116 lines
17 KiB
Markdown
116 lines
17 KiB
Markdown
# 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 | 收编用户故事 / 交互清单的根目录残留示例并收窄文档重叠 | - | ① 根目录 `独立交互清单.md`、`用户故事清单.md` 占位符化后收编：内容去业务事实（用户管理 / `/api/users` / 头像上传等改为 `【占位符】`）、编号规范化为 US-001 / IX-001 格式、表格列对齐 `07-user-stories.md` / `08-interaction-checklist.md` 现有表结构、删除不存在的 `design/screenshot.svg` 引用，作为「填写示例」小节分别并入 07 / 08 文末，然后删除根目录这两个文件；② `docs/02-requirements.md` 的"核心用户故事总览表"收窄为 功能 / US 编号 / 优先级 三列，角色、目标、关联交互列移除，由 07 独占，保留"详细故事以 07 为准"的指向；③ `docs/08-interaction-checklist.md` 把"先总表、只为 P0 / 高风险 / 易歧义交互补详情"升格为醒目规则（详情模板默认只覆盖 P0），避免逐交互填全表的官僚化；④ 验证：`python3 scripts/validate_agent_context.py` 通过；`rg` 确认 `design/screenshot.svg`、`用户管理`、`/api/users` 等业务残留清零，根目录无中文文件名残留；07 / 08 / 02 相互链接一致；不改 07 / 08 文件名和编号（阅读顺序已由 README 导航表达） | DONE |
|
||
| H-411 | 返修 H-410：恢复验收契约并重写填写示例 | H-410 | ① 恢复本文件中 H-410 验收要点为落任务时原文（见 ecd75de），状态保持 DONE；「使用规则」新增"验收要点一经领取不得改写，完成时只更新状态并另记证据；确需重新定义任务时先经用户确认"条款；② `docs/07-user-stories.md`、`docs/08-interaction-checklist.md` 的「填写示例」改写为具体但通用的示例（列表检索、删除确认等通用场景，业务对象统一用【条目】占位），每个字段给出真实可读的填法，不再逐字复读模板占位符；③ 08 示例以破坏性 P0 交互演示完整 10 行状态与异常清单和无障碍要求，低风险交互演示"只留总表条目"的用法；④ 验证：`python3 scripts/validate_agent_context.py` 通过、全仓 `.md` 相对链接无断链、示例未混入真实业务事实（无具体接口路径 / 真实产品名） | DONE |
|
||
| H-412 | 增加 HTML 原型输入约定 `docs/design/` | H-411 | ① 新增 `docs/design/README.md` 约定文档：原型定位（生成 07 用户故事 / 08 交互清单的一次性输入物，低保真优先）；形态（一页面一个单文件 `.html`，CSS / JS 内联、零构建依赖、双击可开，按路由命名如 `items-list.html`）；假数据要求（页面顶部固定 "PROTOTYPE" 横幅标注仅供枚举交互）；权威性边界（行为权威是 08 清单，原型与清单冲突时以清单+需求为准；禁止把原型代码直接复制进生产实现，实现按 `04-architecture.md` 组件边界重写）；工作流（需求描述 → AI 生成原型 → 人工调整认可 → 据原型产出 IX 总表草稿全标【待确认】→ 人工确认行为决策）；SVG / Excalidraw 作为快速草图的替代形态一并说明（文字须保留为真文本）；② `docs/08-interaction-checklist.md` 交互详情模板与填写示例增加可选字段「关联原型」（无原型时写不适用）；③ 登记导航：`README.md`、`docs/README.md`；`docs/00-ai-start-here.md` 的"做页面 / UI"分支提及原型可作输入；④ 验证：`python3 scripts/validate_agent_context.py` 通过、全仓 `.md` 相对链接无断链、约定保持通用占位符不绑业务；不预置示例原型文件，不改 07 / 08 文件名 | DONE |
|
||
| H-413 | 原型生命周期规则：开工门槛 + 触发式重新生成 | H-412 | ① `docs/design/README.md`：「定位与边界」或「维护规则」补三条——P0 的 UI 模块首次实现前应有原型，没有就先生成再拆任务（开工门槛，一次性）；新需求显著改变页面布局或控件集合时，把"重新生成该页原型 → 更新 IX 草稿"作为该任务第一步，判断标准为"agent 是否需要重新看图才能枚举交互"，小改动（文案、加字段）只改 IX 条目不碰原型；页面实现后原型即视为过期，不承担与实现同步的义务，实现后的视觉事实由任务文件执行记录中的真实截图承担；② `docs/tasks/README.md`：UI 任务规则处加一句——P0 UI 任务动手前确认 `docs/design/` 有对应原型，无则先生成；显著改版任务在任务文件方案中写明第一步重新生成原型；③ 不引入"每模块常备原型库"和"变更必同步原型"的义务，措辞明确原型是一次性输入物；④ 验证：`python3 scripts/validate_agent_context.py` 通过、全仓 `.md` 相对链接无断链、新旧措辞无冲突（`rg` 检查"持续同步 / 必备"相关表述一致） | DONE |
|
||
| H-414 | 提炼跨 Agent 工作模式、独立复核与验收门禁 | H-409 | ① `docs/00-ai-start-here.md` 增加跨 Claude Code、Codex 及其他 coding agent 通用的工作模式：默认单任务、单责任 Agent、单写入者；复杂任务先规划并把确认后的方案写入当前任务文件；范围明确时直接执行，范围不清或跨目录探索收益明显时才按平台能力做只读探索；任务内委派仅在项目显式启用时使用，不绑定厂商、模型或代理类型；② `docs/tasks/README.md` 与 `_template.md` 要求任务在编码前落盘方案、不可变约束（阈值 / 判定式 / 安全边界 / 既有契约）、`write_paths`、分层验证和必需人工验收，委派执行者继承全部边界且仍保持唯一写入者；③ `docs/05-coding-rules.md` 与 `docs/clean-state-checklist.md` 增加任务所有者独立复核：检查 `git status` / `git diff` 是否越界、按项目规则检查意外行尾变化、独立重跑验证，不以执行者自报判定完成；必需的人工 / 设备验收未完成不得标记 `DONE`；④ `docs/03-tech-stack.md` 增加任务相关验证、完整门禁、人工 / 设备验收三层矩阵及触发条件；构建产物可按项目需要记录 SHA-256 等指纹，不强制所有任务无差别跑全量；⑤ 保持根 `CLAUDE.md` 为薄入口，不新增厂商专属流程、不新增文档；运行上下文校验、单元测试、治理校验、相对链接和 `git diff --check` | TODO |
|
||
|
||
## 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）。
|
||
- 增加“从空项目初始化文档”的操作清单。
|
||
- 增加“任务拆分质量检查表”。
|
||
- 增加“文档与代码现实不一致时的处理流程”。
|