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
co-authored by
Claude Fable 5
Claude Fable 5
parent
58ebb1fe26
commit
795a852aa9
+18
-13
@@ -1,16 +1,19 @@
|
||||
# 任务文件（一任务一文件 · 多 agent 并发）
|
||||
# 任务文件（一任务一文件 · 默认任务管理方式）
|
||||
|
||||
> 适用场景：**多个 agent（或人 + agent）并发在同一仓库工作**时，避免所有人抢改同一个 `docs/06-tasks.md` 看板文件。
|
||||
> 单 agent / 小项目可继续用单文件看板 `docs/06-tasks.md`；并发协作时改用本目录的"一任务一文件"。
|
||||
> 本目录是项目任务的**默认存放位置**：每个任务一个文件 `docs/tasks/T-<编号>.md`，单 agent 与多 agent 并发通用。
|
||||
> 阶段划分、里程碑和待办池见路线图 [`../06-tasks.md`](../06-tasks.md)；路线图只读，不跟踪单任务状态。
|
||||
|
||||
## 为什么
|
||||
## 为什么默认一任务一文件
|
||||
|
||||
单个大看板文件 + 多写者 = 三种冲突：**编辑竞争**（读到旧版本、反复重读）、**ID 撞号**（全局递增号是共享计数器）、**合并冲突**（相邻行改动）。一任务一文件后：改哪个任务只动哪个文件，agent 之间互不抢占；ID 撞号在**新建文件时当场暴露**（文件已存在就换号）。
|
||||
- **单 agent**：领任务只读一个文件就拿到完整上下文（背景、方案、验收、执行记录），不用在看板、进度流水、快照三个共享文件之间跳转同步；执行记录和任务绑定，审查时 `git log -p` 一个文件即可回放全程。
|
||||
- **多 agent 并发**：单个大看板 + 多写者 = **编辑竞争**（读到旧版本、反复重读）、**ID 撞号**（全局递增号是共享计数器）、**合并冲突**（相邻行改动）。一任务一文件后：改哪个任务只动哪个文件，agent 之间互不抢占；ID 撞号在**新建文件时当场暴露**（文件已存在就换号）。
|
||||
- **零迁移**：项目从单 agent 长到多 agent，无需切换任何约定。
|
||||
|
||||
## 文件命名与 ID
|
||||
|
||||
- 文件名：`docs/tasks/T-<编号>.md`（如 `docs/tasks/T-101.md`）；同族细分用后缀 `T-101a.md`。
|
||||
- 分配下一个 ID：取「看板归档 `docs/06-tasks.md` + `docs/tasks/` 现有文件」里最大的 `T-###`，`+1`。
|
||||
- 落实路线图建议任务时，**沿用路线图 `../06-tasks.md` 里的建议编号**（如 T-101）。
|
||||
- 路线图之外的新任务：取「路线图建议编号 + `docs/tasks/` 现有文件」里最大的 `T-###`，`+1`。
|
||||
- **建文件即防撞**：若目标编号文件已存在（别的 agent 先建了），改用下一个号，**不要覆盖别人的文件**。
|
||||
- 模板 `_template.md` 以下划线开头，不是真实任务、不参与编号扫描。
|
||||
|
||||
@@ -20,7 +23,7 @@
|
||||
---
|
||||
id: T-101
|
||||
title: 一句话任务名
|
||||
phase: 1 # 所属阶段，沿用看板的 Phase 编号
|
||||
phase: 1 # 所属阶段，沿用路线图的 Phase 编号
|
||||
deps: [T-100] # 依赖的任务 ID
|
||||
status: TODO # TODO | DOING | DONE | BLOCKED
|
||||
created: 【日期】
|
||||
@@ -36,8 +39,9 @@ created: 【日期】
|
||||
## 领取 / 完成流程
|
||||
|
||||
- 状态：`TODO` · `DOING`（同一时间最多 1 个）· `DONE` · `BLOCKED`。
|
||||
- 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；做完自测、按「passing 需证据」把验证命令与结果写清、改 `status: DONE`。
|
||||
- **执行记录写进本任务文件的 `## 执行记录` 一节**（改了什么、跑了什么验证、结果、决策）——**不再逐任务追加共享的 `progress.md`、也不再逐任务覆盖 `current-state.md`**（那两个是每任务共享写入点，多 agent 会抢/覆盖）。
|
||||
- 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；若本目录暂无可领任务，先按路线图把下一个建议任务落成任务文件，再领取。
|
||||
- 做完自测、按「passing 需证据」把验证命令与结果写清、改 `status: DONE`。
|
||||
- **执行记录写进本任务文件的 `## 执行记录` 一节**（改了什么、跑了什么验证、结果、决策）——不逐任务追加共享的 `progress.md`（可选历史归档）、也不逐任务覆盖 `current-state.md`（项目级快照，只在启动/验证路径、目录结构或 blocker 变化时更新）。
|
||||
- **只改自己那个任务文件**；不要编辑别人正在做的任务文件。
|
||||
|
||||
## 用户指令暗语（可选约定）
|
||||
@@ -53,7 +57,7 @@ created: 【日期】
|
||||
| `审 T-<编号>` | **以 git 历史为准**（`git log -p` 该任务文件找出最近改动），先核代码事实，再审核该改动是否合理、给缺口 |
|
||||
| `补` | 把讨论新增的结论补进当前任务文件并提交 git |
|
||||
| `做 T-<编号>` | 实现该任务 + 跑任务内验证命令；**验证全绿才提交**（执行记录、状态 DONE、提交）；验证失败 → 报告、**不提交**、状态留 DOING 或标 BLOCKED 记原因 |
|
||||
| `记backlog: <一行>` | 追加进待办池（如 `docs/06-tasks.md` Backlog）并提交，只记一行、不建任务文件 |
|
||||
| `记backlog: <一行>` | 追加进待办池（`docs/06-tasks.md` Backlog）并提交，只记一行、不建任务文件 |
|
||||
|
||||
补充规则：
|
||||
|
||||
@@ -66,7 +70,8 @@ created: 【日期】
|
||||
- 现阶段：`ls docs/tasks/` + 看各文件 frontmatter 的 `status`/`deps` 挑任务。
|
||||
- 可选：加一个脚本把所有任务文件的 frontmatter 汇总成一张只读看板表，agent 不手改看板。
|
||||
|
||||
## 与单文件看板的关系
|
||||
## 与路线图和共享文件的关系
|
||||
|
||||
- 切换到本模式后，把 `docs/06-tasks.md` **冻结为历史归档**（只在订正历史任务状态时才动），新任务只进 `docs/tasks/`。
|
||||
- `progress.md` 冻结为历史归档；`current-state.md` 不再逐任务手动覆盖，当前状态以各任务 frontmatter 为准，可由脚本汇总生成。
|
||||
- [`../06-tasks.md`](../06-tasks.md)：只读路线图（Phase 划分、里程碑、Backlog、建议拆分清单）；真实任务状态一律以本目录任务文件的 frontmatter 为准。
|
||||
- `../../progress.md`：可选工件，用作历史归档或项目级大事记；执行记录写各任务文件，不逐任务追加。
|
||||
- [`../current-state.md`](../current-state.md)：项目级快照（启动/验证路径、目录要点、blocker）；任务状态不在此维护，可由脚本汇总 frontmatter 生成。
|
||||
|
||||
@@ -26,4 +26,4 @@ created: 【日期】
|
||||
## 执行记录
|
||||
|
||||
（做完在此记录：改了哪些文件、跑的验证命令与结果、阻塞、关键决策。
|
||||
取代逐任务追加 `progress.md`——执行记录只写进本任务文件，避免多 agent 抢改共享文件。）
|
||||
执行记录只写进本任务文件，不逐任务追加共享的 `progress.md`，避免多 agent 抢改共享文件。）
|
||||
|
||||
Reference in New Issue
Block a user