harness_coding_docs/tasks.md

# Harness Coding 样本库任务列表

> 本文件记录当前文档样本库自身的拆分任务。
> 复制到新项目后，项目开发任务应按一任务一文件写入 `docs/tasks/`（路线图在 `docs/06-tasks.md`），不要把本文件当成业务项目任务看板。

## 使用规则

- 每次只领取一个状态为 `TODO` 且依赖均已 `DONE` 的任务。
- 修改模板前先读 `AGENTS.md`、`CLAUDE.md` 和相关 `docs/` 文件。
- 新增、改名或删除文档时，同步检查 `README.md` 和 `docs/README.md`。
- 改完后至少运行：

```powershell
Get-ChildItem -Recurse -File
```

如涉及链接、文件名或入口说明，继续用 `rg` 检查引用一致性。

## 状态图例

`TODO` 待开始 · `DOING` 进行中 · `DONE` 已完成 · `BLOCKED` 受阻

## Phase 0 · 仓库入口

| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| H-001 | 建立 Codex 入口 `AGENTS.md` | - | 说明仓库定位、必读顺序、工作规则和验证方式 | DONE |
| H-002 | 建立 Claude Code 入口 `CLAUDE.md` | - | 作为薄入口指向 `AGENTS.md`，不重复维护规则和文档清单 | DONE |
| H-003 | 建立根目录总览 `README.md` | - | 说明样本库用途、推荐文档集合和使用方式 | DONE |
| H-004 | 明确 `docs/` 是 harness coding 文档目录 | H-001, H-002 | `AGENTS.md` 说明编程从 `docs/00-ai-start-here.md` 进入，`CLAUDE.md` 指向 `AGENTS.md` | DONE |
| H-005 | 建立样本库任务列表 `tasks.md` | H-001 | 根目录存在维护任务列表，并和 `docs/06-tasks.md` 职责区分清楚 | DONE |

## Phase 1 · 核心模板

| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| H-101 | 建立文档导航 `docs/README.md` | H-003 | 能快速找到入口、愿景、需求、技术栈、架构、规则、任务、API、路由和当前状态 | DONE |
| H-102 | 建立 AI 开发入口模板 `docs/00-ai-start-here.md` | H-101 | 包含必读顺序、任务领取规则、MVP 边界、事实来源和验证命令 | DONE |
| H-103 | 建立愿景模板 `docs/01-vision.md` | H-102 | 能约束为什么做、为谁做、产品原则和非目标 | DONE |
| H-104 | 建立需求模板 `docs/02-requirements.md` | H-103 | 能表达功能范围、用户故事、优先级和验收标准 | DONE |
| H-105 | 建立技术栈模板 `docs/03-tech-stack.md` | H-104 | 能固定框架、依赖、运行命令和待定项 | DONE |
| H-106 | 建立架构模板 `docs/04-architecture.md` | H-105 | 能表达系统边界、模块职责、数据模型和开发顺序 | DONE |
| H-107 | 建立编码规则模板 `docs/05-coding-rules.md` | H-106 | 能约束事实来源、范围、架构、代码规范和验证 | DONE |
| H-108 | 建立任务看板模板 `docs/06-tasks.md` | H-107 | 能指导 agent 每轮只领取一个小任务 | DONE |

## Phase 2 · 辅助模板

| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| H-201 | 建立 API 合约模板 `docs/api.md` | H-106 | 能记录接口形状、错误格式、鉴权和示例 | DONE |
| H-202 | 建立路由模板 `docs/routes.md` | H-106 | 能记录页面路由、组件归属和导航规则 | DONE |
| H-203 | 建立当前状态模板 `docs/current-state.md` | H-108 | 能记录仓库现实、已完成内容、可运行命令和下一步 | DONE |
| H-204 | 建立执行进度模板 `progress.md` | H-108 | 能追加记录任务执行、验证命令、阻塞点和关键决策 | DONE |

