harness_coding_docs/docs/tasks/README.md

任务文件（一任务一文件 · 默认任务管理方式）

本目录是项目任务的默认存放位置：每个任务一个文件 docs/tasks/T-<编号>.md，单 agent 与多 agent 并发通用。 阶段划分、里程碑和待办池见路线图 ../06-tasks.md；路线图只读，不跟踪单任务状态。

为什么默认一任务一文件

• 单 agent：领任务只读一个文件就拿到完整上下文（背景、方案、验收、执行记录），不用在看板、进度流水、快照三个共享文件之间跳转同步；执行记录和任务绑定，审查时 git log -p 一个文件即可回放全程。
• 多 agent 并发：单个大看板 + 多写者 = 编辑竞争（读到旧版本、反复重读）、ID 撞号（全局递增号是共享计数器）、合并冲突（相邻行改动）。一任务一文件后：改哪个任务只动哪个文件，agent 之间互不抢占；ID 撞号在新建文件时当场暴露（文件已存在就换号）。
• 零迁移：项目从单 agent 长到多 agent，无需切换任何约定。

文件命名与 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 + 正文）

---
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（项目级快照，只在启动/验证路径、目录结构或 blocker 变化时更新）。
• 只改自己那个任务文件；不要编辑别人正在做的任务文件。

用户指令暗语（可选约定）

用户的工作流通常固定为：提 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：只读路线图（Phase 划分、里程碑、Backlog、建议拆分清单）；真实任务状态一律以本目录任务文件的 frontmatter 为准。
• ../../progress.md：可选工件，用作历史归档或项目级大事记；执行记录写各任务文件，不逐任务追加。
• ../current-state.md：项目级快照（启动/验证路径、目录要点、blocker）；任务状态不在此维护，可由脚本汇总 frontmatter 生成。