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:
chengma
2026-07-13 09:34:48 +08:00
co-authored by Claude Fable 5
parent 58ebb1fe26
commit 795a852aa9
15 changed files with 138 additions and 138 deletions
+10 -10
View File
@@ -2,7 +2,7 @@
本仓库用于沉淀一个新项目交给 AI coding agent 开发前,建议准备的文档集合。
这些文档参考了 `D:\opc_project\lingo\docs` 的实际项目文档结构,抽象为可复用模板:从项目入口、愿景、需求、技术栈、架构、编码规则,到任务看板、执行进度、API、路由和当前状态。
这些文档参考了 `D:\opc_project\lingo\docs` 的实际项目文档结构,抽象为可复用模板:从项目入口、愿景、需求、技术栈、架构、编码规则,到任务路线图、任务文件、API、路由和当前状态。
## 推荐文档集合
@@ -13,7 +13,7 @@
| [`tasks.md`](tasks.md) | 本样本库自身的维护任务列表 |
| [`init.sh`](init.sh) | 标准启动与验证入口脚本(Unix shell / WSL / Git Bash),统一安装 + 验证 + 打印启动命令 |
| [`init.ps1`](init.ps1) | 标准启动与验证入口脚本(Windows 原生 PowerShell),与 `init.sh` 等价,按操作系统二选一 |
| [`progress.md`](progress.md) | 复制到新项目后的执行历史流水,记录任务执行、验证、阻塞和决策 |
| [`progress.md`](progress.md) | 可选:历史归档 / 项目级大事记;执行记录默认写各任务文件 |
| [`docs/README.md`](docs/README.md) | 文档导航,总览所有项目文档 |
| [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md) | AI coding agent 的入口、阅读顺序、任务领取规则 |
| [`docs/01-vision.md`](docs/01-vision.md) | 项目为什么做、为谁做、什么不做 |
@@ -21,8 +21,8 @@
| [`docs/03-tech-stack.md`](docs/03-tech-stack.md) | 技术选型和运行命令 |
| [`docs/04-architecture.md`](docs/04-architecture.md) | 系统结构、职责边界、数据模型、开发顺序 |
| [`docs/05-coding-rules.md`](docs/05-coding-rules.md) | AI 写代码前必须遵守的硬规则 |
| [`docs/06-tasks.md`](docs/06-tasks.md) | 可逐步交付的任务看板(单 agent / 小项目) |
| [`docs/tasks/README.md`](docs/tasks/README.md) | 一任务一文件约定:多 agent 并发时避免抢改同一看板/进度文件 |
| [`docs/06-tasks.md`](docs/06-tasks.md) | 任务路线图:阶段划分、里程碑、待办池(只读,不跟踪单任务状态) |
| [`docs/tasks/README.md`](docs/tasks/README.md) | 默认任务管理:一任务一文件 `docs/tasks/T-<编号>.md`,单/多 agent 通用 |
| [`docs/adoption-checklist.md`](docs/adoption-checklist.md) | 已有项目接入 harness 文档的迁移清单 |
| [`docs/api.md`](docs/api.md) | API 合约模板 |
| [`docs/routes.md`](docs/routes.md) | 页面路由、组件归属、导航规则 |
@@ -43,25 +43,25 @@
- `docs/00-ai-start-here.md`
- `docs/05-coding-rules.md`
- `docs/06-tasks.md`
- `docs/tasks/`(`README.md` + `_template.md`)
- `docs/current-state.md`
- `progress.md`
- `init.sh` 或 `init.ps1`
### 完整推荐集
新项目从零开始时,建议复制根目录入口文件、`docs/` 目录、`progress.md`,并按操作系统选择 `init.sh` 或 `init.ps1`。复制后按顺序处理:
新项目从零开始时,建议复制根目录入口文件和 `docs/` 目录(含 `docs/tasks/`),并按操作系统选择 `init.sh` 或 `init.ps1`。复制后按顺序处理:
1. 从 `docs/01-vision.md` 和 `docs/02-requirements.md` 开始替换业务内容。
2. 在 `docs/03-tech-stack.md` 固定技术选型,不确定的选项标为待定。
3. 在 `docs/04-architecture.md` 写清事实来源、数据模型、系统边界。
4. 在 `docs/06-tasks.md` 拆出小任务,要求 AI 每轮只领取一个任务。
4. 在 `docs/06-tasks.md` 拆出阶段路线图和建议任务;开工时按 `docs/tasks/README.md` 把任务落成 `docs/tasks/T-<编号>.md`,要求 AI 每轮只领取一个任务。
5. 替换 `init.sh` 或 `init.ps1` 顶部三个命令,并把真实命令同步到 `docs/03-tech-stack.md`、`docs/00-ai-start-here.md` 和 `docs/current-state.md`。
6. 用 `progress.md` 追加记录每轮执行历史,用 `docs/current-state.md` 覆盖更新当前快照。
6. 执行记录写进各任务文件的 `## 执行记录`,用 `docs/current-state.md` 覆盖更新当前快照;`progress.md` 可选,用作历史归档或项目级大事记。
7. 开始编码前,让 agent 先读 `docs/00-ai-start-here.md`。
### 已有项目接入
已有代码仓库不要急着让 agent 做新功能。先按 [`docs/adoption-checklist.md`](docs/adoption-checklist.md) 建立当前状态、启动路径、验证路径和任务看板;第一轮任务优先修复基线,而不是扩大功能范围。
已有代码仓库不要急着让 agent 做新功能。先按 [`docs/adoption-checklist.md`](docs/adoption-checklist.md) 建立当前状态、启动路径、验证路径和任务文件;第一轮任务优先修复基线,而不是扩大功能范围。
### 可选增强集
@@ -72,6 +72,6 @@
- `docs/evaluator-rubric.md`:评审单次 agent 输出质量。
- `docs/quality-document.md`:追踪代码库长期健康度。
`tasks.md` 是本样本库自身的维护任务;复制到新项目后,项目任务默认写在 `docs/06-tasks.md`。如果新项目希望把任务看板放在根目录,可把 `docs/06-tasks.md` 复制或改名为根目录 `tasks.md`,并同步更新 `docs/README.md`、`docs/00-ai-start-here.md` 和 `docs/current-state.md` 中的链接。
`tasks.md` 是本样本库自身的维护任务;复制到新项目后,项目任务默认以一任务一文件写在 `docs/tasks/`,阶段路线图维护在 `docs/06-tasks.md`。
核心原则:文档不是给人看的装饰,而是给 agent 执行时用的约束、事实来源和验收标准。