仓库导览：harness_coding_docs

写给刚接手这个项目的你。这不是一个业务应用，而是一个文档模板仓库：它沉淀了「把项目交给 AI coding agent 开发之前，应该准备哪些文档」的一整套模板。你复制它到新项目、替换占位符，agent 就能靠仓库内的文件（而不是聊天记录）持续推进开发。

纯 Markdown + 少量脚本中文模板 · 【占位符】待替换不绑定任何技术栈

01先分清两种身份

这个仓库同时扮演两个角色，任务编号也分成两套，千万别混：

	维护模板本身	复制到新项目后使用
任务列表	根目录 `tasks.md`	`docs/tasks/` 一任务一文件
任务编号	`H-xxx`（如 H-412）	`T-xxx`（如 T-001）
路线图	`tasks.md` 的 Phase 0–6	`docs/06-tasks.md`（只读路线图）
你现在的工作	改进模板、保持一致性	——（新项目里才用）

02文档全景图

所有规则的唯一权威源是 AGENTS.md（CLAUDE.md 只是指向它的薄入口）。文档按职责分层，每一层回答一个问题：

flowchart TD
    A["AGENTS.md
仓库级规则 · 唯一权威源"] --> S["docs/00-ai-start-here.md
agent 每轮工作的入口"]
    C["CLAUDE.md
薄入口"] -.指向.-> A

    S --> P["产品层：做什么"]
    S --> E["工程层：怎么做"]
    S --> T["任务层：现在做哪件"]
    S --> Q["状态与质量层：做得怎样"]

    subgraph P["产品层 · 做什么"]
        P1["01-vision 愿景"] --> P2["02-requirements 需求"]
        P2 --> P3["07-user-stories 用户故事 US"]
        P3 --> P4["08-interaction-checklist 交互 IX"]
        P4 -.输入素材.- P5["design/ HTML 原型"]
    end

    subgraph E["工程层 · 怎么做"]
        E1["03-tech-stack 技术栈"]
        E2["04-architecture 架构"]
        E3["05-coding-rules 编码规则"]
        E4["api.md / routes.md 合约"]
    end

    subgraph T["任务层 · 现在做哪件"]
        T1["06-tasks 只读路线图"] --> T2["docs/tasks/T-xxx.md
一任务一文件"]
    end

    subgraph Q["状态与质量层 · 做得怎样"]
        Q1["current-state 项目快照"]
        Q2["clean-state-checklist 收尾清单"]
        Q3["evaluator-rubric 评审评分"]
        Q4["quality-document 长期健康度"]
    end

读的顺序就是图的顺序：先规则入口，再产品层建立「做什么」，工程层约束「怎么做」，最后从任务层领活。progress.md 是可选的历史归档，执行记录默认写在各任务文件里。

03每轮会话的标准工作流

agent（或你自己）每次打开这个项目，走的都是同一条固定流程——开工有基线检查，收尾有清单，保证下一轮不需要人工修复就能继续：

flowchart TD
    A["开工：确认目录 pwd"] --> B["读 current-state.md
和 DOING 中的任务文件"]
    B --> C["git log 看最近改动"]
    C --> D["跑 init.sh / init.ps1
安装依赖 + 基础验证"]
    D --> E{"基线是绿的吗？"}
    E -- 否 --> F["先修基线
不做新功能"]
    F --> D
    E -- 是 --> G["从 docs/tasks/ 领一个任务
TODO 且依赖全 DONE，一次只领一个"]
    G --> H["实现 + 自测"]
    H --> I{"验证命令全绿？"}
    I -- 否 --> J["如实报告红灯
状态改 DOING / BLOCKED
不提交"]
    I -- 是 --> K["把命令和结果写进任务文件
## 执行记录 作为证据"]
    K --> L["状态改 DONE · 提交"]
    L --> M["收尾：过一遍
clean-state-checklist.md"]

核心纪律叫「证据绑定完成」：DONE 必须附带可运行的验证命令和结果，「代码已写」不算完成。

04一个任务的一生

任务管理默认「一任务一文件」：路线图上的条目只是建议，开工时才落成真正的任务文件。文件头部的 frontmatter 状态就是唯一权威状态：

flowchart LR
    R["06-tasks.md 路线图
建议拆分清单"] -- 开工时落文件 --> F["docs/tasks/T-xxx.md
status: TODO"]
    F -- 领取 --> D["status: DOING
写清 write_paths 防冲突"]
    D -- 验证全绿 + 证据入执行记录 --> OK["status: DONE"]
    D -- 被阻塞 --> BL["status: BLOCKED
blocker 同步到 current-state"]
    BL -- 解除 --> D

编号规则：沿用路线图建议的编号，新任务取现有最大 T 编号 +1。多个 agent 并行时，write_paths 重叠的任务不能同时进行。

05UI 需求专线：从一句话到可验收

有界面的需求走一条专门的流水线，把「页面上有什么」和「行为该怎样」分开处理：

flowchart TD
    A["用一两句话描述页面"] --> B["AI 生成低保真原型
docs/design/xxx.html 单文件"]
    B --> C{"人工看图认可？"}
    C -- 调整 --> B
    C -- 认可 --> D["AI 据原型枚举交互
产出 IX 总表草稿 · 全标待确认"]
    D --> E["人工逐条确认行为决策
优先级 / 状态与异常 / 无障碍"]
    E --> F["P0 交互按完整模板展开
10 行状态表 + 无障碍 + 验收证据"]
    F --> G["拆成任务文件 · 关联 US / IX 编号"]
    G --> H["实现 · 截图进执行记录"]
    H --> X["原型即视为过期
不承担同步义务"]

权威关系要记牢：行为的权威永远是 08-interaction-checklist.md，原型只是一次性输入物；原型里有但需求没有的功能，不能因为「图上有」就实现；禁止把原型代码直接复制进生产实现。

06暗语速查表

用户会用短指令驱动工作，约定在 docs/tasks/README.md。看到这些词就知道该做什么、不该做什么：

触发词	含义	关键边界
`bug:` / `需求:`	只分析，给结论	不改任何代码和文档
`grill:`	反方视角严格评审	专挑毛病，不粉饰
`落` / `落task`	把结论写成任务文件	只改文档，写完即提交
`做 T-xxx`	实现该任务	验证全绿才提交；红灯只报告、不提交
`审 T-xxx`	基于 git 历史核实审核	对照落任务时的验收原文逐条核对
`补`	把结论补进对应文档	追加，不重写历史
`记backlog:`	记一行待办	进待办池，不展开

一条铁律：任务的验收要点一经领取就不能改写——完成时只改状态列，证据另记。事后把验收改写成「已完成 X」来自证达标，会架空整个证据机制。

07第一天该做什么

按顺序读：AGENTS.md → README.md → docs/README.md → docs/00-ai-start-here.md。这四个文件读完，其余文档按需查即可。
跑一次一致性校验，感受这个仓库的验证方式：python3 scripts/validate_agent_context.py。
用 git log --oneline -20 看最近的提交——commit message 都以任务编号结尾（如 (H-413)），顺着编号在 tasks.md 里能找到每次改动的验收要点，这就是本仓库的「审计线索」。
翻一眼 docs/method-map.md：它是「失败模式 → 修复方法 → 对应工件」的对照表，迷路时从这里找回入口。
想练手，从 tasks.md 里挑一个 TODO 的小任务（如 H-301 系列一致性检查），按第 03 节的流程完整走一遍。

08可选层：Gitea 多 Agent 协作

当前分支（feat/gitea-multi-agent-context）还带了一个可选层：多个 agent 并行开发时，用自建 Gitea 做协调——Issue/PR 管实时状态、agent-context.json 按任务类型路由该读哪些文档、脚本做治理检查。相关文档是 docs/gitea-mcp.md 和 docs/gitea-collaboration.md。单人 + 单 agent 用不到它，知道存在即可；启用前先读安全基线（私有配置不入库、Token 不提交）。

迷路时的两个锚点：规则不确定 → 回 AGENTS.md；现状不确定 → 回 docs/current-state.md 和 git log。聊天记录永远不是事实来源，仓库里的文件才是。