docs: adopt one-task-per-file under docs/tasks to avoid multi-agent contention

- docs/tasks/README.md: 约定(命名 T-###、frontmatter、领取规则、防撞号)
- docs/tasks/_template.md: 新任务模板
- 06-tasks.md 冻结为 T-000~T-549 历史归档,新任务不再加入
- AGENTS.md / docs/README.md: 指向新任务入口 docs/tasks/

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
chengma
2026-07-08 10:15:00 +08:00
co-authored by Claude Opus 4.8
parent b622247a16
commit 3a552b1880
5 changed files with 85 additions and 2 deletions
+55
View File
@@ -0,0 +1,55 @@
# 任务文件(一任务一文件)
> 目的:多个 agent 并发时,避免所有人抢改同一个 `../06-tasks.md`——单大文件 + 多写者会导致「读到旧版本」的编辑冲突和 ID 撞号(本项目已实际发生)。
> 约定:**新任务一律一个文件放这里 `docs/tasks/T-<编号>.md`;不再往 `../06-tasks.md` 加新任务**(它已冻结为历史归档,保留 T-000~T-549)。
## 为什么这样
一任务一文件后:改哪个任务只动哪个文件,agent 之间互不抢占;ID 撞号在**新建文件时当场暴露**(文件已存在就换号),不像往大表塞行、撞了也不知道。
## 文件命名与 ID(方案 1:连续编号)
- 文件名:`docs/tasks/T-<编号>.md`,如 `docs/tasks/T-550.md`;同族细分用后缀 `T-550a.md`。
- 分配下一个 ID:取「`../06-tasks.md` 归档 + `docs/tasks/` 现有文件」里最大的 `T-###`,`+1`。
- **建文件即防撞**:若 `T-550.md` 已存在(别的 agent 先建了),直接改用下一个号(`T-551`),**不要覆盖别人的文件**。
- 模板 `_template.md` 以下划线开头,不是真实任务、不参与编号扫描。
## 每个任务文件的结构(frontmatter + 正文)
```markdown
---
id: T-550
title: 一句话任务名
phase: 7 # 所属阶段,沿用 06-tasks.md 的 Phase 编号
deps: [T-546, T-538] # 依赖的任务 ID(跨归档/新结构都用完整 ID 引用)
status: TODO # TODO | DOING | DONE | BLOCKED
created: 2026-07-08
---
## 问题 / 背景
...
## 方案
...
## 验收要点
...
## 边界(不改什么)
...
```
## 状态与领取流程(同 `../06-tasks.md`「使用规则」)
- 状态:`TODO` · `DOING`(同一时间最多 1 个)· `DONE` · `BLOCKED`。
- 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务,取编号最靠前的;做完自测、改 `status: DONE`、追加 `../../progress.md`、覆盖 `../current-state.md`。
- **只改自己那个任务文件**;不要编辑别人正在做的任务文件。
## 看板视图
- 现阶段:`ls docs/tasks/` + 看各文件 frontmatter 的 `status`/`deps` 挑任务。
- (可选,后续)加一个脚本把所有任务文件汇总成一张看板表,agent 不手改看板。
## 历史归档
- `docs/06-tasks.md` = T-000~T-549 的历史归档,**冻结、不再新增**;只有历史任务需要订正状态时才动它,新任务不进去。
+24
View File
@@ -0,0 +1,24 @@
---
id: T-XXX
title: 一句话任务名
phase: 7
deps: []
status: TODO
created: 2026-07-08
---
## 问题 / 背景
(现象、根因、为什么要做)
## 方案
(怎么改,落到"改哪个文件、改成什么")
## 验收要点
(可验证的完成标准;涉及测试写清跑哪个)
## 边界(不改什么)
(明确不碰的模块/流程:DB schema、CDP/Shopee、Excel 等)