## Phase 3 · 一致性维护

| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| H-301 | 检查入口文件之间的职责是否重复 | H-005 | `AGENTS.md`、`CLAUDE.md`、`README.md`、`docs/README.md`、`docs/00-ai-start-here.md`、`progress.md` 各自职责清楚 | TODO |
| H-302 | 检查所有模板是否保持通用占位符 | H-201, H-202, H-203 | 没有混入只适用于某个真实项目的业务事实 | TODO |
| H-303 | 检查链接和文件名引用一致性 | H-301 | `rg` 搜索无旧名称、坏路径或冲突说明 | TODO |
| H-304 | 补充复制到新项目后的使用流程 | H-302 | README 和入口模板能指导用户从复制、替换占位符到开始编程 | DONE |
| H-305 | 增加已有项目接入清单 `docs/adoption-checklist.md` | H-304 | 说明已有代码库如何补齐最小接入文件、建立当前状态、配置验证路径和规划第一轮任务 | DONE |

## Phase 4 · Harness 执行可靠性层

> 参考 learn-harness-engineering（OpenAI / Anthropic harness 工程实践）补齐跨会话可靠性机制，保持纯 markdown + 脚本、不绑定技术栈。

| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| H-401 | 增加标准启动入口 `init.sh` | H-106 | 根目录存在统一 install+verify+print-start 脚本；占位变量可替换；未替换时主动失败并提示同步文档命令 | DONE |
| H-406 | 增加 PowerShell 版入口 `init.ps1` 并说明按操作系统二选一 | H-401 | 根目录存在与 `init.sh` 等价的 PowerShell 脚本；脚本头和文档说明二选一、换技术栈只改三个命令变量；导航已登记 | DONE |
| H-402 | 增加干净收尾检查清单 `docs/clean-state-checklist.md` | H-203 | 会话结束前可逐项确认下一轮无需人工修复即可开工 | DONE |
| H-403 | 在 `06-tasks.md`/`05-coding-rules.md` 引入“证据绑定完成” | H-107, H-108 | passing 需在 `progress.md` 记录可运行证据，禁止“代码已写即 DONE” | DONE |
| H-404 | 在 `00-ai-start-here.md` 加固定开工/收尾流程 | H-102 | 含 pwd→读状态→git log→init.sh→smoke 基线→坏先修→领任务，收尾链接检查清单 | DONE |
| H-405 | 在 `current-state.md` 加启动/验证路径和 blocker 字段 | H-203 | 快照含标准启动路径、标准验证路径、当前 blocker | DONE |
| H-407 | 增加多 agent 并发任务管理约定 `docs/tasks/` | H-108, H-501 | 新增 `docs/tasks/README.md`（一任务一文件、frontmatter、防撞号、执行记录进任务文件、不逐任务改共享收尾文件）和 `_template.md`；`method-map.md` 增"多 agent 抢改任务文件"失败模式行；`06-tasks.md`/`00-ai-start-here.md` 加多 agent 分支说明；`README.md`/`docs/README.md` 登记；保持通用占位符、不绑业务 | DONE |
| H-408 | 在 `docs/tasks/README.md` 增加用户指令暗语约定 | H-407 | 触发词表（bug:/需求:/grill:/落task/审/补/做/记backlog:）映射到"分析不改码 / 反方评审 / 落文档并提交 / git 历史核实审核 / 补结论 / 绿灯才提交、红灯报告不提交 / 记待办池"；含默认值（全栈视角、默认提交、只提交相关文件）、无上下文必须先问不得猜、AGENTS.md 为唯一权威源的声明；保持通用、触发词可改名 | DONE |
| H-409 | 把「一任务一文件」从并发切换模式升级为默认任务管理模式 | H-407, H-408 | ① `docs/tasks/README.md` 改为默认模式文档：删除"仅并发时切换"叙事，单/多 agent 统一走一任务一文件，暗语流程、防撞号、执行记录进任务文件等规则保留；② `docs/06-tasks.md` 降级为只读路线图：仅保留 Phase 划分、里程碑 M1-M4、Backlog 待办池，预置 T-001~T-402 转为"建议拆分清单"（开工时才落成任务文件），不再逐任务跟踪状态；③ `progress.md` 标注为可选/历史归档，执行记录默认写任务文件 `## 执行记录`；`current-state.md` 保留项目级快照职责（启动/验证路径、blocker），任务状态以各任务 frontmatter 为准（可脚本汇总）；④ 同步更新引用方：`00-ai-start-here.md`（开工/收尾流程）、`05-coding-rules.md`（完成定义与证据绑定路径）、`README.md`、`docs/README.md`、`adoption-checklist.md`、`clean-state-checklist.md`、`method-map.md`；⑤ 验证：`rg` 搜"切换/冻结/逐任务追加 progress/覆盖 current-state"等旧流程表述清零，链接引用一致；不改暗语触发词，不引入 Gitea 集成（另见 Obsidian 笔记，暂缓） | DONE |
| H-410 | 收编用户故事 / 交互清单的根目录残留示例并收窄文档重叠 | - | 已将根目录草稿收编为 07 / 08 文末的通用填写示例；02 只保留功能 / US 编号 / 优先级索引；08 默认先总表、仅为 P0 或例外交互补详情；已删除根目录草稿并完成导航、上下文和残留校验。 | DONE |

