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>

README.md

@@ -21,7 +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) | 可逐步交付的任务看板 |
+| [`docs/06-tasks.md`](docs/06-tasks.md) | 可逐步交付的任务看板（单 agent / 小项目） |
+| [`docs/tasks/README.md`](docs/tasks/README.md) | 一任务一文件约定：多 agent 并发时避免抢改同一看板/进度文件 |
 | [`docs/adoption-checklist.md`](docs/adoption-checklist.md) | 已有项目接入 harness 文档的迁移清单 |
 | [`docs/api.md`](docs/api.md) | API 合约模板 |
 | [`docs/routes.md`](docs/routes.md) | 页面路由、组件归属、导航规则 |

docs/00-ai-start-here.md

@@ -59,6 +59,8 @@
 - 结束会话前过一遍 [`clean-state-checklist.md`](clean-state-checklist.md)，确保下一轮无需人工修复即可开工。
 - 做完即停，汇报验证结果，等待下一步指令。
 
+> **多 agent / 并发协作**：若项目已切到一任务一文件（见 [`tasks/README.md`](tasks/README.md)），则从 `docs/tasks/` 领取任务文件、状态改在 frontmatter、**执行记录写进该任务文件的 `## 执行记录`**，不再逐任务追加 `progress.md`/覆盖 `current-state.md`（避免多写者抢占共享文件）。
+
 如果代码实际状态和任务看板冲突，先说明冲突，不要擅自跳步或重排。
 
 ## MVP 边界

docs/06-tasks.md

@@ -12,6 +12,8 @@
 6. **动手前**先读 `00-ai-start-here.md`、`05-coding-rules.md` 和 `current-state.md`。
 7. **完成后**把任务状态同步到本文，把执行记录追加到 [`../progress.md`](../progress.md)，覆盖更新 [`current-state.md`](current-state.md)，并过一遍 [`clean-state-checklist.md`](clean-state-checklist.md)。
 
+> **多 agent / 并发协作**：当多个 agent（或人 + agent）并发在同一仓库工作时，单文件看板会被抢改（读到旧版本、ID 撞号、合并冲突）。此时改用 **一任务一文件** [`tasks/README.md`](tasks/README.md)（`docs/tasks/T-<编号>.md`）：新任务只进 `docs/tasks/`、执行记录写进各自任务文件的 `## 执行记录`、不再逐任务追加 `progress.md`/覆盖 `current-state.md`；本单文件看板转为历史归档。单 agent / 小项目继续用本文即可。
+
 如新项目希望任务看板放在根目录，可把本文复制或改名为根目录 `tasks.md`，并同步更新 `README.md`、`docs/README.md`、`00-ai-start-here.md` 和 `current-state.md` 的链接。
 
 ## 状态图例

docs/README.md

@@ -22,7 +22,8 @@
 - [技术栈](03-tech-stack.md)：确定使用哪些框架、库、数据库、部署方式。
 - [架构设计](04-architecture.md)：系统结构、模块职责、数据模型、关键风险和开发顺序。
 - [编码规则](05-coding-rules.md)：AI 写代码前必须遵守的硬约束。
-- [任务看板](06-tasks.md)：按依赖拆分的小任务，agent 每轮只做一个。
+- [任务看板](06-tasks.md)：按依赖拆分的小任务，agent 每轮只做一个（单 agent / 小项目）。
+- [任务文件（多 agent 并发）](tasks/README.md)：一任务一文件 `docs/tasks/T-<编号>.md`，多 agent 并发时避免抢改同一看板/进度文件。
 - [已有项目接入清单](adoption-checklist.md)：把本模板补进已有代码库时的迁移步骤和第一轮任务建议。
 - [API 合约](api.md)：前后端接口形状、错误格式、鉴权约定。
 - [路由与页面结构](routes.md)：页面路由、页面职责、组件归属。

docs/method-map.md

@@ -15,6 +15,7 @@
 | 评审主观 | 质量判断靠个人记忆和感觉，agent 容易自我说服通过 | 用固定维度做评分 | [`evaluator-rubric.md`](evaluator-rubric.md) |
 | 代码库悄悄退化 | 速度上去了，但几轮会话后代码越来越难审、边界越来越糊 | 定期给代码库健康度打分 | [`quality-document.md`](quality-document.md) |
 | 文档堆叠失控 | 入口文件越来越长，"每次失败加一句" | 渐进披露，入口保持薄 | [`00-ai-start-here.md`](00-ai-start-here.md) + 拆分到具体文档 |
+| 多 agent 抢改任务文件 | 多个 agent 并发时抢改同一个看板/进度文件，出现"读到旧版本"、ID 撞号、合并冲突 | 一任务一文件，执行记录进任务文件，不逐任务改共享收尾文件 | [`tasks/README.md`](tasks/README.md) |
 
 ## 使用原则
 

docs/tasks/README.md

@@ -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 为准，可由脚本汇总生成。

docs/tasks/_template.md

@@ -0,0 +1,29 @@
+---
+id: T-XXX
+title: 一句话任务名
+phase: 1
+deps: []
+status: TODO
+created: 【日期】
+---
+
+## 问题 / 背景
+
+（现象、根因、为什么要做）
+
+## 方案
+
+（怎么改，落到"改哪个文件、改成什么"）
+
+## 验收要点
+
+（可验证的完成标准；按「passing 需证据」写清跑哪个验证命令，不写"应该能用"）
+
+## 边界（不改什么）
+
+（明确不碰的模块/流程）
+
+## 执行记录
+
+（做完在此记录：改了哪些文件、跑的验证命令与结果、阻塞、关键决策。
+取代逐任务追加 `progress.md`——执行记录只写进本任务文件，避免多 agent 抢改共享文件。）

tasks.md

@@ -74,6 +74,7 @@ Get-ChildItem -Recurse -File
 | H-403 | 在 `06-tasks.md`/`05-coding-rules.md` 引入“证据绑定完成” | H-107, H-108 | passing 需在 `progress.md` 记录可运行证据，禁止“代码已写即 DONE” | DONE |
 | H-404 | 在 `00-ai-start-here.md` 加固定开工/收尾流程 | H-102 | 含 pwd→读状态→git log→init.sh→smoke 基线→坏先修→领任务，收尾链接检查清单 | DONE |
 | H-405 | 在 `current-state.md` 加启动/验证路径和 blocker 字段 | H-203 | 快照含标准启动路径、标准验证路径、当前 blocker | DONE |
+| H-407 | 增加多 agent 并发任务管理约定 `docs/tasks/` | H-108, H-501 | 新增 `docs/tasks/README.md`（一任务一文件、frontmatter、防撞号、执行记录进任务文件、不逐任务改共享收尾文件）和 `_template.md`；`method-map.md` 增"多 agent 抢改任务文件"失败模式行；`06-tasks.md`/`00-ai-start-here.md` 加多 agent 分支说明；`README.md`/`docs/README.md` 登记；保持通用占位符、不绑业务 | DONE |
 
 ## Phase 5 · Harness 评审与健康度层（Tier 2）