# Dev Master

> 研发全生命周期单一流程（13 阶段）。管理 24 个研发链技能：规格真源 → 功能清单 → 概要设计（含威胁建模）→ 详细设计 → 任务分解 → **接手设计稿** → 编码实现 → 原型标注 → 测试 → 调试验收 → 上线审计 → 文档发版 → 分支收尾。 **设计稿不在本链产出**：由 `pm-master` 阶段 8（`ui-ux-pro-max`）出稿，本链阶段 6 只校验、登记与回扫。 能力：(1) 单点需求直接路由到最合适的技能 (2) 多步需求按同一条流程裁剪出阶段区间并编排 (3) 保证上一步产出是下一步的合法输入（**分层真源门禁**贯穿全程：设计稿管 UI 层、SRS 管规则层）(4) 支持默认/深度档换挡、断点续跑。 触发词：「dev-master」「研发总控」「开发总控」「技术总控」「我该用哪个开发技能」「帮我把这个需求做出来」 「从需求到上线」「完整开发流程」「走完整研发流程」「一键开发」「从0到1开发」「整套系统开发」 「三端开发」「全栈开发」，或者用户描述了一个研发场景但没指明用哪个技能、或任务明显需要多个研发技能接力时。 别名：dve-master（笔误也能命中本技能）。 不适用：产品侧的战略/调研/画像/优先级/PRD、**以及界面设计稿/高保真原型/可点原型**（那条链走 `pm-master`）。

- Skill: `idwong/dev-master` (Agent Skill, multi-file: 18 files)
- Install (CLI): `npx skillmds@latest add idwong/dev-master`
- Raw SKILL.md: https://api.skillmd.com/api/skills/idwong/dev-master/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: iDWong (https://skillmd.com/u/idwong)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/idwong/dev-master

---


# dev-master：研发全生命周期总控

> 定位：**研发侧的入口 + 唯一流程**。你不亲自产出内容，你的工作是：判断这是单点还是多步 →
> 单点直接路由，多步按同一条流程裁剪出阶段区间 → 保证上一步产出是下一步的合法输入。
>
> **库里只有一条流程。** 所谓「快速开发」「只补文档」「上线体检」都是同一条流程的裁剪，**阶段编号永不改变**。

## 与 pm-master 的边界

| | `pm-master` | `dev-master`（本技能） |
|---|---|---|
| 管什么 | 产品侧：战略 → 调研 → 画像 → 优先级 → 路线图 → PRD → **界面设计稿** | 研发侧：SRS → 实现 → 测试 → 上线（**不出设计稿**） |
| 交接点 | 它的阶段 5 产出需求文档 | 本流程的**阶段 1** 接手，把 PRD 转写成 SRS（规则层真源）|
| 重叠技能 | `req-doc` / `page-generator` / `pm-test-cases` 等在两条链上都出现 | **同一份技能，不是两份**；谁在跑就由谁编排，不要两个总控同时起流程 |

用户从 `pm-master` 一路跑到需求文档后说「开始开发」→ 交给本技能，从阶段 1 的门禁检查接手。

> **设计稿归产品链，本链不做。** `ui-ux-pro-max` **不是研发链技能**——设计稿由 `pm-master` **阶段 8** 产出，
> 落 `design-system/`；本流程的**阶段 6 只接手**（校验 → 登记 `DESIGN_SOURCE` → 回扫），不调任何 UI 技能。
> 缺稿又要做界面 → **停下来路由 `pm-master` 跑它的阶段 8**，不要自己补一版：
> 两条链各出一版稿，`design-system/` 会被互相覆盖，且阶段 10 的四方签字基线对不上。

> **`task-breakdown` 是两条链共用的同一个技能**（`pm-master` 阶段 11 / 本流程阶段 5），共用仓库根同一份 `issues/`。
> 产品链已经拆过时，本流程**续用不重拆**——重拆会把 `done/` 的历史冲掉；只需补研发侧新增的任务并重排顺序。

### 重叠产物：四类文档两条链都会出，各归各根

阶段 9/12 与 `pm-master` 阶段 9/10 用的是**同一个技能**，但产出**不是同一份东西**，
落盘也各归各根（研发侧 `dev/`、产品侧 `prd/`）。
**看到 `prd/` 下那份：不要删、不要覆盖，也不要因为它存在就认为自己这一步已经做过。**

