diff --git a/README.md b/README.md index 291dfca..9ac2e04 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ | [`gitea.env.example`](gitea.env.example) | Gitea MCP 本机私有配置示例；复制后替换，真实文件不得入库 | | [`progress.md`](progress.md) | 可选：历史归档 / 项目级大事记；执行记录默认写各任务文件 | | [`docs/README.md`](docs/README.md) | 文档导航，总览所有项目文档 | +| [`docs/repo-tour.md`](docs/repo-tour.md) | 新人导览：文档全景、工作流、任务生命周期流程图（描述样本库自身） | | [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md) | AI coding agent 的入口、阅读顺序、任务领取规则 | | [`docs/01-vision.md`](docs/01-vision.md) | 项目为什么做、为谁做、什么不做 | | [`docs/02-requirements.md`](docs/02-requirements.md) | 产品需求、功能范围、优先级与验收标准 | diff --git a/docs/README.md b/docs/README.md index 47c08f2..77db2b1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,6 +16,7 @@ - [`../CLAUDE.md`](../CLAUDE.md)：Claude Code 的薄入口，具体规则以 `AGENTS.md` 为准。 - [`../tasks.md`](../tasks.md)：当前样本库自身的维护任务列表，不是复制到新项目后的业务任务看板。 - [`../progress.md`](../progress.md)：可选历史归档 / 项目级大事记；执行记录默认写各任务文件的 `## 执行记录`。 +- [仓库导览](repo-tour.md)：给新接手者的结构、工作流和任务生命周期流程图；描述样本库自身，复制模板到新项目时可不带。 - [AI 开发入口](00-ai-start-here.md)：agent 每次开始工作的入口、阅读顺序和任务领取规则。 - [项目愿景](01-vision.md)：为什么做、为谁做、产品原则、非目标。 - [需求](02-requirements.md)：要什么、功能范围、优先级、验收标准，不写技术实现。 diff --git a/docs/repo-tour.md b/docs/repo-tour.md new file mode 100644 index 0000000..8fad64e --- /dev/null +++ b/docs/repo-tour.md @@ -0,0 +1,147 @@ +# 仓库导览（新人流程图） + +> 写给刚接手本仓库的人。本文描述**样本库自身**的结构和工作流，不是可复制到新项目的模板；复制模板时可以不带本文。 +> 事实基准：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`](06-tasks.md)（只读路线图） | + +## 二、文档全景图 + +所有规则的唯一权威源是 `AGENTS.md`（`CLAUDE.md` 只是指向它的薄入口）。文档按职责分层： + +```mermaid +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` 是可选的历史归档，执行记录默认写在各任务文件里。 + +## 三、每轮会话的标准工作流 + +每次进入项目走同一条固定流程——开工有基线检查，收尾有清单，保证下一轮无需人工修复即可开工： + +```mermaid +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 必须附带可运行的验证命令和结果，「代码已写」不算完成。 + +## 四、一个任务的一生 + +任务管理默认「一任务一文件」：路线图上的条目只是建议，开工时才落成任务文件，frontmatter 状态是唯一权威状态： + +```mermaid +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` 重叠的任务不能同时进行。 + +## 五、UI 需求专线：从一句话到可验收 + +有界面的需求走专门流水线，把「页面上有什么」和「行为该怎样」分开处理： + +```mermaid +flowchart TD + A["用一两句话描述页面"] --> B["AI 生成低保真原型
docs/design/xxx.html 单文件"] + B --> C{"人工看图认可？"} + C -- 调整 --> B + C -- 认可 --> D["AI 据原型枚举交互
产出 IX 总表草稿 · 全标待确认"] + D --> E["人工逐条确认行为决策
优先级 / 状态与异常 / 无障碍"] + E --> F["P0 交互按完整模板展开
状态表 + 无障碍 + 验收证据"] + F --> G["拆成任务文件 · 关联 US / IX 编号"] + G --> H["实现 · 截图进执行记录"] + H --> X["原型即视为过期
不承担同步义务"] +``` + +权威关系：行为的权威永远是[交互清单](08-interaction-checklist.md)，原型只是一次性输入物（约定见 [`design/README.md`](design/README.md)）；原型里有但需求没有的功能不能实现；禁止把原型代码直接复制进生产实现。 + +## 六、暗语速查表 + +用户用短指令驱动工作，完整约定在 [`tasks/README.md`](tasks/README.md)： + +| 触发词 | 含义 | 关键边界 | +| --- | --- | --- | +| `bug:` / `需求:` | 只分析，给结论 | 不改任何代码和文档 | +| `grill:` | 反方视角严格评审 | 专挑毛病，不粉饰 | +| `落` / `落task` | 把结论写成任务文件 | 只改文档，写完即提交 | +| `做 T-xxx` | 实现该任务 | 验证全绿才提交；红灯只报告、不提交 | +| `审 T-xxx` | 基于 git 历史核实审核 | 对照落任务时的验收原文逐条核对 | +| `补` | 把结论补进对应文档 | 追加，不重写历史 | +| `记backlog:` | 记一行待办 | 进待办池，不展开 | + +> **一条铁律**：任务的验收要点一经领取就不能改写——完成时只改状态列，证据另记。事后把验收改写成「已完成 X」来自证达标，会架空整个证据机制。 + +## 七、第一天该做什么 + +1. 按顺序读：`AGENTS.md` → `README.md` → [`README.md`](README.md)（docs 导航）→ [`00-ai-start-here.md`](00-ai-start-here.md)。这四个读完，其余按需查。 +2. 跑一次一致性校验：`python3 scripts/validate_agent_context.py`。 +3. `git log --oneline -20` 看最近提交——message 以任务编号结尾（如 `(H-413)`），顺着编号在 `tasks.md` 能找到每次改动的验收要点，这是本仓库的审计线索。 +4. 翻一眼[方法对照表](method-map.md)：失败模式 → 修复方法 → 对应工件，迷路时从这里找回入口。 +5. 想练手，从 `tasks.md` 挑一个 `TODO` 的小任务，按第三节流程完整走一遍。 + +## 八、可选层：Gitea 多 Agent 协作 + +多 agent 并行开发时，用自建 Gitea 做协调——Issue/PR 管实时状态、`agent-context.json` 按任务类型路由必读文档、脚本做治理检查，见 [`gitea-mcp.md`](gitea-mcp.md) 和 [`gitea-collaboration.md`](gitea-collaboration.md)。**单人 + 单 agent 用不到它**；启用前先读安全基线（私有配置不入库、Token 不提交）。 + +--- + +迷路时的两个锚点：规则不确定 → 回 `AGENTS.md`；现状不确定 → 回 [`current-state.md`](current-state.md) 和 `git log`。聊天记录永远不是事实来源，仓库里的文件才是。