# Requirement Analysis

> 需求设计工作流——在任何创造性开发工作（新功能、新组件、行为变更、API/数据库设计）开始前必须使用。通过需求分诊、并行探索、逐题澄清、对抗验证与 2-3 方案对比，把想法打磨成完整设计，落盘 spec 并交接 writing-plans。当用户已明确要交付某功能或变更（功能开发、API/数据库设计、行为变更、技术选型落地）时触发；不适用于纯问答、跑测试、无设计空间的小 bug 修复/小调整（用 quick-fix）；想法尚未定型、还没决定要不要做时先用 exploring。

- Skill: `flamemida/requirement-analysis-7` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add flamemida/requirement-analysis-7`
- Raw SKILL.md: https://api.skillmd.com/api/skills/flamemida/requirement-analysis-7/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: flamemida (https://skillmd.com/u/flamemida)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/flamemida/requirement-analysis-7

---


> 语言协议：以对话语言输出——用户显式指定（含平台 `language` 设置）优先，其次跟随用户近期消息语言；均无法判定时默认英语。落盘产物以创建时对话语言为准，增量修改保持产物既有语言。本 skill 中的固定话术是语义模板，用对话语言表达其意，不逐字照搬。

> **插件根**：`${CLAUDE_PLUGIN_ROOT}`——本 skill 正文与其 references 中的插件根命令以此为准；若上式仍为变量字面量（平台未替换），按 requirement-analysis 的 references/exploration-patterns.md「插件根解析」序列推导。

# 需求设计工作流

通过自然的协作对话，把想法转化为经过验证的完整设计与 spec。

先理解项目现状，再逐题澄清打磨想法；理解到位后做对抗验证、给出多方案对比；用户批准设计后落盘 spec，最终交接 writing-plans 生成实施计划。

<HARD-GATE>
在设计展示给用户并获得批准之前，不得调用任何实施类 skill、不得编写任何代码、不得搭建任何脚手架、不得采取任何实施动作。此门槛适用于所有项目，无论看起来多简单。
</HARD-GATE>

## 反模式："这需求太简单，不需要设计"

所有需求都要走完本流程。加一个字段、改一处文案、一个单函数工具——都一样。"简单"需求恰恰是未经检验的假设造成返工最多的地方。设计可以很短（light 档几句话即可），但**必须展示并获得批准**。

## Checklist

必须为以下每一项创建任务（Claude Code 用 `TaskCreate`，Codex 用 `update_plan`），按序完成；被跳过的项标记完成并注明原因：

1. **需求理解与分诊** — 理解意图，判定档位，标记外部探索/视觉候选
2. **并行探索** — 内部代码 + 外部资源同一波次 fan-out，深度按档位
3. **澄清问题** — 一次一个问题，不限轮数；视觉问题 JIT 提议 visual-preview
4. **对抗验证 + 提出 2-3 方案** — sequential-thinking 校验信息后给方案与推荐，用户选定
5. **展示完整设计** — 整篇展示不分章节，获得用户批准
6. **写 spec 并提交** — 落盘 `.spec-dev/YYYY-MM-DD-NN-<feature>/spec/<feature>-design.md` 并 git commit
7. **Spec self-review + 对抗验证** — inline 自检 + 审查子代理；有修改则请用户再 review
8. **交接 writing-plans** — 唯一终态；经用户确认后调用 writing-plans 生成实施计划

## 流程图

```dot
digraph requirement_analysis {
    "1 需求理解与分诊" [shape=box];
    "2 并行探索（内部+外部）" [shape=box];
    "3 澄清问题（逐题）" [shape=box];
    "4 对抗验证 + 2-3 方案" [shape=box];
    "用户选定方案?" [shape=diamond];
    "5 展示完整设计" [shape=box];
    "用户批准设计?" [shape=diamond];
    "6 写 spec 并提交" [shape=box];
    "7 self-review + 对抗验证" [shape=box];
    "用户 review 通过?" [shape=diamond];
    "8 调用 writing-plans" [shape=doublecircle];

    "1 需求理解与分诊" -> "2 并行探索（内部+外部）";
    "2 并行探索（内部+外部）" -> "3 澄清问题（逐题）";
    "3 澄清问题（逐题）" -> "4 对抗验证 + 2-3 方案";
    "4 对抗验证 + 2-3 方案" -> "用户选定方案?";
    "用户选定方案?" -> "4 对抗验证 + 2-3 方案" [label="要求调整"];
    "用户选定方案?" -> "5 展示完整设计" [label="选定"];
    "5 展示完整设计" -> "用户批准设计?";
    "用户批准设计?" -> "5 展示完整设计" [label="否，修订"];
    "用户批准设计?" -> "6 写 spec 并提交" [label="是"];
    "6 写 spec 并提交" -> "7 self-review + 对抗验证";
    "7 self-review + 对抗验证" -> "用户 review 通过?";
    "用户 review 通过?" -> "6 写 spec 并提交" [label="要求修改"];
    "用户 review 通过?" -> "8 调用 writing-plans" [label="通过"];
}
```

**终态是调用 writing-plans。** 不得调用 executing-plans、acceptance-qa 或任何其他实施类 skill——本 skill 之后唯一可调用的 skill 是 writing-plans。

## 执行档位

档位在阶段 1 判定，向用户声明并允许覆盖；它只调节探索规模与 spec 篇幅，**不豁免任何 Checklist 项与 HARD-GATE**。

```
light    — 单文件/单模块、无新依赖、无方案分歧（如加字段、改文案）
           探索：主线程直查或 1 个子代理；方案可收敛为 1 个（说明为何无分歧）；spec 几句话到半页
