# 任务文件(一任务一文件 · 默认任务管理方式)

> 本目录是项目任务的**默认存放位置**:每个任务一个文件 `docs/tasks/W-<编号>.md`。当前项目使用单 Agent 串行执行。
> 阶段划分、里程碑和待办池见路线图 [`../06-tasks.md`](../06-tasks.md);路线图只读,不跟踪单任务状态。
> 本仓库任务编号前缀为 `W-`;引用客户端仓库任务写全称(如 `soft_quay/T-614`),避免跨仓库混淆。

## 为什么默认一任务一文件

- **单 agent**:领任务只读一个文件就拿到完整上下文(背景、方案、验收、执行记录);执行记录和任务绑定,审查时 `git log -p` 一个文件即可回放全程。
- **低上下文成本**:只读取当前任务规格和执行记录,减少跨文件同步与重复检索。
- **保留扩展性**:如果未来由用户明确启用多 Agent,现有任务文件仍可作为写路径和依赖边界;启用前必须先更新并提交协作规则。

## 文件命名与 ID

- 文件名:`docs/tasks/W-<编号>.md`(如 `docs/tasks/W-101.md`);同族细分用后缀 `W-101a.md`。
- 落实路线图建议任务时,**沿用路线图 [`../06-tasks.md`](../06-tasks.md) 里的建议编号**(如 W-101)。
- 路线图之外的新任务:取「路线图建议编号 + `docs/tasks/` 现有文件」里最大的 `W-###`,`+1`。
- **建文件即防撞**:若目标编号文件已存在,改用下一个号,不要覆盖别人的文件。
- 模板 `_template.md` 以下划线开头,不是真实任务、不参与编号扫描。

## 每个任务文件的结构(frontmatter + 正文)

```markdown
---
id: W-101
title: 一句话任务名
phase: 1               # 所属阶段,沿用路线图的 Phase 编号
deps: [W-002]          # 依赖的任务 ID
status: TODO           # TODO | DOING | DONE | BLOCKED
created: 【日期】
issue: null            # 远端 Issue 编号;未启用时保持 null
context_ref: null      # 领取时默认分支提交 SHA
claim_branch: null
work_branch: null
write_paths:           # 允许修改的仓库相对路径
  - docs/tasks/W-101.md
  - 【path/to/module】
---

## 问题 / 背景
## 方案
## 验收要点
## 边界(不改什么)
## 协作约束
## 执行记录
```

## 领取 / 完成流程

- 状态:`TODO` · `DOING` · `DONE` · `BLOCKED`。项目同一时间只保留一个活跃任务。
- 单 Agent 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务,取编号最靠前的;若本目录暂无可领任务,先按路线图把下一个建议任务落成任务文件,再领取。
- 裁定类任务(如 W-003、W-004)的产出是写进文档的决策结论,不是代码;验收同样要可检查(结论落在哪个文档哪一节)。
- `write_paths` 必须在动手前写清,用于约束本任务允许修改和提交的路径。
- 做完自测、按「passing 需证据」把验证命令与结果写清、改 `status: DONE`。
- **执行记录写进本任务文件的 `## 执行记录` 一节**——不逐任务追加共享的 `progress.md`(可选历史归档),也不逐任务覆盖 `current-state.md`(项目级快照,只在启动/验证路径、目录结构或 blocker 变化时更新)。
- **只改当前任务文件**;不要顺带修改其他任务的状态或执行记录。

### 当前单 Agent 模式

1. 当前 Agent 负责从任务落文档到最终提交的完整生命周期,不启动或委派子 Agent。
2. 测试设计、安全检查、代码审查和提交前复核由当前 Agent 分阶段执行,结果统一写入任务执行记录。
3. 前一个任务达到 `DONE`、完整验证通过并提交后,才正式落成或领取下一个依赖任务。
4. 若用户以后明确启用多 Agent,必须先修改并提交 `AGENTS.md` 和本文;在该提交之前不得启动子 Agent。

## 用户指令暗语(可选约定,与 soft_quay 一致)

> 默认值:不注明视角就是全栈工程师视角;每步产物默认提交 git(只提交本次相关文件)。

| 用户输入 | agent 执行 |
| --- | --- |
| `bug: <现象>` / `需求: <描述>` | 先查代码再给分析和方案,**只讨论不改代码** |
| `grill: <方案>` | 反方评审,逐点挑战该方案 |
| `落task` | 把已讨论定案落成 `docs/tasks/W-<编号>.md`(按上述规则查号防撞),**只写文档不写代码,写完自动提交 git** |
| `审 W-<编号>` | **以 git 历史为准**先核代码事实,再审核该改动是否合理、给缺口 |
| `补` | 把讨论新增的结论补进当前任务文件并提交 git |
| `做 W-<编号>` | 实现该任务 + 跑任务内验证命令;**验证全绿才提交**;验证失败 → 报告、不提交、状态留 DOING 或标 BLOCKED 记原因 |
| `记backlog: <一行>` | 追加进待办池(`docs/06-tasks.md` Backlog)并提交,只记一行、不建任务文件 |

`落task`/`补` 可带参数;新会话或无对话上下文时 agent **必须先问清指代对象,不得猜**。

## 与路线图和共享文件的关系

- [`../06-tasks.md`](../06-tasks.md):只读路线图(Phase 划分、里程碑、裁定清单、Backlog、建议拆分清单);任务状态以任务文件 frontmatter 为准。
- `../../progress.md`:可选工件,用作历史归档或项目级大事记。
- [`../current-state.md`](../current-state.md):项目级快照(启动/验证路径、目录要点、blocker);任务状态不在此维护。