From ef288b0021d351a76b0d2db89259447881c73991 Mon Sep 17 00:00:00 2001 From: chengma Date: Wed, 8 Jul 2026 15:00:07 +0800 Subject: [PATCH] docs: add one-task-per-file convention for multi-agent concurrency MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 多个 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 --- README.md | 3 ++- docs/00-ai-start-here.md | 2 ++ docs/06-tasks.md | 2 ++ docs/README.md | 3 ++- docs/method-map.md | 1 + docs/tasks/README.md | 51 ++++++++++++++++++++++++++++++++++++++++ docs/tasks/_template.md | 29 +++++++++++++++++++++++ tasks.md | 1 + 8 files changed, 90 insertions(+), 2 deletions(-) create mode 100644 docs/tasks/README.md create mode 100644 docs/tasks/_template.md diff --git a/README.md b/README.md index 17872f1..fb3bd5e 100644 --- a/README.md +++ b/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) | 页面路由、组件归属、导航规则 | diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md index 31eb6f0..8d51c0e 100644 --- a/docs/00-ai-start-here.md +++ b/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 边界 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 9134b28..4587776 100644 --- a/docs/06-tasks.md +++ b/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` 的链接。 ## 状态图例 diff --git a/docs/README.md b/docs/README.md index 746a670..ccd183b 100644 --- a/docs/README.md +++ b/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)：页面路由、页面职责、组件归属。 diff --git a/docs/method-map.md b/docs/method-map.md index f2de077..36af2d6 100644 --- a/docs/method-map.md +++ b/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) | ## 使用原则 diff --git a/docs/tasks/README.md b/docs/tasks/README.md new file mode 100644 index 0000000..9cb4e37 --- /dev/null +++ b/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 为准，可由脚本汇总生成。 diff --git a/docs/tasks/_template.md b/docs/tasks/_template.md new file mode 100644 index 0000000..3a48909 --- /dev/null +++ b/docs/tasks/_template.md @@ -0,0 +1,29 @@ +--- +id: T-XXX +title: 一句话任务名 +phase: 1 +deps: [] +status: TODO +created: 【日期】 +--- + +## 问题 / 背景 + +（现象、根因、为什么要做） + +## 方案 + +（怎么改，落到"改哪个文件、改成什么"） + +## 验收要点 + +（可验证的完成标准；按「passing 需证据」写清跑哪个验证命令，不写"应该能用"） + +## 边界（不改什么） + +（明确不碰的模块/流程） + +## 执行记录 + +（做完在此记录：改了哪些文件、跑的验证命令与结果、阻塞、关键决策。 +取代逐任务追加 `progress.md`——执行记录只写进本任务文件，避免多 agent 抢改共享文件。） diff --git a/tasks.md b/tasks.md index 60d0277..945a733 100644 --- a/tasks.md +++ b/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）