standard — 默认档。跨 2-3 模块或有方案取舍
           探索：按架构层次或功能模块 3-5 个子代理；完整 2-3 方案对比
deep     — 跨层架构变更、新技术栈、用户使用"彻底/全面/审计"等措辞
           探索：multi-modal sweep，按模态数派发、不设上限；方案对比含更完整的风险分析
```

**判定依据**：涉及文件数与模块数（阶段 1 初判、阶段 2 修正）、是否引入新依赖、是否存在多解取舍、用户措辞强度。声明格式：「本需求判定为 {档位}（理由），如需更彻底/更轻量请告知」。

## 执行环境兼容性

本 skill 同时兼容 Claude Code 和 Codex。工具映射（澄清 AskUserQuestion↔对话消息、进度 TaskCreate↔update_plan、并行 Agent↔spawn_agent+wait_agent、规范文件 CLAUDE.md↔AGENTS.md 优先序、搜索 anysearch 降级链）以 [codex-compat.md](references/codex-compat.md) 的工具映射总表为准——全 skill 共用的单一定义点，此处不复述整表；Codex 环境的完整规则同见该文件。

---

## 阶段 1: 需求理解与分诊

**目标**：理解意图，给流程定参。

- 理解核心功能、业务实体、约束与成功标准；描述模糊或多模块时用 sequential-thinking skill（插件内嵌）分解
- **上下文复用**：提出路由建议前按 [context-reuse.md](references/context-reuse.md) 双查相关实现与历史否决，并读取适用共享术语；已有有效决定直接消费。
- **意图承诺检查**：用户仍在"要不要做"的犹豫期（探索性措辞、无交付承诺）→ 建议切换 exploring skill，不硬拉八阶段；存在相关的 `.spec-dev/explorations/` 探索笔记时作为本阶段输入，已探索过的部分阶段 2 不重做
- **小修检查**：需求其实是"已决定要修、无设计空间"的小 bug 修复/小调整（单点 bug、单常量、单文案，无方案取舍、不跨模块、不引入新依赖）→ 建议切换 quick-fix skill，不硬拉八阶段；这是意图承诺检查的对偶——那边挡"还没决定要不要做"，这边挡"决定了但不值得走完整设计"。建议式（不自动切换），由用户裁决。大小/设计空间拿不准的已承诺开发请求，同样建议先走 quick-fix——其步骤 2.5 基于根因证据的升级门（含上下文交接）比入口猜测更准，升级便宜、降级浪费
- **任务类型检查（报告通道权威定义）**：按用户最终交付目标判断。已明确交付功能、组件或 API 时，本轮只做澄清、方案设计或 spec 仍属于开发流程，保留方案与设计的用户裁决门，不能因本轮暂不写代码而转为报告通道；开发流程中的研究子题可以返回研究摘要，但不改变主流程。只有最终交付物本身是调研报告、方案对比、日志分析等非开发成果，且未要求功能落地时 → 建议走报告通道，不硬拉八阶段：不建特性目录、不写 spec/plan；需要时按 clarifying 纪律澄清关注点；主线程产出结论后**问一次**「落盘为 `.spec-dev/reports/YYYY-MM-DD-NN-<topic>.md` 吗」（结构从轻：问题、结论、依据来源；目录随首个报告创建；同一 NN 序列全 `.spec-dev/` 日期前缀产物共用），用户婉拒则只留对话、零落盘。建议式，由用户裁决。结论要落地成代码时回归正常分诊——报告通道不是实施后门
- **范围分解检查**：需求的意图必须能用一句话说清——说不清就该拆。出现过大信号（范围读起来像不相关功能清单、审查一份 spec 要一下午、两人同时做会撞车、一半任务可独立交付）或描述了多个独立子系统（如"做一个带聊天、文件存储、计费、分析的平台"）时立即指出，先帮用户分解为子项目（各自独立的 spec → plan → 实施周期）——不要在一个需要分解的项目上浪费澄清轮次。分解说完不算完，两个配套动作：
  - **分解登记（roadmap）**：拆分方案（子项目清单、一句话范围、依赖顺序）经用户确认后，按 [roadmap-template.md](assets/roadmap-template.md) 落盘 `.spec-dev/roadmaps/YYYY-MM-DD-NN-<project>.md`（同一 NN 序列全 `.spec-dev/` 日期前缀产物共用）并 git commit（登记时同步填写「原始需求」节——用户原话全文，与每子项目「上下文胶囊」——关键裁决/探索指针/已扫范围），然后只对第一个（或用户指定的）子项目走本流程。roadmap 是分解决策唯一的持久化位置——不落盘，其余子项目就只活在本次对话里，会话一结束静默蒸发
  - **续接检查**：需求命中某 active roadmap 的既有子项目时（用户点名"继续 <项目>"，或 `.spec-dev/roadmaps/` 下某 active roadmap 的 pending 子项目与本需求对得上）→ 载入该 roadmap 的目标/分解边界/备注，**并读取该子项目上下文胶囊指向的前置产物**（前置子项目 spec 的「背景与目标」与验收报告结论、探索指针文件），以此为阶段 1-2 输入直接走本流程、不重新分解、**不要求用户重新提供原始需求**；阶段 2 探索对胶囊「已扫范围」登记过的模态不重扫、只补缺口；依赖的前置子项目未交付时先向用户指出。roadmap 目录不存在或无命中 → 本条零动作，正常走流程
- 判定档位并声明（见"执行档位"）
- 打标记，供后续阶段消费：
  - **需要外部探索？**——涉及新第三方库/框架、需要行业最新实践、内部示例不足，任一满足即标记
  - **视觉候选？**——需求涉及 UI 布局、页面结构、视觉风格等"看比说清楚"的题材时标记；此标记只影响阶段 3 的 JIT 提议时机，**不在此时提议**
  - **契约姿态判定**：需求措辞含破坏性重构信号（"重构""推翻""可破坏""不留兼容"等）且预计触及既有 active spec/ADR 时，**在本阶段（先于阶段 2 派发）以一道澄清题当场确认**这些旧契约是**硬约束**（默认）还是**仅现状输入**——姿态结论决定探索派发词，不能等到阶段 3。确认降格后：阶段 2 主波次与回补探索的派发词均须携带该姿态结论，子代理不得把降格契约当设计约束报告（仅作现状与迁移分析输入）；阶段 4 方案对比不因"违反旧 spec 契约"排除选项

## 阶段 2: 并行探索

**目标**：一个波次拿齐内部代码事实与外部最佳实践。

**首要任务**：查找并阅读项目规范文件（优先级按环境映射表）。

**编排**：内部与外部探索相互独立，**必须在单条消息中一次性发起全部子代理**——分批发起会退化为串行等待。子代理数量不设上限，按档位与需求结构决定：

- **light**：主线程直查（Glob/Grep/Read 或 codegraph），或 1 个 `code-explorer`
- **standard**：按架构层次或功能模块拆 3-5 个 `code-explorer`；阶段 1 标记了外部探索时，同波次加 1-2 个 `external-resource-explorer`
- **deep**：multi-modal sweep——每个模态一个 `code-explorer` 彼此盲扫，模态数由项目形态决定、不设上限；外部按主题拆多个 `external-resource-explorer` 同波次发起

外部研究的来源纪律先实际读取 [external-resource-explorer.md](../../agents/external-resource-explorer.md)，等待定义回执后才发起材料读取；不能把两者放在同一批并行工具调用中。主线程直查或接管也适用。

开始外部研究（包括本地保存的第三方依赖材料，以及主线程直接接管）前，先实际读取 [exploration-patterns.md](references/exploration-patterns.md) 的外部研究分类、定义加载与派发要求，按该单点执行；非自动加载环境不能省略定义读取。

外部探索工具优先级：AnySearch（通用/垂直/批量，插件内嵌）优先 → `WebSearch` / `WebFetch` 兜底；**派发外部探索子代理时须在派发词中主动重申此优先级**（不依赖 agent 定义文件生效，Codex 端尤其如此）；降级链与模态定义、契约校验、失败隔离规则见 [exploration-patterns.md](references/exploration-patterns.md)。

**每个子代理必须给定**：有界主题、来源线索、可判定的完成条件、显式排除项、期望输出及适用的工具优先级/文档时效提醒；按 [exploration-patterns.md](references/exploration-patterns.md)「完成条件与排除项」和派发要求校准，不复制定义。失败先缩小范围重试 1 次，再失败主线程接管（定义见 exploration-patterns「派发要求与失败隔离」）。

## 阶段 3: 澄清问题

**目标**：解决所有模糊、歧义与多解取舍。

**提问前取得澄清权威**：先实际读取 [clarifying 的核心纪律](../clarifying/SKILL.md)，再按被引用模式组织问题；已取得当前定义时复用，不另起独立澄清流程。

**提问纪律遵循 clarifying skill（被引用模式，纪律定义以 clarifying 为准）**：用单题澄清与可见清单处理当前范围，不在此复述核心纪律枚举。澄清后直接进入阶段 4，不触发独立共识摘要或三出口；Codex 逐题规则见 clarifying，三道门呈现见 [codex-compat.md](references/codex-compat.md)。

- 优先覆盖：目的、约束、成功标准；阶段 1-2 暴露的歧义、约束冲突、隐含假设、边缘场景
- 术语挑战裁决出的规范术语全程沿用；共享术语及冲突处理遵循 [context-reuse.md](references/context-reuse.md)，特性局部术语留在 spec，完整设计批准后再按该约定保存词汇表。

**可视化预览（JIT 提议）**：不要在开场提议。当某个问题**用看的比用说的更清楚**时（真实的 mockup/布局/图示问题，而不只是"话题涉及 UI"），首次出现的那一刻单独发一条消息提议使用 visual-preview skill——该消息只含提议、不夹带其他问题。用户接受则按 visual-preview skill 执行；拒绝则继续纯文字，不再重复提议。逐题判断浏览器 vs 终端：内容本身是视觉的（线框、布局对比、架构图）用浏览器，内容是文字的（需求、取舍、概念选择）留在终端。

**回补探索**：澄清或方案期发现新库/新领域，允许回补一轮外部探索（同样单响应发起），回补后继续当前阶段。

## 需求完备性与约束归属

standard 档在既有有界探索主题内核对相邻测试、公共行为入口与 fixture/mock 惯例，或单独分配这个主题；细则见 exploration-patterns，不将 standard 升成 deep 多模态盲扫。

在方案定型前枚举实际参与者及其适用行为/错误路径，包括真实的后台或系统触发者；独立约束分别映射负责边界和验证位置。判据沿 writing-plans/references/design-principles 的迁移过渡与约束归属单点，spec 模板保存参与者及有依据的拒绝解读。没有真实 actor/歧义时不为凑数发明，也不重开获批 seam。参与者盘点只记录有来源的能力与边界，不把后台身份推成已有凭据或授权策略。下游先读采用理解及裁决来源；已有完整记录且需求无冲突就直接消费，不因存在拒绝记录而假定 spec 写错、缺项或必须重新批准。确实缺记录或存在冲突时才按原修订流程处理。

## 阶段 4: 对抗验证 + 提出 2-3 方案

**目标**：先证伪自己的信息，再给出可比较的方案。

**零子代理**：本阶段全部在主线程完成，用 sequential-thinking skill（插件内嵌，bun/tsx → scripts/think.mjs Node 端口自动降级）结构化推进；该 skill 及其运行时均不可用时降级为在回复中显式分点推演并注明工具降级原因，不得因工具缺失跳过分析。

**第一步——信息对抗验证**。对阶段 1-3 收集的每条承重结论（将直接决定方案取舍的事实）逐条质询：

- 来源可靠吗？（外部结论：官方文档还是二手博客？版本时效？）
- 与代码库事实冲突吗？（外部最佳实践与项目现有模式矛盾时，回读代码裁决）
- 是未验证的假设吗？（是→标记，能在代码中验证的立即验证，只能由用户裁决的回到阶段 3 补问）

冲突未消解前不进入方案设计。

**第二步——提出 2-3 个方案**。基于验证后的信息给出方案对比：

- 每个方案：核心思路、与现有模式的契合度、改动半径、风险、成本、设计原则符合度（对照 writing-plans/references/design-principles.md 八条及「模块判据」——尤其"是否引入投机抽象""是否留兼容垫片""是否权宜之计"三问）
- **推荐方案放首位并说明理由**，以对话方式呈现，不堆砌表格
- YAGNI：从所有方案中删掉没人要求的功能
- light 档确无分歧时可收敛为 1 个方案，但必须说明"为何无分歧"
- 用户选定方案后才进入阶段 5；用户提出调整则修订方案重新呈现

## 阶段 5: 展示完整设计

**目标**：把选定方案展开为完整设计，整篇获得批准。

- **整篇展示、不分章节逐节确认**——一次性给出全文，用户整体反馈
- 覆盖：架构与组件划分、数据流、关键接口/数据结构、错误处理、测试策略、风险与边缘情况
- **测试落点声明**：在本次完整设计中一并展示公共接口与签名/协议、覆盖 Scenario、允许替换的外部依赖（无则写无）和来源。按 test-driven-development 的落点规则优先复用、选择仍可稳定观察行为的较高层接口、减少新接口；获批后写入 spec 测试策略，不增加独立 seam 批准门。
- 篇幅与复杂度匹配：light 档几句话，复杂设计每节最多两三百词——设计文档不是越长越好
- **面向隔离与清晰设计**：拆成职责单一、接口明确、可独立理解与测试的单元；每个单元能回答"做什么、怎么用、依赖什么"；不读内部实现就能理解一个单元、改内部实现不破坏消费者——做不到就重划边界；整体设计对照 design-principles.md 八条自检
- **在既有代码库中**：跟随现有模式；当前工作触及的既有问题（文件过大、边界混乱）可纳入设计做定向改进，但不做无关重构
- 用户批准前不进入阶段 6；有修改意见则修订后重新整篇展示

## 阶段 6: 写 spec 并提交

- 为本需求创建特性目录 `.spec-dev/YYYY-MM-DD-NN-<feature>/`（所有 spec-dev 产物统一收纳在项目根目录 `.spec-dev/` 下；NN 为当日两位序号——扫描 `.spec-dev/` 下当日已有的日期前缀产物（特性目录，及 `reports/`、`roadmaps/` 下的文件名）取最大加一、01 起步，**落盘前重扫一次防并发撞号**：发现同号已被占则顺延并同步修正自引路径；feature 取需求主题的短语义名，跟随项目语言；存量旧命名 `YYYY-MM-DD-<feature>` 目录不改名（grandfather）；同一 NN 序列由全部 `.spec-dev/` 日期前缀产物共用），将批准的设计写入其 `spec/<feature>-design.md`（用户对 spec 位置的偏好优先于此默认值）
- 按 [context-reuse.md](references/context-reuse.md) 将本次获批共享术语与 spec 同次保存和范围提交；无共享术语不创建空 glossary，特性局部术语只留 spec。
- spec 与后续 writing-plans 的计划（同目录 `plan/` 分文件形态：index.md + tasks/ + progress.yaml）共用这一个特性目录——一个需求的全部产物收纳在一处
- **决策分流（ADR）**：检查"已确认的关键决策"中是否有同时满足三判据的决策——**难以逆转**（事后改主意成本高）、**缺上下文会费解**（未来读者会问"当初为什么这么做"）、**真实取舍**（存在真正的备选且因具体理由选定其一）——满足者每条沉淀为仓库级 `.spec-dev/adr/NNNN-<slug>.md`（全项目共用一个目录、统一编号：扫描现有最高编号递增，目录不存在时随首个 ADR 创建；**落盘前重扫一次目录防撞号**——并行会话可能已用掉同号，发现同号文件已存在则顺延取下一号并同步修正正文与链接中的自引编号；正文 1-3 句写清背景、决定与理由即可，值得记住的被否方案附一行），spec 决策节保留一行摘要并链接过去；三判据缺一即不建 ADR——ADR 泛滥和没有 ADR 一样没用。**ADR 状态纪律**：每条 ADR 标题下带状态行，封闭三态——`**Status**: Accepted (YYYY-MM-DD)` / `**Status**: Deprecated (YYYY-MM-DD) — <一句原因，强制>` / `**Status**: Superseded by [ADR-NNNN](NNNN-<slug>.md) (YYYY-MM-DD)`（同目录文件名相对链接，编号强制；缺状态行的历史 ADR 视同 Accepted）。判据一句话：有替代决策用 Superseded，无替代者且决策语境消失用 Deprecated。Accepted 后正文不可变（仅 status 行、错别字、坏链可改）；**不做部分推翻**——推翻既有 ADR 的任何部分时，新 ADR 完整重述仍有效的结论并整体取代，标题下声明 `**Supersedes**: ADR-NNNN` 行，且在本阶段同一提交把旧 ADR 状态行回写为 Superseded by（ADR 取代随裁决即时生效，不等实施交付）
- **取代分流（supersede triage）**：对阶段 2 探索命中的每份行为相交 active spec 做三分类判定并写入 spec——**完全取代**（新 spec 整体替换旧特性）与**部分取代**（替换旧 spec 的部分 Requirement）登记进 frontmatter `supersedes`（仓库根相对路径）与正文「取代与共存」节（部分取代必须列出被取代的具体 Requirement 标题清单，每条附一句取代理由）；**分面共存**（同文件不同行为切面、无冲突）不登记 supersedes，记一行判定理由并各自声明 covers。节模板与标注形制见 [spec-template.md](assets/spec-template.md)。用户要求删除整个特性且无新行为承接时，产出仅含 REMOVED Requirements 的轻量 spec 作为后继（记录删除理由，交付时按完全取代回写旧 spec）。spec 的取代回写随交付生效（executing-plans 最终任务），与 ADR 的即时回写构成双轨
- 结构参考 [spec-template.md](assets/spec-template.md)，按需增删节；**行为需求必须用 Requirement + Scenario 结构表达**（`### Requirement:` 一条一个 SHALL 且可观察，`#### Scenario:` 用 GIVEN/WHEN/THEN——它们是后续 TDD 测试与验收的直接锚点）；修改既有功能时行为部分改用差量三节（ADDED/MODIFIED/REMOVED Requirements，见模板）
- **漂移守卫锚点（必填）**：落盘时保留模板顶部的 `spec_dev` frontmatter，填写 `feature` 与 `covers`（本特性拥有的代码路径 glob；纯文档特性留空数组 `[]`）——此阶段 `status` 保持 `draft`。该 frontmatter 是 pre-commit / CI 漂移守卫的锚点，缺失或永停 draft 意味着该特性代码不受"改了代码却没同步 spec"的拦截保护
- 新建/本次更新胶囊指针时使用一句用途/适用边界摘要 + 精确来源路径；摘要不能替代续接读取原文，旧胶囊没有摘要仍正常读，不全库回填。
- **roadmap 回填（仅当本特性是某 active roadmap 的子项目）**：把特性目录路径回填至 roadmap 对应子项目行、状态置 `in-progress`；不属于任何 roadmap 则无此步
- git commit 该 spec、本次按获批设计更新的 glossary、新增 ADR 与 roadmap 回填（仅本次实际修改的这些文件；非 git 仓库则跳过并向用户说明）