## Phase 5 · Harness 评审与健康度层（Tier 2）

> 补齐"评审单次输出"和"追踪代码库长期健康度"两套机制，保持通用占位符、不绑定技术栈。

| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| H-501 | 增加方法对照表 `docs/method-map.md` | H-401, H-402, H-403 | 失败模式 → 首要修复 → 工件，链接到本仓库真实工件，作为诊断 / 导航入口 | DONE |
| H-502 | 增加评审评分表 `docs/evaluator-rubric.md` | H-403 | 6 维 0-2 分 + Accept/Revise/Block 结论 + 校准说明 | DONE |
| H-503 | 增加质量文档 `docs/quality-document.md` | H-106 | 产品域 × 架构层 A-D 评级 + 变更历史，区别于单次输出评审 | DONE |

## Phase 6 · Gitea 多 Agent 共享上下文

> 用 Gitea Git 保存版本化事实、Issue / PR 协调实时状态、MCP 按需读取；保持模板通用，不提交实例地址或 Token。

| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| H-601 | Phase 0：建立 Gitea MCP 安全与连接基线 | H-409 | 固定 MCP 版本；私有配置不入库；HTTP 需显式确认风险；读写审批和断连降级规则清楚 | DONE |
| H-602 | Phase 1：增加上下文清单与按需读取流程 | H-601 | 有机器可读清单和无第三方依赖验证；agent 按任务类型读取；同一 SHA 不重复加载 | DONE |
| H-603 | Phase 2：建立 Issue / 任务文件 / PR 多 Agent 协调协议 | H-602 | 任务映射、领取读回校验、分支 / worktree 和写路径防撞规则完整 | DONE |
| H-604 | Phase 3：增加自动化治理与一致性检查 | H-603 | 离线导航、清单、任务元数据和敏感信息检查可运行；Actions 模板就绪，实际运行以 runner 启用为前提 | DONE |

## Backlog

- 【Tier 3】增加初始化阶段 playbook：第一轮会话产出基线工件 + 第一个 clean commit。
- 【Tier 3】给 `04-architecture.md` 补可选分层领域架构小节（Types→Config→Repo→Service→Runtime→UI）。
- 【Tier 3】增加可观测性 / UI 验证闭环 SOP（query→reason→implement→restart→rerun→verify）。
- 增加“从空项目初始化文档”的操作清单。
- 增加“任务拆分质量检查表”。
- 增加“文档与代码现实不一致时的处理流程”。