2026-07-16 14:33:43 +08:00
|
|
|
|
# 任务文件（一任务一文件 · 默认任务管理方式）
|
|
|
|
|
|
|
2026-07-16 20:42:32 +08:00
|
|
|
|
> 本目录是项目任务的**默认存放位置**：每个任务一个文件 `docs/tasks/T-<编号>.md`。当前项目使用单 Agent 串行执行。
|
2026-07-16 14:33:43 +08:00
|
|
|
|
> 阶段划分、里程碑和待办池见路线图 [`../06-tasks.md`](../06-tasks.md)；路线图只读，不跟踪单任务状态。
|
|
|
|
|
|
|
|
|
|
|
|
## 为什么默认一任务一文件
|
|
|
|
|
|
|
|
|
|
|
|
- **单 agent**：领任务只读一个文件就拿到完整上下文（背景、方案、验收、执行记录），不用在看板、进度流水、快照三个共享文件之间跳转同步；执行记录和任务绑定，审查时 `git log -p` 一个文件即可回放全程。
|
2026-07-16 20:42:32 +08:00
|
|
|
|
- **低上下文成本**：一任务一文件让单 Agent 只读取当前任务规格和执行记录,减少跨文件同步与重复检索。
|
|
|
|
|
|
- **保留扩展性**：如果未来由用户明确重新启用多 Agent,现有任务文件仍可作为写路径和依赖边界;重新启用前必须先更新并提交协作规则。
|
2026-07-16 14:33:43 +08:00
|
|
|
|
|
|
|
|
|
|
## 文件命名与 ID
|
|
|
|
|
|
|
|
|
|
|
|
- 文件名：`docs/tasks/T-<编号>.md`（如 `docs/tasks/T-101.md`）；同族细分用后缀 `T-101a.md`。
|
|
|
|
|
|
- 落实路线图建议任务时，**沿用路线图 `../06-tasks.md` 里的建议编号**（如 T-101）。
|
|
|
|
|
|
- 路线图之外的新任务：取「路线图建议编号 + `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: 【日期】
|
|
|
|
|
|
issue: null # Gitea Issue 编号；未启用 Gitea 时保持 null
|
|
|
|
|
|
context_ref: null # 领取时默认分支提交 SHA
|
|
|
|
|
|
claim_branch: null
|
|
|
|
|
|
work_branch: null
|
|
|
|
|
|
write_paths: # 允许修改的仓库相对路径
|
|
|
|
|
|
- docs/tasks/T-101.md
|
|
|
|
|
|
- 【path/to/module】
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 问题 / 背景
|
|
|
|
|
|
## 方案
|
|
|
|
|
|
## 验收要点
|
|
|
|
|
|
## 边界（不改什么）
|
|
|
|
|
|
## 协作约束
|
|
|
|
|
|
## 执行记录
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 领取 / 完成流程
|
|
|
|
|
|
|
2026-07-16 20:42:32 +08:00
|
|
|
|
- 状态：`TODO` · `DOING` · `DONE` · `BLOCKED`。项目同一时间只保留一个活跃任务。
|
|
|
|
|
|
- 单 Agent 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；若本目录暂无可领任务，先按路线图把下一个建议任务落成任务文件，再领取。
|
|
|
|
|
|
- `write_paths` 必须在动手前写清,用于约束本任务允许修改和提交的路径。
|
2026-07-16 14:33:43 +08:00
|
|
|
|
- 做完自测、按「passing 需证据」把验证命令与结果写清、改 `status: DONE`。
|
|
|
|
|
|
- **执行记录写进本任务文件的 `## 执行记录` 一节**（改了什么、跑了什么验证、结果、决策）——不逐任务追加共享的 `progress.md`（可选历史归档）、也不逐任务覆盖 `current-state.md`（项目级快照，只在启动/验证路径、目录结构或 blocker 变化时更新）。
|
2026-07-16 20:42:32 +08:00
|
|
|
|
- **只改当前任务文件**；不要顺带修改其他任务的状态或执行记录。
|
2026-07-16 14:33:43 +08:00
|
|
|
|
|
2026-07-16 20:42:32 +08:00
|
|
|
|
### 当前单 Agent 模式
|
2026-07-16 18:48:15 +08:00
|
|
|
|
|
2026-07-16 20:42:32 +08:00
|
|
|
|
1. 当前 Agent 负责从任务落文档到最终提交的完整生命周期,不启动或委派子 Agent。
|
|
|
|
|
|
2. 测试设计、安全检查、代码审查和提交前复核由当前 Agent 分阶段执行,结果统一写入任务执行记录。
|
|
|
|
|
|
3. 前一个任务达到 `DONE`、完整验证通过并提交后,才正式落成或领取下一个依赖任务。
|
|
|
|
|
|
4. 若用户以后明确恢复多 Agent,必须先修改并提交 `AGENTS.md`、本文和当前任务的协作约束;在该文档提交之前不得启动子 Agent。
|
2026-07-16 18:48:15 +08:00
|
|
|
|
|
2026-07-16 14:33:43 +08:00
|
|
|
|
未启用 Gitea 时，在独立分支 / worktree 中把任务文件从 `TODO` 改为 `DOING` 即可。启用 Gitea 时，必须先按 [`../gitea-collaboration.md`](../gitea-collaboration.md) 由 dispatcher 串行分配并创建 `claims/T-<编号>` 防御性标记；assignee、标签、读回和普通 create-branch API 都不能单独提供并发互斥。
|
|
|
|
|
|
|
|
|
|
|
|
## 与 Gitea Issue / PR 的映射（可选）
|
|
|
|
|
|
|
|
|
|
|
|
- 一个任务文件对应一个主 Issue；Issue 负责实时领取、阻塞和评审状态，任务文件负责版本化规格和长期证据。
|
|
|
|
|
|
- 先把任务文件合入默认分支，再创建 Issue；随后把 Issue 编号回填任务文件并合入默认分支，最后才添加 `status/todo`。映射未完成的 Issue 不可领取。
|
|
|
|
|
|
- Issue、claim 分支、工作分支和 PR 都携带同一个 `T-<编号>`；不得用一个 PR 顺带完成多个任务。
|
|
|
|
|
|
- 工作分支命名为 `agent/<agent-id>/T-<编号>`，每个 agent 使用独立 worktree。
|
|
|
|
|
|
- MVP 由一个 dispatcher / 主 agent 串行分配任务，以此保证同一任务不被重复领取，并保证不同任务的 `write_paths` 不冲突。唯一 claim 分支只拦截顺序重试和常见旁路，不能替代 dispatcher 的互斥保证。
|
|
|
|
|
|
- 进入评审后 Issue 使用唯一 `status/review`；PR 合并且默认分支任务文件为 `DONE` 后，Issue 才能关闭并标记 `status/done`。
|
|
|
|
|
|
- 领取、结构化 claim 评论、过期锁回收和分支清理的完整规则见 [`../gitea-collaboration.md`](../gitea-collaboration.md)。
|
|
|
|
|
|
|
|
|
|
|
|
## 用户指令暗语（可选约定）
|
|
|
|
|
|
|
|
|
|
|
|
> 用户的工作流通常固定为：提 bug/需求 → 讨论定案 → 落成任务文件 → 提交 → 实现 → 提交。
|
|
|
|
|
|
> 为减少重复输入，可约定以下触发词；agent 读到即按约定执行。默认值：不注明视角就是全栈工程师视角；每步产物默认提交 git（只提交本次相关文件）。
|
|
|
|
|
|
|
|
|
|
|
|
| 用户输入 | agent 执行 |
|
|
|
|
|
|
| --- | --- |
|
|
|
|
|
|
| `bug: <现象>` / `需求: <描述>` | 先查代码再给分析和方案，**只讨论不改代码** |
|
|
|
|
|
|
| `grill: <方案>` | 反方评审，逐点挑战该方案 |
|
|
|
|
|
|
| `落task` | 把已讨论定案落成 `docs/tasks/T-<编号>.md`（按上述规则查号防撞），**只写文档不写代码，写完自动提交 git** |
|
|
|
|
|
|
| `审 T-<编号>` | **以 git 历史为准**（`git log -p` 该任务文件找出最近改动），先核代码事实，再审核该改动是否合理、给缺口 |
|
|
|
|
|
|
| `补` | 把讨论新增的结论补进当前任务文件并提交 git |
|
|
|
|
|
|
| `做 T-<编号>` | 实现该任务 + 跑任务内验证命令；**验证全绿才提交**（执行记录、状态 DONE、提交）；验证失败 → 报告、**不提交**、状态留 DOING 或标 BLOCKED 记原因 |
|
|
|
|
|
|
| `记backlog: <一行>` | 追加进待办池（`docs/06-tasks.md` Backlog）并提交，只记一行、不建任务文件 |
|
|
|
|
|
|
|
|
|
|
|
|
补充规则：
|
|
|
|
|
|
|
|
|
|
|
|
- `落task`/`补` 可带参数（`落task <主题>`、`补 T-<编号>`）；新会话或无对话上下文时 agent **必须先问清指代对象，不得猜**。
|
|
|
|
|
|
- 采用时把这套暗语同时写进项目的 `AGENTS.md` 工作规则，并**声明 `AGENTS.md` 为唯一权威源**（agent 记忆、模板副本仅为指针/种子）——多副本不声明权威源，改触发词时必然漂移。
|
|
|
|
|
|
- 触发词可按团队习惯改名，关键是「一个词 = 一个流程阶段 + 默认动作」。
|
|
|
|
|
|
|
|
|
|
|
|
## 看板视图
|
|
|
|
|
|
|
|
|
|
|
|
- 现阶段：`ls docs/tasks/` + 看各文件 frontmatter 的 `status`/`deps` 挑任务。
|
|
|
|
|
|
- 可选：加一个脚本把所有任务文件的 frontmatter 汇总成一张只读看板表，agent 不手改看板。
|
|
|
|
|
|
|
|
|
|
|
|
## 与路线图和共享文件的关系
|
|
|
|
|
|
|
|
|
|
|
|
- [`../06-tasks.md`](../06-tasks.md)：只读路线图（Phase 划分、里程碑、Backlog、建议拆分清单）；未启用 Gitea 时以任务文件 frontmatter 为准，启用后以 Issue 为实时状态、合并后的任务文件为长期事实。
|
|
|
|
|
|
- `../../progress.md`：可选工件，用作历史归档或项目级大事记；执行记录写各任务文件，不逐任务追加。
|
|
|
|
|
|
- [`../current-state.md`](../current-state.md)：项目级快照（启动/验证路径、目录要点、blocker）；任务状态不在此维护，可由脚本汇总 frontmatter 生成。
|
|
|
|
|
|
- [`../gitea-collaboration.md`](../gitea-collaboration.md)：启用 Gitea 时的任务映射、串行分配、防重复 claim、写路径防撞和 PR 状态协议。
|