## 阶段 7: Spec self-review + 对抗验证

**第一步——inline 自检**（自己以新鲜眼光重读，发现即改，无需复审）：

1. **占位符扫描**：有无 "TBD"、"TODO"、未写完的节、含糊的需求？
2. **内部一致性**：各节是否互相矛盾？架构是否与功能描述匹配？术语是否全篇沿用术语表的规范名、未混入 Avoid 别名？
3. **范围检查**：整份 spec 的意图能否一句话说清？是否聚焦到单个实施计划能承载？出现过大信号（不相关功能清单、一半任务可独立交付）则回到分解。**警惕伪聚焦**：spec 正文自行写了"第一阶段/Phase 1、第二阶段/Phase 2……"或"先做 X 再做 Y"这类阶段化结构——这是未登记的分解伪装成一份聚焦 spec（读起来聚焦，实则把多个实施周期塞进一份 spec，下游 writing-plans 只会为第一阶段写 plan、其余阶段无声蒸发）。命中即回到阶段 1 范围分解检查：把阶段拆成 roadmap 子项目，本 spec 只保留第一阶段的内容
4. **歧义检查**：有无可以两种方式解读的需求？有则选定一种写明
5. **Requirement 质量**：每条 Requirement 是否一个 SHALL 且可观察？每条是否至少有一个真正检验它的 Scenario（不是复述）？最怕坏掉的场景有没有命名的 Scenario？差量三节（如使用）分类是否与既有行为对得上？