| 产物 | 本流程（`dev/`） | `pm-master`（`prd/`） |
|---|---|---|
| 测试用例 | 阶段9 `dev/test/`——用例 + `webapp-testing` **真跑过**的执行报告与缺陷清单，带截图证据，回答「实际跑通没有」 | 阶段7 `prd/test/`——从 `SPEC_SOURCE` 推导的**验收用例，未执行**，回答「该验哪些」 |
| 操作手册 | 阶段12 `dev/release/`——照**真实实现**写，另含发布与回滚预案，面向运维与发布 | 阶段8 `prd/release/`——照需求文档与设计稿写，面向最终用户 |
| 发版说明 | 阶段12 `dev/release/`——随 `release-rollout` / `finishing-branch` 出的**变更与回滚**记录 | 阶段9 `prd/release/`——按路线图讲**这一版给用户带来什么** |
| 上线审计 | 阶段11 `dev/reports/` | 阶段10 `prd/reports/` —— **这两个是同一件事**，见下 |

**上线审计只跑一次。** 两边都是 `pm-ai-ship-audit`、硬输入都是 `dev/code/`、产出也一样，
真实差别只有落盘目录。**本流程是出代码的那条链，审计以 `dev/reports/` 为准**；
`prd/reports/` 下已有产品侧跑过的报告时，读它避免重复发现，但结论仍落 `dev/reports/`。

前三类则**不要**因为 `prd/` 下已有就跳过：那边是文档态、没执行过，
替代不了本流程「真跑 + 证据」的要求（阶段9 铁律：只写真正执行过的结果）。

`pm-master` 侧有一张对称的表，口径一致；改一处必须同步另一处。

## 分诊（三类，先判这个）

| 类型 | 特征 | 怎么办 |
|---|---|---|
| **单点类** | 要的是一份可交付物，且只要这一份（「写个详细设计」「生成测试用例」） | 按下方路由表选 1 个技能，**不要起流程** |
| **流程类** | 横跨多步、说了「从需求到上线 / 完整开发 / 三端全做 / 从 0 到 1」 | 起流程：定裁剪 → 建任务清单 → 逐阶段执行 |
| **排障类** | 现成代码出了问题、要定位（「这个 bug 怎么回事」「为什么跑不起来」） | 直接 `systematic-debugging`，**不要起流程** |

判不清单点还是流程：**问一句「只要这一份，还是要往后接着做？」** 不要自己假设。

## 一条流程，13 个阶段

**阶段的权威定义在 `workflow-catalog.yaml`**（机器可读：每阶段的技能、细则文件、产出 glob、门禁条目、跳过条件、裁剪区间）。
下表是它的人读摘要，**两者不一致时以 YAML 为准**；改阶段必须改 YAML，只改表会被自检拦下。

**档位在入口就问定**（见 `references/flow-engine.md` Step 0），不是等用户嫌浅了再换。

| # | 阶段 | 默认档 | 深度档 | 产出 |
|---|---|---|---|---|
| 0 | 项目初始化 | `project-init`（CI/钩子/定时任务配 `workflow-automator`） | — | 仓库骨架 + `README-DEV.md` + CI 配置 |
| 1 | **规格真源（规则层）** | `req-doc`（SRS） | — | `dev/SRS/*.md` ← **不可跳过**，登记 `SPEC_SOURCE` |
| 2 | 功能清单 | `feature-list` | — | `dev/design/*功能清单*.md`/`.xlsx` |
| 3 | 概要设计 | `hld-design`（安全侧配 `threat-model`） | — | `dev/design/*概要设计*.md` + `dev/design/威胁模型-*.md` |
| 4 | 详细设计 | `lld-design` | — | `dev/design/*详细设计*.md`（表结构 + 接口 + 模块） |
| 5 | **任务分解** | `task-breakdown` | — | `issues/`（五格 + `kanban.md` + `gaps.md`） |
| 6 | **接手设计稿（UI 层真源）** | **不调技能**——稿由 `pm-master` 阶段 8 产出 | — | 校验 `design-system/` → 登记 `DESIGN_SOURCE` → **回扫阶段 2/3/4/5** |
| 7 | **编码实现** | `page-generator`（页面级／单端） | `dev-fullstack-product`（三端全栈 0-1，带三轮测试与 12 角色评审） | `dev/code/` |
| 8 | 原型标注 | `annotation` | — | 页面内标注层 |
| 9 | 测试 | `pm-test-cases`（用例）+ `webapp-testing`（真跑） | `test-driven-development`（先写测试驱动实现） | `dev/test/*测试用例*.md` + 测试报告 |
| 10 | 调试与验收 | `dev-code-review`（评审）+ `verification-before-completion`（终检） | `systematic-debugging`（有具体故障时） | `dev/reports/代码评审-*.md` + 缺陷闭环记录 |
| 11 | 上线审计 | `pm-ai-ship-audit` | — | `dev/reports/` |
| 12 | 文档与发版 | `pm-operation-manual` + `pm-release-notes` + `release-rollout` + `finishing-branch` | — | `dev/release/` 手册 / 发版说明 / **发布与回滚预案** + 分支收尾 |

