docs(tasks): make one-task-per-file the default task mode (H-409)
- docs/tasks/README.md: default mode for single and multi agent, drop switch narrative - docs/06-tasks.md: demote to read-only roadmap (phases, milestones, backlog, suggested split list without status) - progress.md: optional archive / project-level event log; execution records live in task files - current-state.md: project-level snapshot; task status authoritative in task frontmatter - sync all referencing docs (start-here, coding-rules, READMEs, adoption/clean-state checklists, method-map, evaluator-rubric) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Fable 5
parent
58ebb1fe26
commit
795a852aa9
@@ -4,7 +4,7 @@
|
||||
|
||||
## 适用场景
|
||||
|
||||
- 项目已经有代码,但缺少清晰的 agent 入口、任务看板、当前状态和验证路径。
|
||||
- 项目已经有代码,但缺少清晰的 agent 入口、任务文件、当前状态和验证路径。
|
||||
- 项目被多轮 AI 修改过,文档、代码和真实可运行状态已经不一致。
|
||||
- 想从“靠聊天记录推进”切换到“靠仓库内工件推进”。
|
||||
|
||||
@@ -20,12 +20,12 @@
|
||||
| `CLAUDE.md` | Claude Code 薄入口,指向 `AGENTS.md` |
|
||||
| `docs/00-ai-start-here.md` | 每轮开工流程 |
|
||||
| `docs/05-coding-rules.md` | 编码纪律和验证底线 |
|
||||
| `docs/06-tasks.md` | 任务看板 |
|
||||
| `docs/06-tasks.md` | 任务路线图(阶段、里程碑、待办池) |
|
||||
| `docs/tasks/` | 默认任务管理:一任务一文件(`README.md` + `_template.md`) |
|
||||
| `docs/current-state.md` | 当前实现状态快照 |
|
||||
| `progress.md` | 只追加的执行流水 |
|
||||
| `init.sh` 或 `init.ps1` | 标准启动与验证入口,按操作系统二选一 |
|
||||
|
||||
推荐随后补齐:`docs/01-vision.md`、`docs/02-requirements.md`、`docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/api.md`、`docs/routes.md`、`docs/clean-state-checklist.md`。
|
||||
推荐随后补齐:`docs/01-vision.md`、`docs/02-requirements.md`、`docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/api.md`、`docs/routes.md`、`docs/clean-state-checklist.md`;`progress.md` 可选(历史归档 / 项目级大事记)。
|
||||
|
||||
## 接入步骤
|
||||
|
||||
@@ -34,10 +34,10 @@
|
||||
3. 在 `docs/current-state.md` 写清真实目录、真实启动命令、真实验证命令、当前 blocker。
|
||||
4. 在 `docs/03-tech-stack.md` 固定已经实际使用的技术栈,不确定项标为“待定”,不要让 agent 自行选择。
|
||||
5. 在 `docs/04-architecture.md` 记录当前代码的真实模块边界;不清楚的地方标为“待确认”。
|
||||
6. 在 `docs/06-tasks.md` 只放下一阶段能小步交付的任务,不要把历史愿望清单全部搬进去。
|
||||
6. 在 `docs/06-tasks.md` 只放下一阶段能小步交付的建议任务,不要把历史愿望清单全部搬进去;第一轮任务按 `docs/tasks/README.md` 落成 `docs/tasks/T-<编号>.md`。
|
||||
7. 配置 `init.sh` 或 `init.ps1` 顶部三个命令,让它能安装依赖、运行基础验证、打印启动命令。
|
||||
8. 运行标准验证;如果失败,第一轮任务应先修基线,不做新功能。
|
||||
9. 把接入过程、验证结果和遗留 blocker 追加到 `progress.md`。
|
||||
9. 把接入过程、验证结果写进第一轮任务文件的 `## 执行记录`,遗留 blocker 同步到 `docs/current-state.md`。
|
||||
|
||||
## 第一轮 agent 任务建议
|
||||
|
||||
@@ -45,16 +45,16 @@
|
||||
|
||||
| ID | 任务 | 验收要点 |
|
||||
| --- | --- | --- |
|
||||
| T-000 | 建立当前状态基线 | `current-state.md` 写清真实状态;`init` 脚本已配置;基础验证结果已记录到 `progress.md` |
|
||||
| T-000 | 建立当前状态基线 | `current-state.md` 写清真实状态;`init` 脚本已配置;基础验证结果已记录到本任务文件的 `## 执行记录` |
|
||||
| T-001 | 修复启动 / 验证基线 | 标准启动路径和标准验证路径可运行;失败原因已消除或记录为 blocker |
|
||||
| T-002 | 对齐任务看板 | `06-tasks.md` 只保留可执行的小任务;第一个 TODO 依赖清楚、验收可观察 |
|
||||
| T-002 | 对齐任务路线图 | `06-tasks.md` 只保留可小步交付的建议任务;第一个待落地任务依赖清楚、验收可观察 |
|
||||
|
||||
## 代码现实与文档冲突时
|
||||
|
||||
- 以当前可运行代码和真实验证结果为事实起点。
|
||||
- 文档描述旧功能但代码不存在时,先把差异记录到 `current-state.md`,不要直接补实现。
|
||||
- 代码已有行为但文档没写时,先补 `02-requirements.md`、`04-architecture.md` 或 `api.md`,再继续修改代码。
|
||||
- 命令不可运行时,不要标记任务完成;在 `progress.md` 记录失败命令和错误摘要。
|
||||
- 命令不可运行时,不要标记任务完成;在当前任务文件的 `## 执行记录` 记录失败命令和错误摘要。
|
||||
|
||||
## 不建议做的事
|
||||
|
||||
|
||||
Reference in New Issue
Block a user