**第二步——对抗验证**：派 1 个临时子代理（Claude Code 用 general-purpose，Codex 用 `spawn_agent`），提示词按 [spec-reviewer-prompt.md](references/spec-reviewer-prompt.md) 模板构造，对 spec 做独立审查（完整性/一致性/清晰度/范围/YAGNI）。审查回报的问题逐条处置：成立则修 spec，不成立则记录理由。

**第三步——用户 review 门**：

先展示最新版 spec 链接、简短变更摘要和 2–3 个针对实际参与者、约束或边界的陈述式检查点，再使用下方一次整体确认。检查点只陈述来源已支持的事实与影响，不附“请确认”或问题；约束表示必须保护的边界，不能改写成违反约束的情况“不可能发生”。若确有未决决策，转为一次一题澄清，先处理该决策。

保存与提交状态只按本次实际证据陈述：Read 只证明读到了文件；取得真实提交回执后才能说“已提交”。只读审阅或接手现有稿件时说明“待审稿”，不从话术模板推定执行过写入或提交。

> 「待审 spec：`<路径>`。<按证据说明保存/提交状态及变更摘要>
> <2–3 个陈述式检查点>
> 是否确认这版 spec，并开始编写实施计划？」

仅认可内容不等于授权实施；保持本阶段和下一阶段的授权边界，不把审阅认可报告成执行授权。

