# 阅读指南

> 本套文档既是给人类决策的 PRD，也是给 Claude Code 的**可执行构建清单**。两类读者各有路径。

## 两个读者

HUMAN

### 人类 · 决策 / 评审

关心「想做什么、为什么、值不值得」。阅读路径：

1. [封面](index.html)
2. [背景](prd-background.html) · [角色](prd-personas.html)
3. [原始需求](requirement.html) · [范围与原则](scope.html)
4. [功能树](prd-feature-tree.html) · [用户流程](prd-user-flows.html)
5. [三层 Loop](loops-overview.html) · [六个 Agent](agents-overview.html)
6. [最小改造路径](plan-migration.html) · [风险](plan-risks.html)

> _预估 30 分钟。最后回到 [plan-risks](plan-risks.html) 末尾回答 3 个 yes/no。_

CLAUDE CODE

### Agent · 执行 / 复现

关心「这个项目要落地什么文件、什么签名、什么行为」。阅读路径：

1. 本页 — 学会怎么抽取结构化信息
2. [功能树](prd-feature-tree.html) — 拿到所有 Unit id 与依赖关系
3. [SDD 总览](sdd-overview.html) — 了解 MVCP 四象限
4. [Model](sdd-model.html) · [View](sdd-view.html) · [Control](sdd-control.html) · [Process](sdd-process.html) — 抽取构建清单
5. [Unit Contract](api-contracts.html) — 跨 Unit 握手协议
6. [复现指南](plan-reproducibility.html) — 执行 prompt

> _机械化阅读，不需要欣赏 prose。所有 `data-*` 属性是 Agent 抓取的锚点。_

## HTML 锚点协议（Claude Code 读取）

所有结构化信息都通过 `data-*` 属性暴露。Agent 用 cheerio 选择器即可机械抽取，无需 NLP。

| 属性 | 出现位置 | 含义 | 选择器示例 |
| --- | --- | --- | --- |
| `data-doc` | 顶级 `
` | 文档类型：prd / sdd | `article[data-doc="prd"]` |
| `data-rev` | article / section | 修订号，单调递增 | `section[data-rev="3"]` |
| `data-unit-id` | SDD section | 本 section 描述的 Unit | `section[data-unit-id="auth-be"]` |
| `data-type` | SDD section | Unit 类型：be / fe / mw / db | `[data-type="be"]` |
| `data-depends` | SDD section | 本 Unit 依赖的其他 Unit id（空格分隔） | — |
| `data-contract` | `
` | 契约定义 (openapi / tsinterface) | `pre[data-contract="openapi"]` | | `data-acceptance` | `<ul>` | 验收标准列表 | — | | `data-mvcp` | 本套文档 SDD section | 所属 MVCP 象限 | `[data-mvcp="model"]` | | `data-origin` | PRD section | 本 section 来源（用户 + 时间） | — | | `data-conflict` | PRD `<aside>` | 与历史 section 矛盾的标记 | — | | `data-changelog` | PRD `
` | 修订日志区 | — | 

## 抽取示例 — units.json 怎么从 SDD 派生 ```js // 给 Claude Code 的 cheerio 代码片段 const $ = cheerio.load(sddHtml); const units = $('section[data-unit-id]').map((_, el) => ({ id: $(el).attr('data-unit-id'), type: $(el).attr('data-type'), depends_on: ($(el).attr('data-depends') || '').split(/\s+/).filter(Boolean), contract: $(el).find('pre[data-contract]').text(), acceptance: $(el).find('ul[data-acceptance] li').map((_,li)=>$(li).text()).get(), })).get(); // → 直接落盘为 units.json 的 .units 字段 ``` 

## MVCP 抽取约定 <p>SDD 四象限页（[Model](sdd-model.html) / [View](sdd-view.html) / [Control](sdd-control.html) / [Process](sdd-process.html)）使用统一的 5 字段结构。每个定义都带：

| 字段 | 含义 | 示例 |
| --- | --- | --- |
| **name** | 唯一标识符 | `units.json` · `DevLoopDashboard` · `LoopController.runProject` |
| **path** | 预期落盘路径 | `server/services/doc-store.js` |
| **shape** | 结构定义（TS / TypeBox / Vue props） | 代码块 |
| **contract** | 行为契约（前置 / 后置条件） | 列表 |
| **tests** | 验收用例 | 列表 |

Claude Code 把 SDD 转成 Unit 任务时，每一条 MVCP 定义都可以独立映射到一个 Unit（或多个 Unit 共享）。

## 文档作为「构建清单」

把整套 PRD + SDD 看作一个机器可解析的 build manifest。复现流程：

<!-- 图见原 HTML -->

具体的 prompt 模板见 [plan-reproducibility](plan-reproducibility.html)。

## 本文档版本

| rev | 日期 | 变更摘要 |
| --- | --- | --- |
| v0.1 | 2026-05-12 | 初版 24 页 · 单 HTML + 拆 24 页 |
| v0.2 | 2026-05-13 | 升级到 41 页：新增 PRD 标准章节、SDD MVCP 五页、原型补全、复现指南 |