2026-07-08 15:00:07 +08:00
|
|
|
|
# 任务文件（一任务一文件 · 多 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 会抢/覆盖）。
|
|
|
|
|
|
- **只改自己那个任务文件**；不要编辑别人正在做的任务文件。
|
|
|
|
|
|
|
2026-07-09 16:57:29 +08:00
|
|
|
|
## 用户指令暗语（可选约定）
|
|
|
|
|
|
|
|
|
|
|
|
> 用户的工作流通常固定为：提 bug/需求 → 讨论定案 → 落成任务文件 → 提交 → 实现 → 提交。
|
|
|
|
|
|
> 为减少重复输入，可约定以下触发词；agent 读到即按约定执行。默认值：不注明视角就是全栈工程师视角；每步产物默认提交 git（只提交本次相关文件）。
|
|
|
|
|
|
|
|
|
|
|
|
| 用户输入 | agent 执行 |
|
|
|
|
|
|
| --- | --- |
|
|
|
|
|
|
| `bug: <现象>` / `需求: <描述>` | 先查代码再给分析和方案，**只讨论不改代码** |
|
|
|
|
|
|
| `grill: <方案>` | 反方评审，逐点挑战该方案 |
|
|
|
|
|
|
| `落task` | 把已讨论定案落成 `docs/tasks/T-<编号>.md`（按上述规则查号防撞），**只写文档不写代码，写完自动提交 git** |
|
|
|
|
|
|
| `审 T-<编号>` | 先核代码事实，再审核该任务文件最近的更新是否合理、给缺口 |
|
|
|
|
|
|
| `补` | 把讨论新增的结论补进当前任务文件并提交 git |
|
|
|
|
|
|
| `做 T-<编号>` | 实现该任务 + 跑任务内验证命令 + 执行记录写进任务文件 + 提交 git |
|
|
|
|
|
|
|
|
|
|
|
|
采用时把这套暗语同时写进项目的 `AGENTS.md` 工作规则，保证所有 agent 认同一套指令；触发词可按团队习惯改名，关键是「一个词 = 一个流程阶段 + 默认动作」。
|
|
|
|
|
|
|
2026-07-08 15:00:07 +08:00
|
|
|
|
## 看板视图
|
|
|
|
|
|
|
|
|
|
|
|
- 现阶段：`ls docs/tasks/` + 看各文件 frontmatter 的 `status`/`deps` 挑任务。
|
|
|
|
|
|
- 可选：加一个脚本把所有任务文件的 frontmatter 汇总成一张只读看板表，agent 不手改看板。
|
|
|
|
|
|
|
|
|
|
|
|
## 与单文件看板的关系
|
|
|
|
|
|
|
|
|
|
|
|
- 切换到本模式后，把 `docs/06-tasks.md` **冻结为历史归档**（只在订正历史任务状态时才动），新任务只进 `docs/tasks/`。
|
|
|
|
|
|
- `progress.md` 冻结为历史归档；`current-state.md` 不再逐任务手动覆盖，当前状态以各任务 frontmatter 为准，可由脚本汇总生成。
|