等待用户回复。**若第一/二步曾修改 spec，必须让用户重新 review 修改后的版本**；用户要求修改则改完重跑本阶段。用户确认后才进入阶段 8。

## 阶段 8: 交接 writing-plans

- **前置确认**：须持有用户对「开始编写实施计划」的明确同意——阶段 7 的确认话术已包含此询问；用户仅认可 spec、未表态是否继续时，先问「现在开始编写实施计划吗？」，同意后才交接
- **激活漂移守卫**：交接前把 spec frontmatter 的 `status: draft` 翻为 `active` 并 commit（仅 `active` 参与漂移拦截——不翻转则守卫对本特性静默失效）
- **打取代预告（仅当 spec 的 `supersedes` 非空）**：翻 active 的同一提交内，向每份被指向的旧 spec H1 标题下写入 Superseded-pending 标注（形制见 spec-template「取代标注形制」节；部分取代写明将被取代的 Requirement 标题）——窗口期的双 active 状态由此对全部消费方显式可判定；后续该计划若被废弃，由 executing-plans 意图级偏差收尾回收此标注
- 调用 writing-plans skill，基于已批准的 spec 生成实施计划
- **不得调用任何其他 skill**——writing-plans 是本流程唯一的下一步；实施纪律（worktree 隔离、TDD、审查编排）由 writing-plans → executing-plans 链路承接

