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
+2 -1
View File
@@ -28,7 +28,8 @@
- 正式代码统一放入 `app/` 包;迁移完成后复用 `app/cdp.py`,遵守架构第七节的选择器、就绪判断、上传/拖拽方式,不另起一套 CDP 交互。
- 只做当前任务范围内的事;T-504 已接入的多账号并行、dry-run、运行日志属于当前范围,其他 V2 / V3 功能只记录不实现。
- CDP 选择器 / 流程 / 配置 schema 变化,必须同步更新 `docs/04-architecture.md` 与相关任务。
- 改完后更新任务状态、追加 `progress.md`、覆盖 `docs/current-state.md`。
- **新任务一任务一文件写进 `docs/tasks/T-<编号>.md`,不再手改 `docs/06-tasks.md`**(已冻结为 T-000~T-549 历史归档);命名/frontmatter/领取规则见 `docs/tasks/README.md`。为避免多 agent 并发抢改同一文件、ID 撞号。
- 改完后更新对应任务文件状态、追加 `progress.md`、覆盖 `docs/current-state.md`。
## 安全红线
+2
View File
@@ -1,6 +1,8 @@
# 任务看板(Tasks)
> 把目标拆成小步、可独立交付的任务,让 AI 一步一步开发,避免一次生成整个项目。
>
> **⚠️ 本文件已冻结为历史归档(T-000~T-549)。新任务不再加到这里**——为避免多 agent 并发抢改同一文件、ID 撞号,**新任务一律一任务一文件放 [`tasks/`](tasks/)**(`docs/tasks/T-<编号>.md`),约定见 [`tasks/README.md`](tasks/README.md)。只有订正历史任务状态时才改本文件。
## 使用规则
+2 -1
View File
@@ -17,7 +17,8 @@
- [技术栈](03-tech-stack.md):语言、运行平台、CDP 方案、GUI 选型和运行命令。
- [架构设计](04-architecture.md):模块职责、账号与配置目录数据模型、CDP 已验证事实和开发顺序。
- [编码规则](05-coding-rules.md):写代码前必须遵守的硬约束。
- [任务看板](06-tasks.md):按依赖拆分的小任务,agent 每轮只做一个。
- [任务文件](tasks/README.md):**新任务入口**——一任务一文件 `docs/tasks/T-<编号>.md`,避免多 agent 并发抢改同一文件、ID 撞号。
- [任务看板(历史归档)](06-tasks.md):T-000~T-549 历史任务,已冻结,不再新增。
- [模块 / CLI 合约](api.md):本地模块接口、Chrome 启动参数、账号配置 schema。
- [界面与流程结构](routes.md):GUI 窗口、操作流程、按钮职责(无前端路由,用 GUI 流程替代)。
- [当前实现状态](current-state.md):当前代码现实、可运行命令、下一步可做任务。
+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 等)