> **产出路径一律按 glob 匹配**：各技能的实际命名带项目名／日期／版本号，写死精确文件名门禁永远过不了。
> 落盘根一律是 `dev/`，见下方「落盘目录」一节；`docs/` 只做只读兼容。

> **阶段 7 的档位有硬区别**：`page-generator` 是「在已有项目里加页面」，`dev-fullstack-product` 是
> 「移动端 + 管理端 + 后端三端 0-1 全栈交付」，后者**自带阶段 9/10/11 的等价环节**（三轮真跑测试 +
> 12 角色专家评审）。选了深度档时，阶段 9–11 改为**校验它的产出是否达标**，不要重复跑一遍。

**阶段 1 对阶段 2–8 仍是硬前置**——规则层真源缺了，下游照样缺字段、缺校验、缺状态机。
裁剪区间**完全不含 2–8** 时（「上线体检」只跑 11、「单页面/小改」7,9,10、「热修复」）才可以不跑阶段 1，
且要在进度存档里标明「本次裁剪不依赖 `SPEC_SOURCE`」。其余阶段的跳过判据见 `references/tailoring.md`。

**阶段 6 对阶段 7/8/9/10 是 UI 层的硬前置**：这四个阶段凡涉及页面、交互、文案、令牌的判定，
一律以 `DESIGN_SOURCE` 为准，不再回头问 SRS。**但阶段 6 本身不出稿**——它只校验并登记 `pm-master` 阶段 8 的产出。
设计稿缺失而用户又要求「1:1 还原」时**不能跳阶段 6**，正确动作是**路由 `pm-master` 补出稿**，不是本链自己画。

**读这几个文件再动手（不要凭记忆跑流程）：**
- `workflow-catalog.yaml` — 阶段、产出 glob、门禁、裁剪的**权威定义**；起流程时先读它
- `references/flow-engine.md` — Step 0 初始化四问、任务清单规范、阶段间传递门禁、并行规则、确认节点、进度汇报格式、目录规范、断点续跑
- `references/tailoring.md` — 裁剪表与逐阶段跳过判据、默认档／深度档换挡规则
- `references/stages/s<N>-*.md` — 每个阶段的执行细则，**进入该阶段时只读那一个**，不要一次全读
- `references/delivery-review.md` — **开发交付闭环验收检查机制**（五阶段：设计稿 1:1 还原 → 三端页面覆盖
  → 接口连通 → 数据落库 → 测试闭环，外加五方对齐、问题分级与证据留存、准入准出与禁止上线清单）。
  **阶段 9–11 的判据以它为准**；与 `dev-fullstack-product` 下的同名文件是**同一份**，改一处必须同步另一处

## 真源分层：设计稿管 UI，SRS 管规则

**本流程没有「唯一真源」，有两个真源，各管一层。** 判定归属看它写进代码之后落在哪儿：
落进样式/布局/组件树 → UI 层；落进校验函数、状态机、SQL、接口契约 → 规则层。

| 层 | 管什么 | 真源 | 变量 |
|---|---|---|---|
| **UI 层** | 页面清单与路由、布局与信息层级、组件选型与八态、交互流程与分支、按钮与文案措辞、设计令牌（色值/字号/间距/圆角/阴影）、图标、空态与错误态的**呈现** | **设计稿** `design-system/`（`FLOWS.md` · `HANDOFF.md` · `tokens.json` · `*.html`）—— **由 `pm-master` 阶段 8 产出，本链只读** | `DESIGN_SOURCE` |
| **规则层** | 字段与类型、必填与校验、枚举取值、状态流转、权限与数据可见性、错误码、表结构与索引、接口契约、幂等与并发、非功能指标 | **SRS** `dev/SRS/*.md` | `SPEC_SOURCE` |
| 背景层 | 为什么做、业务目标、优先级 | PRD `prd/PRD/*.md`（只读） | — |

**PRD 不参与任何判定**，连 UI 层也不是——它解释动机，不裁决实现。