---

## Key Principles

- **一次一个问题**——不要用一串问题淹没用户
- **选择题优先**——能给具体选项就不问开放式问题
- **YAGNI 无情裁剪**——从所有设计里删掉不必要的功能
- **先证伪再方案**——承重信息未经对抗验证不得进入方案设计
- **多方案对比**——定稿前必出 2-3 个方案（light 档例外需说明理由）
- **增量验证**——方案选定、设计批准、spec review 三道门逐一通过
- **随时回退**——发现理解有误就回到对应阶段澄清，不带着错误假设前进
- **原则先于偏好**——方案对比与设计定稿以 design-principles.md 为共同裁决维度

## Red Flags

出现以下想法时，停下来重新对照 Checklist：

- "这太简单了，直接写代码吧" → HARD-GATE 适用于一切需求
- "一次多问几个问题效率高" → 一次一个
- "外部搜到的做法直接用" → 先对抗验证，与代码库事实对照
- "方案很明显，不用对比" → 除 light 档且说明理由外，必出 2-3 方案
- "设计批准了，spec 就不用再让用户看了" → self-review 后有修改必须让用户再 review
- "顺手把代码也写了" → 终态只有 writing-plans，实施是后续 skill 的职责
- "先开工，档位/任务清单回头补" → Checklist 每项建任务，跳过要注明原因
- "项目太大，先做第一部分，剩下的以后再说" → 分解必须落盘 roadmap："以后"没有登记就等于不存在
- "spec 里分个阶段（Phase 1/2/3）就能装下大目标" → 阶段化 spec 是未登记的分解，拆成 roadmap 子项目、spec 只留第一个