# prd-master / design-master / tdd-master 升级说明（维护者版）

> 日期：2026-07-11  
> 设计参考：[Kiro Specs](https://kiro.dev/docs/specs/) 的 `requirements.md → design.md → tasks.md` 三阶段结构  
> 适用对象：prd-master、design-master、tdd-master 的维护者与下游 Coding Agent 工作流维护者

## 1. 执行摘要

本次升级没有把现有三段链路简单改造成 Kiro 的复制品，而是保留原链路的优势，并补上 Kiro 最强的三件事：机器可解析需求、端到端追溯和可执行任务图。

原链路更接近：

```text
产品决策 → 全套设计 → 证明做对
```

升级后变为：

```text
产品决策
  → 稳定需求契约
  → 可追溯设计
  → 分层测试与验收门禁
  → 开发任务 DAG
  → 按 wave 执行并记录 fresh verification
```

本次共涉及 **23 个文件**：

- 修改既有文件：11 个
- 新增文件：12 个
- prd-master：8 个
- design-master：7 个
- tdd-master：8 个

## 2. 六项改造总览

| # | 改造项 | 落地结果 | 主要归属 |
| :--- | :--- | :--- | :--- |
| 1 | 稳定 ID 与全链路追溯 | `SOURCE → DESIGN → TEST → TASK` 全程使用稳定 ID；发布后不重排复用 | 三个 master |
| 2 | 开发任务 DAG | 新增 `开发任务图.md + task-state.json`，含依赖、wave、required/optional、状态和 fresh evidence | tdd-master |
| 3 | EARS 机器需求契约 | PRD 之外新增 `requirements.md`，使用 `WHEN … THE SYSTEM SHALL …` | prd-master |
| 4 | 跨需求正确性分析 | 新增冲突、歧义、未声明假设、边界、并发和不可验证指标闸门 | prd-master |
| 5 | 三档流程 | 新增 `standard / quick / tech-constrained`，模式只改变交互与研究深度，不降低契约门槛 | 三个 master |
| 6 | Bugfix 专用链路 | 新增 `REPRO/CUR/EXP/UNCH/CON` 行为链，贯通修复设计、回归测试与任务 DAG | 三个 master |

## 3. 升级后的总体契约

### 3.1 Feature 链路

```mermaid
flowchart LR
    A["prd-master<br/>PRD详细版.md"] --> B["requirements.md<br/>REQ / AC / NFR + EARS"]
    B --> C["requirements-analysis.md<br/>P0/P1 清零"]
    C --> D["design-master<br/>页面 / API / 数据 / 时序 / 技术方案"]
    D --> E["设计追溯矩阵.md"]
    E --> F["tdd-master<br/>分层 TDD + GOAL 契约"]
    F --> G["全链路追溯矩阵.md"]
    G --> H["开发任务图.md<br/>DAG + wave"]
    H --> I["task-state.json<br/>状态 + SHA-256 + evidence"]
```

### 3.2 Bugfix 链路

```mermaid
flowchart LR
    A["bugfix.md<br/>REPRO / CUR / EXP / UNCH / CON"] --> B["修复设计.md<br/>根因证据 + 最小修复面 + 回滚"]
    B --> C["设计追溯矩阵.md"]
    C --> D["复现 / 修复 / 不变行为 / 约束测试"]
    D --> E["Bugfix 任务 DAG"]
    E --> F["required 完成 + P0/P1 全绿"]
```

## 4. 稳定 ID 规则

### 4.1 需求层

| 对象 | 格式 | 示例 |
| :--- | :--- | :--- |
| 功能 | `Fnn` | `F03` |
| 用户故事 | `US-Fnn-nn` | `US-F03-01` |
| 行为需求 | `REQ-Fnn-nn` | `REQ-F03-02` |
| 验收条件 | `AC-Fnn-nn` | `AC-F03-04` |
| 非功能需求 | `NFR-nnn` | `NFR-006` |
| 假设 | `A-nnn` | `A-014` |

### 4.2 设计层

| 对象 | 格式 | 示例 |
| :--- | :--- | :--- |
| 页面 | `PAGE-Fnn-nn` | `PAGE-F03-01` |
| 组件 | `CMP-Fnn-nn` | `CMP-F03-04` |
| 接口 | `API-Fnn-nn` | `API-F03-02` |
| 数据实体 | `DATA-Fnn-nn` | `DATA-F03-01` |
| 时序/流程 | `SEQ-Fnn-nn` | `SEQ-F03-01` |
| 设计决策 | `DEC-nnn` | `DEC-008` |
| Bugfix 修复点 | `FIX-BUG-nnn` | `FIX-BUG-001` |

### 4.3 测试与任务层

- 测试沿用分层前缀：`U/C/I/E/S/B/A/P`。
- Bugfix 测试增加：`BR` 复现、`BF` 修复、`BG` 回归、`BP` 性质测试。
- Feature 任务：`TASK-Fnn-nn`。
- Bugfix 任务：`TASK-BUG-nnn-nn`。

共同规则：ID 一经发布不得重编号或复用；删除项保留并标 `retired`；语义变化递增 revision；拆分后旧 ID retired，新 ID 写 `supersedes`。

## 5. prd-master 详细变更

### 5.1 核心行为变化

1. 版本说明从 v0.3 升级到 v0.4。
2. 启动时先判断 `work_type=feature|bugfix`。
3. Feature 再选择：
   - `standard`：保留完整七阶段和逐阶段确认。
   - `quick`：阻塞问题前置，确认总蓝图后连续生成；若发现 P0/P1 自动回 standard。
   - `tech-constrained`：先固化硬 NFR、既有架构和禁改面，做可行性证据，再锁需求。
4. PRD 定稿后新增 `requirements.md`：稳定 ID + EARS 行为契约。
5. 新增 `requirements-analysis.md`：检查完整需求集合，而非只逐条审稿。
6. 正确性闸门要求 `P0 unresolved: 0` 且 `P1 unresolved: 0` 才能进入 design-master。
7. 新增 Bugfix 专用流程；不再让复杂缺陷走价值论证、竞品调研、方案辩论和 PPT。
8. `state.json` 新增：`work_type`、`workflow_mode`、`contract_revision`、`source_ids_changed` 和新的 deliverable 字段。

### 5.2 新增 Feature 产物

```text
output/
├── PRD详细版.md
├── requirements.md
├── requirements-analysis.md
├── PRD-summary.md
├── PRD-dev.md
└── ppt/...
```

### 5.3 Bugfix 产物

`output/bugfix.md` 至少包含：

- `BUG`：缺陷摘要
- `REPRO`：最小复现与证据
- `CUR`：当前错误行为
- `EXP`：预期正确行为
- `UNCH`：必须保持不变的行为
- `CON`：接口、数据、兼容性、安全或性能约束

prd-master 在 Bugfix 阶段不声明根因；根因必须由 design-master 基于代码、日志或运行证据分析。

### 5.4 跨需求分析的六类检查

1. 逻辑不一致
2. 含糊量词
3. 功能/NFR/安全/合规约束冲突
4. 未声明角色、实体、状态或外部系统假设
5. 缺失失败、边界、并发、幂等、重试和恢复路径
6. 没有阈值、单位、采样方式或时间窗的不可验证指标

### 5.5 prd-master 文件清单

| 类型 | 文件 | 变化 |
| :--- | :--- | :--- |
| 修改 | `SKILL.md` | 554 → 615 行；加入模式、需求契约、正确性分析和 Bugfix 路由 |
| 修改 | `docs/STATE-MANAGEMENT.md` | 180 → 192 行；加入 work_type/mode/revision/source impact |
| 新增 | `references/需求契约与模式路由.md` | 三档模式、稳定 ID、EARS、分析和增量同步 |
| 新增 | `references/Bugfix专用链路.md` | Bugfix 行为三分法和升级 Feature 条件 |
| 新增 | `templates/requirements.md` | Feature 机器需求模板 |
| 新增 | `templates/requirements-analysis.md` | 正确性分析模板 |
| 新增 | `templates/bugfix.md` | Bugfix 行为契约模板 |
| 新增 | `validators/check_requirements_contract.py` | 校验 REQ/AC Parent、EARS、Bugfix 必备项和分析清零 |

## 6. design-master 详细变更

### 6.1 输入契约变化

Feature 从只读 `PRD详细版.md` 改为读取：

```text
PRD详细版.md + requirements.md + requirements-analysis.md
```

Bugfix 改为读取：

```text
bugfix.md
```

如果 PRD 与 requirements 冲突，必须停止并回上游修订，不能由设计阶段任选一份继续。

### 6.2 新增输出

- `设计追溯矩阵.md`：每个 active source ID 映射到页面、组件、API、数据、时序、设计决策和真实文件。
- `change-impact.md`：上游 revision 变化时列出受影响设计 ID、文件、动作和 stale 状态。
- Bugfix：`修复设计.md`，包含根因证据、最小变更面、UNCH/CON 保护、风险、发布和回滚。

### 6.3 页面清单与页面模板变化

页面清单由 4 列改为 6 列：

```text
页面 ID | Source IDs | 所属阶段 | 功能模块 | 页面名称 | 功能范围描述
```

页面模板的元信息新增：

- `页面 ID`
- `Source IDs`

没有直接需求来源但设计上必要的门禁、异常或合规页面，必须写 `design-derived: DEC-nnn`；不得伪造 REQ/AC。

### 6.4 设计覆盖闸

- 每条 active REQ/AC/NFR 必须有矩阵行。
- `Design IDs / Artifact / Error or Invariant / Verification Surface` 不得为空或 TBD。
- 关键跨组件流程必须有 sequence diagram 或等价时序描述。
- 状态型实体必须定义合法、非法和并发迁移。
- 交付时不得存在 `missing / TBD / stale`。

### 6.5 Bugfix 设计纪律

- fresh reproduction 失败前，不声称根因已确认。
- 区分根因、诱因和表象。
- 只改变恢复 EXP 所需的最小设计面。
- 每个 UNCH/CON 必须有保护设计和验证面。
- 默认不重做 tokens、设计系统展示页或无关页面。

### 6.6 design-master 文件清单

| 类型 | 文件 | 变化 |
| :--- | :--- | :--- |
| 修改 | `SKILL.md` | 262 → 295 行；加入 requirements、追溯、增量和 Bugfix |
| 修改 | `references/页面清单规划师.md` | 页面清单升级为 6 列并加入稳定 ID |
| 修改 | `references/页面文档撰写师.md` | 强制从 Source IDs 定位需求，不再只靠关键词 |
| 修改 | `references/页面模板.md` | 元信息新增页面 ID 和 Source IDs |
| 新增 | `references/追溯与增量同步规范.md` | 设计 ID、矩阵、覆盖闸、revision/stale |
| 新增 | `references/Bugfix设计规范.md` | 根因证据、最小修复、风险和回滚 |
| 新增 | `validators/check_traceability.py` | 校验每个 active source 的设计覆盖 |

## 7. tdd-master 详细变更

### 7.1 职责变化

tdd-master 从“只定义测试终点”扩展为：

```text
测试终点（GOAL） + 执行路径（任务 DAG）
```

仍然不写生产代码；新增的是给 Coding Agent 消费的交付计划契约。

### 7.2 新增输出

```text
output/
├── 全链路追溯矩阵.md
├── 开发任务图.md
├── task-state.json
└── tests/
    ├── 验收门禁与GOAL契约.md
    ├── 测试索引.md
    └── 各层 TDD 文档
```

### 7.3 开发任务图固定字段

```text
ID | Outcome | Source IDs | Design IDs | Test IDs |
Depends On | Wave | Class | Done When | Status
```

规则：

- 任务必须按可独立验收的纵向行为切片，不能按“全部前端/全部后端/全部测试”水平切层。
- `Class=required|optional`。
- `Status=pending|in_progress|blocked|completed|stale`。
- 无依赖任务进入 Wave 1；后续任务 wave 必须晚于全部依赖。
- required 任务不能依赖 optional 任务。
- P0/P1 测试必须至少映射到一个 required 任务。
- Done When 必须包含 RED、GREEN、回退复红和回归证据。

### 7.4 task-state.json

新增字段：

- `schema_version`
- `work_type`
- `active_contract=requirements.md|bugfix.md`
- `source_hashes`
- 每个任务的状态、wave、required、source/design/test IDs、验证时间和 evidence

允许同一产品目录保留 Feature 与 Bugfix 历史契约，但同一轮只能激活一个 `active_contract`。

### 7.5 完成定义变化

旧定义：

```text
全部 P0/P1 测试转绿 = 交付
```

新定义：

```text
全部 required 任务 completed
+ 全部 P0/P1 测试转绿
+ 覆盖率/变异测试达到门槛
+ 安全层特例满足
= 交付
```

任务标 completed 必须带本次 RED/GREEN/回归命令、退出码和时间；只改 Markdown/JSON 状态不算完成。

### 7.6 Bugfix 测试要求

- `BR`：复现测试，当前实现必须按缺陷原因稳定 RED。
- `BF`：修复行为，修复后 GREEN，回退修复必须复红。
- `BG`：UNCH 和约束回归。
- `BP`：输入空间、解析、状态或并发复杂时可加入性质测试。

Bugfix 不默认全 8 层；先强制覆盖复现、修复、不变行为和约束，再根据真实影响面补相应层。

### 7.7 tdd-master 文件清单

| 类型 | 文件 | 变化 |
| :--- | :--- | :--- |
| 修改 | `SKILL.md` | 250 → 296 行；加入 source/design 输入、任务 DAG、Bugfix |
| 修改 | `references/TDD模板.md` | 每条测试从三件套升级为四件套 |
| 修改 | `references/测试单元设计师.md` | 强制 Source IDs + Design IDs + 真实产物 |
| 修改 | `references/验收门禁与GOAL契约规范.md` | GOAL 加入 required 任务闸 |
| 修改 | `references/执行纪律.md` | completed 也必须有 fresh evidence |
| 新增 | `references/开发任务图规范.md` | 任务切分、DAG、wave、状态、指纹和追溯 |
| 新增 | `references/Bugfix测试与修复规范.md` | 复现/修复/回归/性质测试规则 |
| 新增 | `validators/check_delivery_contract.py` | 校验追溯、任务、依赖、wave、状态和 SHA-256 |

## 8. 增量同步协议

当 source revision 或文件 SHA-256 改变时：

1. 从变更 source ID 出发。
2. 沿设计、测试和任务依赖求影响闭包。
3. 只把受影响项标 `stale`。
4. 未受影响 ID、决策和状态保持不变。
5. stale 项重新生成、评审并通过 fresh regression 后，才能恢复 `covered/completed`。

禁止直接覆盖新 hash 后继续沿用旧 completed 状态。

## 9. 兼容性与迁移说明

### 9.1 旧 Feature 项目

- design-master 对缺少 `requirements.md` 的旧项目允许从 PRD 派生一次。
- 派生后必须通过 prd-master 的需求契约校验，才可继续设计。
- 推荐维护者批量迁移旧项目，而不是长期依赖兼容分支。

### 9.2 页面清单消费者

页面清单从 4 列变为 6 列，是一个需要关注的格式变化。所有消费者应按表头名称读取，不应依赖固定列序号。现有“页面文档撰写师”已同步更新。

### 9.3 TDD 入口

新版 tdd-master 要求 `设计追溯矩阵.md`。旧项目若没有该文件，应先补跑 design-master 的覆盖矩阵步骤。

### 9.4 完成状态

旧的“P0/P1 全绿”不再单独等于交付。下游 Coding Agent 需要同步支持 `开发任务图.md + task-state.json`。

## 10. 主要失败模式与缓解

| 失败模式 | 后果 | 缓解 |
| :--- | :--- | :--- |
| 产物增多后互相失同步 | 设计/测试实现的是旧需求 | 稳定 ID、revision、SHA-256、stale 闭包 |
| quick 被理解为降低质量 | 快速模式漏掉高风险要求 | quick 只减少审批/研究，不取消契约和正确性闸 |
| 任务图按技术层切分 | Coding Agent 无法独立交付价值 | 强制纵向行为切片；测试在任务内先 RED |
| 只修改 completed 状态 | 假完成、无法审计 | fresh verification evidence + Markdown/JSON 一致性 |
| Bugfix 顺手扩成新功能 | 修复范围膨胀、回归不可控 | EXP/UNCH/CON 固定；需新增能力时另开 Feature |
| 全量重生所有产物 | 丢失确认历史、成本失控 | 只重生影响闭包，未受影响项保持不变 |

## 11. 已完成的验证

本地已完成：

- 237 项结构、引用、UTF-8 无 BOM 和能力落点检查通过。
- Feature 样例：`3 source → 3 tests → 2 DAG tasks` 通过。
- Bugfix 样例：`5 source → 4 tests → 2 DAG tasks` 通过。
- 安装后的 23 个目标文件与验证副本 SHA-256 全部一致。
- 安装前版本已完整备份。

## 12. 尚需维护者执行的原生验证

当前执行环境没有可用 Python 解释器，因此以下 Python 文件已完成结构与等价契约验证，但**没有在本机原生执行**：

- `check_requirements_contract.py`
- `check_traceability.py`
- `check_delivery_contract.py`
- skill-creator 的 `quick_validate.py`

维护者应在有 Python 的环境运行：

```bash
python /path/to/skill-creator/scripts/quick_validate.py /path/to/prd-master
python /path/to/skill-creator/scripts/quick_validate.py /path/to/design-master
python /path/to/skill-creator/scripts/quick_validate.py /path/to/tdd-master

python prd-master/validators/check_requirements_contract.py \
  project/output/requirements.md \
  project/output/requirements-analysis.md

python design-master/validators/check_traceability.py \
  project/output/requirements.md \
  project/output/设计追溯矩阵.md

python tdd-master/validators/check_delivery_contract.py \
  project/output
```

Bugfix 的第一个 validator 参数改为 `project/output/bugfix.md`。

## 13. 维护者建议复核清单

- [ ] 确认三档模式与团队实际成本模型一致。
- [ ] 确认稳定 ID 命名不会与现有项目编号冲突。
- [ ] 确认所有页面清单消费者支持 6 列格式。
- [ ] 确认 Coding Agent 能读取开发任务图并按 wave 执行。
- [ ] 确认 task-state.json 的 evidence 结构满足团队审计要求。
- [ ] 用真实复杂 Feature 做一次 standard forward test。
- [ ] 用成熟小功能做一次 quick forward test。
- [ ] 用严格延迟/合规项目做一次 tech-constrained forward test。
- [ ] 用历史上发生过回归的缺陷做一次 Bugfix forward test。
- [ ] 验证上游 revision 改变后，只把影响闭包标 stale。
- [ ] 在 CI 中加入三个新增 validator。

## 14. 已知技术债

1. `prd-master/SKILL.md` 从 554 行增至 615 行，超过 skill-creator 建议的 500 行。后续建议把阶段 5/6 的详细执行协议继续下沉到 references，主文件只保留路由和硬门禁。
2. 三个 skill 当前没有统一的 JSON Schema 文件；`task-state.json` 由 Markdown 规范和 Python validator 共同约束。维护者如要接 CI/IDE，建议补正式 schema。
3. Python validators 尚未在本地 Python 运行时编译执行，这是合并前必须补做的最后验证。
4. 本次未修改 `agents/openai.yaml`；若维护仓库采用 skill-creator 推荐的 UI metadata，应核对 description 更新后是否需要重新生成。

## 15. 建议的维护者合并策略

建议按以下顺序审查和合并：

1. 先合并 prd-master 的稳定 ID、requirements 和正确性分析。
2. 再合并 design-master 的追溯矩阵及页面 6 列格式。
3. 最后合并 tdd-master 的全链路追溯、任务 DAG 和状态契约。
4. 三个 validator 全绿后，再启用 Bugfix 和 quick 模式。
5. 对一个真实项目跑完整链路，确认下游 Coding Agent 不再自行猜开发顺序。

核心验收标准只有一句：

> 任意一个 active source 行为，都能一路找到它的设计落点、测试用例、开发任务、执行状态和最新验证证据。