### 冲突怎么裁（三条，逐条判）

1. **UI 层冲突**（同一页面/字段位置/文案/组件形态两边说法不一）→ **设计稿赢**，回改 SRS 并在进度存档记一行。
2. **规则层冲突**（设计稿画出的校验/枚举/状态流转/权限与 SRS 不一致）→ **SRS 赢**，回阶段 6 修稿。
   **不许让代码两头各实现一遍。**
3. **跨层冲突**（设计稿有而 SRS 完全没有，或 SRS 有字段而设计稿无页面）→ **谁都不自动赢**，
   按 `issues/gaps.md` 的 G2/G3 登记后停下来问用户，**禁止静默选一边**。

### 设计稿通常在起流程前就有了（先扫一遍再决定要不要打标记）

设计稿由 `pm-master` **阶段 8** 产出，而产品链跑在研发链**前面**——所以**正常情况下起流程时
`design-system/` 已经存在**。Step 0 就要扫一次：

```bash
ls design-system/index.html design-system/web-index.html design-system/admin-index.html 2>/dev/null
```

- **有稿（常态）** → **当场登记 `DESIGN_SOURCE`**，阶段 2/3/4/5 全程有 UI 层真源可用，
  **不需要打任何待回填标记**；阶段 6 退化为「校验签字 + 回扫（结果自然为空）」。
- **无稿**（产品链还没跑到阶段 8 就先开工）→ 走下面的兜底：
  - 阶段 2/3/4/5 **不中止、不等待**，UI 层判断先按 SRS 写并就地打标记 **`⏳ 待回填（阶段6 设计稿）`**；
  - 到阶段 6 仍无稿且本次要做界面 → **停下来路由 `pm-master` 跑它的阶段 8**，拿到稿再回来；
  - 稿到位后**必须回扫阶段 2/3/4/5**，逐个 `⏳` 按上面三条裁决消掉——这是阶段 6 的门禁条目。

**规则层冲突要退回产品链修稿**（设计稿画出的校验/枚举/状态流转与 SRS 不一致时）：
本链没有出稿动作，**不要自己改 `design-system/`**，那会让两条链的稿分叉。

纯后端项目或阶段 6 按判据跳过 → 登记 `DESIGN_SOURCE=无（理由）`，**UI 层整层不适用**，
SRS 恢复为全部内容的真源，回扫与冲突裁决都不触发。这行必须出现在进度存档里，
否则阶段 10 的交付验收会因为找不到设计稿基线而退回阶段 6。

规则原文见 `../common/prd-to-srs-gate.md` **§6**。

## 落盘目录：研发链产出一律进 `dev/`

**唯一落盘根是 `dev/`**（记作 `DEV_DOC_ROOT`）。13 个阶段的文档产出全部落这儿，与产品侧的 `prd/` 彻底分开——
`prd/` 由 `pm-master` 那条链写（战略/调研/画像/优先级/路线图/PRD/可研），本流程**只读**；
`docs/**` 是旧根，也**只读兼容**（存量项目的老文档）。

```
dev/
├─ SRS/                     阶段 1   规则层真源（SPEC_SOURCE 指这儿；UI 层真源是 design-system/）
├─ design/                  阶段 2/3/4  功能清单 · 概要设计 · 详细设计 · error-codes.md · 数据字典
├─ plan/                    （存量项目的 delivery-plan-*.md 留这儿只读；该技能已删除）
├─ test/                    阶段 9/10  测试用例 · 测试报告 · 缺陷清单与闭环记录
├─ reports/                 阶段 11  上线审计报告（阶段 7 深度档的 12 角色评审报告也落这儿）
├─ release/                 阶段 12  操作手册 · 发版说明
├─ code/                    阶段 7   **应用代码**：各端子项目（`admin/ mobile/ h5-app/ server/ backend/ web/ shared/`）；
│                                    单端项目直接是 `dev/code/src/`
└─ dev-master-{项目名}.md    流程进度存档
```

**`dev/code/` 只放应用代码**：仓库级基建（`docker-compose*.yml`、`Caddyfile`、CI 配置、`hooks/`、
`scripts/`、部署文档）留在**仓库根**；子项目自己的 `README-DEV.md`、`.env.example`、lint 配置、
`migrations/` 跟着子项目走，即在 `dev/code/<子项目>/` 下。

四条规则：

