7.8 KiB
仓库导览（新人流程图）
写给刚接手本仓库的人。本文描述样本库自身的结构和工作流，不是可复制到新项目的模板；复制模板时可以不带本文。 事实基准：2026-07-17，分支
feat/gitea-multi-agent-context。仓库结构显著变化后应重新生成本文。
本仓库不是业务应用，而是文档模板仓库：沉淀「把项目交给 AI coding agent 开发之前，应该准备哪些文档」的一整套模板。复制到新项目、替换 【占位符】 后，agent 就能靠仓库内文件（而不是聊天记录）持续推进开发。
一、先分清两种身份
本仓库同时扮演两个角色，任务编号分两套，不要混：
| 维护模板本身 | 复制到新项目后使用 | |
|---|---|---|
| 任务列表 | 根目录 tasks.md |
docs/tasks/ 一任务一文件 |
| 任务编号 | H-xxx（如 H-412） |
T-xxx（如 T-001） |
| 路线图 | tasks.md 的 Phase 0–6 |
06-tasks.md（只读路线图） |
二、文档全景图
所有规则的唯一权威源是 AGENTS.md（CLAUDE.md 只是指向它的薄入口）。文档按职责分层：
flowchart TD
A["AGENTS.md<br/>仓库级规则 · 唯一权威源"] --> S["docs/00-ai-start-here.md<br/>agent 每轮工作的入口"]
C["CLAUDE.md<br/>薄入口"] -.指向.-> 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<br/>一任务一文件"]
end
subgraph Q["状态与质量层 · 做得怎样"]
Q1["current-state 项目快照"]
Q2["clean-state-checklist 收尾清单"]
Q3["evaluator-rubric 评审评分"]
Q4["quality-document 长期健康度"]
end
读的顺序就是图的顺序：先规则入口，再产品层建立「做什么」，工程层约束「怎么做」，最后从任务层领活。progress.md 是可选的历史归档，执行记录默认写在各任务文件里。
三、每轮会话的标准工作流
每次进入项目走同一条固定流程——开工有基线检查，收尾有清单，保证下一轮无需人工修复即可开工：
flowchart TD
A["开工：确认目录 pwd"] --> B["读 current-state.md<br/>和 DOING 中的任务文件"]
B --> C["git log 看最近改动"]
C --> D["跑 init.sh / init.ps1<br/>安装依赖 + 基础验证"]
D --> E{"基线是绿的吗？"}
E -- 否 --> F["先修基线<br/>不做新功能"]
F --> D
E -- 是 --> G["从 docs/tasks/ 领一个任务<br/>TODO 且依赖全 DONE，一次只领一个"]
G --> H["实现 + 自测"]
H --> I{"验证命令全绿？"}
I -- 否 --> J["如实报告红灯<br/>状态改 DOING / BLOCKED<br/>不提交"]
I -- 是 --> K["把命令和结果写进任务文件<br/>## 执行记录 作为证据"]
K --> L["状态改 DONE · 提交"]
L --> M["收尾：过一遍<br/>clean-state-checklist.md"]
核心纪律叫「证据绑定完成」：DONE 必须附带可运行的验证命令和结果，「代码已写」不算完成。
四、一个任务的一生
任务管理默认「一任务一文件」：路线图上的条目只是建议，开工时才落成任务文件，frontmatter 状态是唯一权威状态：
flowchart LR
R["06-tasks.md 路线图<br/>建议拆分清单"] -- 开工时落文件 --> F["docs/tasks/T-xxx.md<br/>status: TODO"]
F -- 领取 --> D["status: DOING<br/>写清 write_paths 防冲突"]
D -- 验证全绿 + 证据入执行记录 --> OK["status: DONE"]
D -- 被阻塞 --> BL["status: BLOCKED<br/>blocker 同步到 current-state"]
BL -- 解除 --> D
编号规则：沿用路线图建议的编号，新任务取现有最大 T 编号 +1。多 agent 并行时，write_paths 重叠的任务不能同时进行。
五、UI 需求专线：从一句话到可验收
有界面的需求走专门流水线，把「页面上有什么」和「行为该怎样」分开处理：
flowchart TD
A["用一两句话描述页面"] --> B["AI 生成低保真原型<br/>docs/design/xxx.html 单文件"]
B --> C{"人工看图认可？"}
C -- 调整 --> B
C -- 认可 --> D["AI 据原型枚举交互<br/>产出 IX 总表草稿 · 全标待确认"]
D --> E["人工逐条确认行为决策<br/>优先级 / 状态与异常 / 无障碍"]
E --> F["P0 交互按完整模板展开<br/>状态表 + 无障碍 + 验收证据"]
F --> G["拆成任务文件 · 关联 US / IX 编号"]
G --> H["实现 · 截图进执行记录"]
H --> X["原型即视为过期<br/>不承担同步义务"]
权威关系：行为的权威永远是交互清单，原型只是一次性输入物（约定见 design/README.md）；原型里有但需求没有的功能不能实现；禁止把原型代码直接复制进生产实现。
六、暗语速查表
用户用短指令驱动工作，完整约定在 tasks/README.md：
| 触发词 | 含义 | 关键边界 |
|---|---|---|
bug: / 需求: |
只分析，给结论 | 不改任何代码和文档 |
grill: |
反方视角严格评审 | 专挑毛病，不粉饰 |
落 / 落task |
把结论写成任务文件 | 只改文档，写完即提交 |
做 T-xxx |
实现该任务 | 验证全绿才提交；红灯只报告、不提交 |
审 T-xxx |
基于 git 历史核实审核 | 对照落任务时的验收原文逐条核对 |
补 |
把结论补进对应文档 | 追加，不重写历史 |
记backlog: |
记一行待办 | 进待办池，不展开 |
一条铁律：任务的验收要点一经领取就不能改写——完成时只改状态列，证据另记。事后把验收改写成「已完成 X」来自证达标，会架空整个证据机制。
七、第一天该做什么
- 按顺序读：
AGENTS.md→README.md→README.md（docs 导航）→00-ai-start-here.md。这四个读完，其余按需查。 - 跑一次一致性校验：
python3 scripts/validate_agent_context.py。 git log --oneline -20看最近提交——message 以任务编号结尾（如(H-413)），顺着编号在tasks.md能找到每次改动的验收要点，这是本仓库的审计线索。- 翻一眼方法对照表：失败模式 → 修复方法 → 对应工件，迷路时从这里找回入口。
- 想练手，从
tasks.md挑一个TODO的小任务，按第三节流程完整走一遍。
八、可选层：Gitea 多 Agent 协作
多 agent 并行开发时，用自建 Gitea 做协调——Issue/PR 管实时状态、agent-context.json 按任务类型路由必读文档、脚本做治理检查，见 gitea-mcp.md 和 gitea-collaboration.md。单人 + 单 agent 用不到它；启用前先读安全基线（私有配置不入库、Token 不提交）。
迷路时的两个锚点：规则不确定 → 回 AGENTS.md；现状不确定 → 回 current-state.md 和 git log。聊天记录永远不是事实来源，仓库里的文件才是。