# Spec Change

> 统管需求变更的回流：把对已有特性的任何改动按「先文档后代码」的铁律同步回 PRD → 原型 → 设计 → plan，复用原 NNN、续编 R/F 与 AE/AC、不重排。Use when 客户/内部对已上线或在研特性提出改动、原型评审后要变更需求、开发中发现需求漏洞要回流。全新特性请改用 /spec-prd。

- Skill: `yisean/spec-change` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yisean/spec-change`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yisean/spec-change/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: yisean (https://skillmd.com/u/yisean)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yisean/spec-change

---


# 变更阶段：需求变更回流（先文档后代码）

**当前年份 2026**。

这是横切流水线的**变更管理** skill。它不引入新阶段，而是保证任何改动都遵守两条铁律：

> **铁律一**（workflow 全景）：允许阶段回流，但**产出物要同步更新，保持单一事实源**。
> **铁律二**（workflow 开发阶段）：**改动需求范围时，先回流更新 PRD/设计/plan，再继续写代码。**

## 术语提示

功能需求用 **R/F** 编号、验收用 **AE/AC** 编号（详见 `/spec-prd` 术语表）。变更时的头号纪律：**续编不重排**——新增需求往后接（如已有到 R15，新增是 R16、R17），绝不重编已有需求号，否则历史追溯全失效。

**多人并发改同一特性时**：续编 `R/F` / `AE/AC` 前**先 `git pull --rebase` 到最新**，从合并后的真实最大号往后接，避免两人都从 R15 撞出 R16。万一仍撞号，由 `/spec-check` C1（编号重复=FAIL）在合并/评审前兜底拦截。特性号 `NNN` 的唯一性见 `docs/engineering/workflow.md`「取号约定」（先登记后开工）。

## 核心原则

1. **先文档、后实现** — 永远先改 PRD（必要时原型、plan），最后才动代码。
2. **复用序号** — 增量改动属于原特性，复用原 `YYYY-MM-DD-NNN`，**不新建 PRD**。
3. **续编 + 标注** — 续编 `R/F`，补/调对应 `AE/AC` 并标注覆盖的需求号；增量单列一节并标日期。
4. **单一事实源** — 同一条信息只在一处维护，改一处即全链生效；本 skill 的两条铁律源自 `docs/engineering/constitution.md`（工程宪法，不可妥协原则），项目有该文件时以其为准。

## 执行流程

### Phase 0 · 判定变更类型

- **增量变更**（属于某个已有 PRD 的主题）→ 继续本流程，复用原 `NNN`。
- **全新特性**（能独立一句话说清解决谁的什么问题）→ **停下**，建议改用 `/spec-prd` 走完整新链路（取新 `NNN`）。

### Phase 1 · 定位受影响产出物

顺着同一 `NNN` 找齐：
- `docs/product/prd/…-NNN-*.md`（要回流的 PRD）
- `docs/product/brainstorms/`（可选：先开一份带日期的增量探讨稿，如 `YYYY-MM-DD-<slug>-requirements.md`）
- `docs/engineering/prototype/`（涉及界面的页面）
- `docs/engineering/design/…-NNN-*.md`（技术设计：架构/接口/ER/详细设计）
- `docs/engineering/plans/…-NNN-*.md`（实现计划）

### Phase 1.5 · 波及面扫描（横向：找出会影响到的其他特性）

变更回流前，先确认这次改动是否会**波及别的特性（别的 NNN）**——改一个接口/表/共享组件，往往别的特性正依赖它。spec 全是可检索文本，所以**按需现扫，不预存依赖表**：

1. **列共享面**：写出本次改动触及、且可能被多特性复用的对外面：
   - 接口签名（路径/方法/出入参）、表名/字段、公共枚举/字典、被多页面复用的原型组件。
2. **全 `docs/` 检索**：拿这些名字在 `docs/product/prd`、`docs/engineering/design`、`docs/engineering/plans`、`docs/engineering/prototype` 里检索，**列出命中的其他 NNN**（排除本特性自己的 NNN）。
3. **逐个判定**：对每个命中标「**真波及 / 不波及**」。真波及的单独记一行：`受影响特性 NNN → 命中位置 → 影响点 → 处置`。
4. **决定处置方式**：
   - 影响小、同主题 → 顺带在本次变更里一并回流（各自 NNN 的产出物都更新）。
   - 影响大、独立主题 → 拆成对方 NNN 的独立 `/spec-change`，本次只记录依赖、不越界改。
5. **扫不到 ≠ 没有**：检索是粗筛；若改的是底层公共面，宁可多看一眼。命中为空时在收尾里显式写「无跨特性波及」。

> 这一步只**发现并定范围**，真正的对外兜底核对由 `/spec-check` 的跨特性引用检查在事后再过一遍。

### Phase 2 · 按顺序回流（铁律：自上而下）

1. **改 PRD**（必做）：
   - 新增一节标明是增量并标日期（如 `## §X 增量（YYYY-MM-DD）`）。
   - **续编 `R/F`**（接着原最大号往后，不重排）。
   - 补/调 `AE/AC`，每条标注覆盖的需求号。
   - 同步「目标/非目标/待解决问题」如有变化。
2. **改原型**（涉及界面才做）：按 `/spec-prototype` 与 `prototype/_spec.md` 更新对应页面，并保持入口在 `index.html`。
3. **改设计**（涉及架构/接口/数据模型才做）：按 `/spec-design` 更新 `docs/engineering/design/…-NNN-*` 的概要设计/ER/详细设计，保持与续编后的 `R/F` 对齐。
4. **改 plan**：在原 plan 补/改 Implementation Units，更新追溯映射与单元的「设计依据」；DB 变化落 `docs/ops/install/migration-YYYY-<特性名>.sql`，与设计 ER 一致。
5. **最后改代码**：在特性分支按更新后的 plan 实现。

### Phase 3 · 验收与提交

- **更新覆盖矩阵**：把本次续编的 `R/F` / `AE/AC` / 实现单元补进 PRD 与 plan 的覆盖矩阵，确认新需求都有验收、新验收都挂到需求、无悬空、无重排。
- 按新增/变更的 `AE/AC` 逐条验证。
- **提交分开打、用对 type**：文档变更 `docs(prd)` / `docs(brainstorm)`，代码 `feat` / `fix`。
  （参考一次真实变更的提交序列：`docs(brainstorm): …需求文档` → `feat: …` → `docs(prd): …（§X 增量）`。）

### Phase 4 · 收尾

输出：本次变更触达的 PRD/原型/plan 路径、新增的需求号范围（如 R16–R19 / AE7–AE8）、对应提交。确认所有产出物已同步、单一事实源一致。

**跨特性波及小结**（来自 Phase 1.5）：列出真波及的其他特性 NNN 及处置（顺带回流 / 已拆独立变更 / 仅记录依赖）；无波及则显式写「无跨特性波及」。建议变更后对受影响的各 NNN 跑一次 `/spec-check` 兜底。