1. **写一律 `dev/`，读 `dev/` 优先，再看 `prd/`（上游产品文档）、`docs/**` 兜底（存量项目）。**
   `req-doc` / `feature-list` / `hld-design` / `lld-design` 的默认落点已经是 `dev/` 下对应目录，
   直接调即可；`pm-test-cases` / `pm-operation-manual` / `pm-release-notes` / `pm-ai-ship-audit` 两条链共用
   （产品链落 `prd/`），**在本流程里要显式指到 `dev/test|release|reports/`**。写完再搬会断图片相对路径与交叉引用。
2. **图片放各文档同级 `images/`**（如 `dev/design/images/`），不要集中到一个目录，跨目录引用在 Word 导出时会丢图。
3. **老项目命中 `docs/` 里的历史产出：原地续用，不主动搬家**，在进度存档里登记真实路径即可。
   用户明确要求迁移才迁；迁移时同级 `images/` 一起搬，并回改 md 里的相对引用与全部交叉链接。
4. `prd/`（旧项目 `docs/PRD/`）是上游产物**只读不写**；**`design-system/` 同样是上游产物、同样只读不写**
   （由 `pm-master` 阶段 8 写入；设计稿与设计令牌同树）、
   `tools/`（生图与一次性脚本）、**`issues/`（阶段 5 任务分解，两条链共用）**不在 `dev/` 下，保持各自约定。存量项目的代码在仓库根（`src/`、
   `admin/`、`server/` …）时**原地续用不搬家**，除非用户要求迁到 `dev/code/`。

## 常用裁剪（细则见 tailoring.md）

| 裁剪 | 阶段区间 | 什么时候用 |
|---|---|---|
| 全量（从 0 到 1） | 0 → 12 | 新项目，代码还没有 |
| 三端全栈 0-1 | 0,1,2,3,4,5,6,**7深度档**,9,10,11,12 | 移动端 + 管理端 + 后端一起做 |
| 有 SRS 直接开工 | 5 → 12 | 文档齐了，只要实现 |
| 只要文档链 | 1,2,3,4 | 交付设计文档，不写代码 |
| 迭代（老项目加功能） | 1,5,7,9,10,12 | 已有代码库，加一批功能 |
| 单页面 / 小改 | 7,9,10 | 加一两个页面 |
| 上线体检 | 11 | 代码已经写完（尤其 AI 写的），只要审计 |
| 热修复（线上出事） | 10 → 7 → 9 → 12 | 线上有故障。入口是阶段 10 的 `systematic-debugging` 先定位，改完只回归受影响范围 |
| 反向补文档 | 1,3,4（各技能的反向同步模式） | 代码先行，文档缺失 |

## 单点路由表

用户只要一份产出时用这张表，**不要起流程**。

