docs: add one-task-per-file convention for multi-agent concurrency

多个 agent 并发时抢改单一看板/进度文件会导致读到旧版本、ID 撞号、合并冲突。
新增 docs/tasks/(README 约定 + _template):一任务一文件、frontmatter、防撞号、
执行记录写进任务文件、不逐任务改共享收尾文件。method-map 增对应失败模式行;
06-tasks/00-ai-start-here 加多 agent 分支;README/docs/README 登记;tasks.md 记 H-407。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
chengma
2026-07-08 15:00:07 +08:00
co-authored by Claude Opus 4.8
parent 791211363e
commit ef288b0021
8 changed files with 90 additions and 2 deletions
+51
View File
@@ -0,0 +1,51 @@
# 任务文件(一任务一文件 · 多 agent 并发)
> 适用场景:**多个 agent(或人 + agent)并发在同一仓库工作**时,避免所有人抢改同一个 `docs/06-tasks.md` 看板文件。
> 单 agent / 小项目可继续用单文件看板 `docs/06-tasks.md`;并发协作时改用本目录的"一任务一文件"。
## 为什么
单个大看板文件 + 多写者 = 三种冲突:**编辑竞争**(读到旧版本、反复重读)、**ID 撞号**(全局递增号是共享计数器)、**合并冲突**(相邻行改动)。一任务一文件后:改哪个任务只动哪个文件,agent 之间互不抢占;ID 撞号在**新建文件时当场暴露**(文件已存在就换号)。
## 文件命名与 ID
- 文件名:`docs/tasks/T-<编号>.md`(如 `docs/tasks/T-101.md`);同族细分用后缀 `T-101a.md`。
- 分配下一个 ID:取「看板归档 `docs/06-tasks.md` + `docs/tasks/` 现有文件」里最大的 `T-###`,`+1`。
- **建文件即防撞**:若目标编号文件已存在(别的 agent 先建了),改用下一个号,**不要覆盖别人的文件**。
- 模板 `_template.md` 以下划线开头,不是真实任务、不参与编号扫描。
## 每个任务文件的结构(frontmatter + 正文)
```markdown
---
id: T-101
title: 一句话任务名
phase: 1 # 所属阶段,沿用看板的 Phase 编号
deps: [T-100] # 依赖的任务 ID
status: TODO # TODO | DOING | DONE | BLOCKED
created: 【日期】
---
## 问题 / 背景
## 方案
## 验收要点
## 边界(不改什么)
## 执行记录
```
## 领取 / 完成流程
- 状态:`TODO` · `DOING`(同一时间最多 1 个)· `DONE` · `BLOCKED`。
- 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务,取编号最靠前的;做完自测、按「passing 需证据」把验证命令与结果写清、改 `status: DONE`。
- **执行记录写进本任务文件的 `## 执行记录` 一节**(改了什么、跑了什么验证、结果、决策)——**不再逐任务追加共享的 `progress.md`、也不再逐任务覆盖 `current-state.md`**(那两个是每任务共享写入点,多 agent 会抢/覆盖)。
- **只改自己那个任务文件**;不要编辑别人正在做的任务文件。
## 看板视图
- 现阶段:`ls docs/tasks/` + 看各文件 frontmatter 的 `status`/`deps` 挑任务。
- 可选:加一个脚本把所有任务文件的 frontmatter 汇总成一张只读看板表,agent 不手改看板。
## 与单文件看板的关系
- 切换到本模式后,把 `docs/06-tasks.md` **冻结为历史归档**(只在订正历史任务状态时才动),新任务只进 `docs/tasks/`。
- `progress.md` 冻结为历史归档;`current-state.md` 不再逐任务手动覆盖,当前状态以各任务 frontmatter 为准,可由脚本汇总生成。