| 用户在说什么 | 路由到 | 备注 |
|---|---|---|
| 要 SRS / 需求规格说明书 / PRD 转 SRS | `req-doc` | 研发侧**规则层**真源（UI 层真源是设计稿） |
| 功能清单 / 功能列表 | `feature-list` | 从 SRS+可研提取 |
| 概要设计 / 系统架构 / 分层与模块划分 | `hld-design` | |
| 详细设计 / 表结构 / 接口设计 / 类图 | `lld-design` | 三合一，不要拆成三份文档 |
| 威胁建模 / 安全设计评审 / STRIDE / 攻击面 / 越权设计 | `threat-model` | 阶段 3 之后、阶段 4 之前做；写完代码再查是 `pm-ai-ship-audit` |
| 任务分解 / 拆任务 / 切片 / 看板 / 三源对不对得上 / 开发顺序 / 下一步做什么 | `task-breakdown` | 也管进度追踪与自动连跑；取代已删除的旧交付计划技能 |
| 设计稿 / 高保真原型 / 可点原型 / 预览墙 | **`pm-master`**（它的阶段 8 调 `ui-ux-pro-max`） | **不在研发链内**。它是 UI 层真源的产出方，本链只接手 |
| 前端界面实现 / 组件 / 落地页要好看 | `frontend-design` | 只要设计建议不写码 → 转 `pm-master` |
| 磨砂玻璃 / 深浅双主题 / 材质与层级 | **`pm-master`** | 材质层并在 `ui-ux-pro-max` 里（规则在它 `references/` 下的 `design-system.md` 第四节），**属设计侧**；研发侧只按 `design-system/tokens.json` 落地 |
| 加一个页面 / 实现某个功能页 | `page-generator` | 在**已有项目**里加 |
| 整套系统做出来（三端 + 测试 + 评审） | `dev-fullstack-product` | 0-1 全栈 SOP |
| 原型标注 / 给页面加需求说明 | `annotation` | |
| 流程图 / 架构图 / 时序图 / ER 图 | `diagram-generator` | 文档里所有图一律走它，禁止手绘 |
| 测试用例 / 验收标准 | `pm-test-cases` | |
| 真的把 Web 应用跑起来点一遍 | `webapp-testing` | 要出正式用例文档 → `pm-test-cases` |
| 先写测试再写实现 | `test-driven-development` | |
| 这个 bug 怎么回事 / 为什么跑不起来 | `systematic-debugging` | |
| 代码评审 / 看看这个 PR / 合并前把关 | `dev-code-review` | 评「这次改动」；Claude Code 里要快评不留档用内置 `/code-review` |
| 做完了，帮我确认真的做完了 | `verification-before-completion` | |
| AI 写的代码能不能上线 / 安全性能审计 / 代码和文档对不上 | `pm-ai-ship-audit` | |
| 操作手册 / 用户指南 | `pm-operation-manual` | |
| 发版说明 / release notes | `pm-release-notes` | 面向用户的文案 |
| 发布方案 / 灰度 / 回滚预案 / 出事怎么退回去 | `release-rollout` | 面向自己人的操作手册，落 `dev/release/` |
| 分支做完了怎么收尾（合并/PR/丢弃） | `finishing-branch` | |
| 新项目脚手架 / 初始化 | `project-init` | |
| CI/CD 配置 / Git Hooks / 定时任务 / 自动化脚本 | `workflow-automator` | 阶段 0 落基建，阶段 12 补发布流水线 |
| 产品侧的事（战略/调研/画像/优先级/PRD/**设计稿**） | `pm-master` | 不在本流程内 |

路由后说明选择理由（一句话），确认后加载执行。用户明显着急或指令明确时**直接执行，不要多问**。

## 贯穿全程的三条铁律

1. **分层真源门禁**：UI 层认设计稿、规则层认 SRS，**PRD 两层都不认**。只有 PRD 时走 `req-doc` **Step F** 转写。
   规则原文在 `../common/prd-to-srs-gate.md`（§1–§5 是 SRS 门禁，**§6 是分层真源**），
   **进流程前把 §6 读一遍**，不要凭记忆执行——旧口径「SRS 是唯一真源」已经作废。
2. **图一律走 `diagram-generator`**：所有阶段产出的文档里的流程图/架构图/时序图/ER 图都由它生成，禁止手绘。
   改过文案的图**必须重渲**（`mermaid`/`drawio` 源与图片 mtime 对不上就是过期）。
3. **Word 导出放在最后**：导出读的是**启动那一刻的 md**，任何编辑之后都要重新导出，否则 docx 静默过期。
   导完必须验图：`unzip -l x.docx | grep -c 'word/media/'` 要等于图片张数。

### 没配端点时怎么办（新装的库默认没配，别卡在这儿）

图表渲染与 Word/xlsx 导出都要技能根的 `config.json`（`diagramApiUrl` / `apiBaseUrl`），
从 `config.example.json` 复制后自己填。**没配不阻断流程**，按下面降级并在产出里标一行：

| 能力 | 没配时 | 降级做法 |
|---|---|---|
| 图表渲染 | `render-diagram.*` 明确报错（不是静默失败） | 图改用 **mermaid 代码块内嵌 md**（Claude Code 与 GitHub 都能渲染），文档里标注「图为 mermaid 源码，未出 PNG」；drawio XML 仍可用 `validate-diagram.*` 本地校验 |
| Word / xlsx 导出 | `export-word.*` 报「无法读取 apiBaseUrl」 | 交付 md，阶段 12 的交付清单里注明「Word 未导出（未配端点）」 |

**降级不等于可以手绘 ASCII 流程图**——mermaid 源码仍是结构化的，手画的框线图不是。

## 工具层（不占阶段，按需调用）

| 技能 | 什么时候用 |
|---|---|
| `diagram-generator` | 任何阶段要出图 |
| `common/export-word.*` | 文档类阶段要交 Word（阶段 1/2/3/4/9/12） |

## 输出格式（每阶段固定）

```
【阶段 N：名称】
- 本阶段目标：
- 调用技能：（默认档/深度档）
- 已完成内容：
- 产出文件：（真实路径）
- 门禁检查：（下一阶段需要的输入是否齐备）
- 待用户确认事项：
- 下一步计划：
```