---
name: requirement-analysis
description: Use when 用户、产品经理或 PMS 需要判断一个需求是否清楚、是否值得接纳、接纳成本是否可信。
---

# 需求分析

> 前置：使用本 Skill 前，先按 `using-nucleus` 完成 Nucleus 入口识别（Claude Code 会话由插件 SessionStart hook 自动注入该纪律）。

## 核心原则

关键澄清没有回答前，只能澄清，不能估算，不能建议接纳。

需求分析只回答“需求是否清楚、是否值得接纳、接纳成本是否可信”。它可以产出待评审 PRD、满足度 / 工作量评估、需求尺寸和接纳建议，但不做需求设计、正式特性拆解、开发计划、测试计划、技术方案、源码修改或最终接纳裁决。

<HARD-GATE>
如果存在会影响接纳判断、工作量估算、产品边界或外部依赖的关键问题未回答：
- 不得生成完整 PRD
- 不得给出人日估算
- 不得给出接纳、条件接纳、暂缓或拒绝建议
- 不得生成需求评估
- 只能输出当前理解、证据、缺口、一个最关键澄清问题和推荐答案

待评审 PRD 和 evaluation 草稿提交人工或 PMS 评审前，必须先按 `requirement-analysis-review` 的 `subagentPreReview` 调度独立 reviewer 子代理；未取得“材料可提交人工审查”预审结论时，不得请求人工评审通过。
</HARD-GATE>

## 什么时候使用

使用本 Skill：

- 判断一个需求是否清楚、是否值得接纳、接纳成本是否可信。
- 生成供产品经理或 PMS 评审的 `docs/requirement/**/prd.md` 和 `evaluation.md` 草稿。
- 在明确授权下把澄清、满足度、gap、满足路径、轻量实现口径、工作量、需求尺寸和接纳建议收口为需求分析证据。

不要使用本 Skill：

- 已接纳需求后的方案设计、产品子需求拆解或正式特性拆解。
- 特性设计、开发准备、测试生成、缺陷修复或交付收口。
- 普通 setup、普通开发或未授权场景写 `docs/requirement/**`。

## Checklist

启动本 Skill 后，必须先为每一项创建宿主 todo/task，并按顺序逐项推进、逐项更新状态；Codex 使用计划 / 任务工具，Claude Code 使用 TodoWrite 或等价宿主 todo。`.nucleus/runs/**`、`summary.md`、`result.json`、候选文件和 review report 只能记录事实，不能替代宿主任务、人工回答、人工评审或 PMS 接纳事实。

1. **读取需求输入和 context**
   完成证据：`input-evidence.json` 或等价输入证据。
   STOP：未读需求输入、`.nucleus/context/<workflowRunId>.json` 或 standalone problem statement 时，不得提问、估算或生成需求文档。

2. **读取产品上下文**
   完成证据：产品定位、`docs/features/**`、`docs/architecture/**`、安全实现线索或缺失证据。
   STOP：未读产品与特性上下文时，不得把用户原话直接整理成 PRD。

3. **复述当前理解**
   完成证据：`understanding.md`，说明需求想解决什么、归属哪个产品能力、已有满足度初判和证据缺口。
   STOP：复述中出现技术方案、接口设计、数据表、权限码或开发计划时，必须退回需求语言。

4. **识别并推动关键澄清**
   完成证据：`clarification-questions.json`、`clarification-candidate.md`、人工回答记录。
   STOP：一次只能推动一个最影响接纳和成本的问题；没有明确回答前，不得生成 PRD、工作量或接纳建议。细节读取 `references/clarification-method.md`。

5. **调用 `requirement-evaluation` 做满足度和工作量评估**
   完成证据：`analysis-package.json`、`workload-estimate.json`、`acceptance-recommendation.json` 或等价结构化评估证据。
   STOP：必须显式加载并执行 `requirement-evaluation`；形成满足度 gap、满足路径、轻量实现口径和工作量评估前，不得估人日、不得给接纳建议、不得写需求评估正文；不得直接从澄清答案跳到人日估算。

6. **调用 `requirement-sizing` 识别需求尺寸**
   完成证据：`requirement-sizing.json`，以及待写入 `evaluation.md` 的“需求尺寸”中文结论。
   STOP：需求尺寸必须在满足度、gap、满足路径、轻量实现口径和工作量评估完成后识别；不得在需求澄清开始阶段、单凭原始需求标题或早期澄清问题猜测尺寸。

7. **直接写 docs 下待评审 PRD 和包含需求尺寸的需求评估**
   完成证据：状态为 `draft` / `pending_review` 的 `docs/requirement/**/prd.md` 和 `evaluation.md`。
   STOP：`.ac` 只保存过程证据和结构化评估，不得先把完整 PRD / evaluation 正文写成 `.ac` candidate 再复制到 docs；草稿写入细节读取 `references/draft-doc-write-policy.md`。

8. **调用 `multi-review` 做需求分析质量评审**
   完成证据：针对 docs 草稿和结构化评估证据的需求分析领域 review report，且阻塞项已整改或标记无法验证。
   STOP：review report 只能记录发现、风险和复核；不得写“已接纳”“PMS 已批准”“人工评审通过”或“可以进入需求设计”。

9. **预审通过后等待人工或 PMS 评审**
   完成证据：人工 / PMS 审批事实引用当前 run 的 `requirement-analysis-review`。
   STOP：先完成 `requirement-analysis-review.subagentPreReview` 并确认材料可提交人工审查，才可等待人工或 PMS 评审；`analysis-package.json`、review report、`summary.md`、`result.json` 都不能制造审批事实；没有事实时 `review-gate.json` 只能是 pending 或 blocked。

10. **确认终稿**
    完成证据：`finalize-gate.json`，已有草稿被更新为 `final` / `accepted`。
    STOP：`finalize` 只能更新已有待评审草稿；不得从 `.ac` 候选包首次创建正式需求文档；终稿细节读取 `references/finalize-policy.md`。

## 选项式澄清协议

澄清阶段必须按真实对话呈现，不能用 JSON 状态、推荐答案、候选文件、`summary.md` 或 `result.json` 代替人的回答。

每轮澄清必须：

1. 先说明当前理解和已读证据。
2. 只问一个最影响接纳判断和工作量估算的问题。
3. 给出 2-3 个选项，使用 A/B/C 标识。
4. 标明推荐选项，并说明推荐理由。
5. 写清每个选项对首版范围、数据来源、验收标准、外部依赖、工作量可信度和接纳判断的影响。
6. 点明“选错代价”：选了不合适的选项会对首版范围、工作量可信度或接纳判断造成什么后果。
7. 等待明确回复。用户可以选择 A/B/C，也可以补充自由回答。

澄清提问的呈现格式遵循 `_shared/references/interaction-format.md` 的补齐型，方案 / 范围类多选遵循选择型；追问纪律遵循 `_shared/references/question-discipline.md`。

推荐选项只是默认建议，不是授权、人工回答或 PMS 审批事实。记录回答后必须重新执行剩余关键缺口审计；如果仍有高影响缺口，继续只问下一个最关键问题。审计维度和提问边界见 `references/clarification-method.md`。

回答后先判定具体度是否达标；如果回答仍停留在“提升效率”“方便管理”“支持查看”“看情况”“数据准确”“首版简单做”等泛泛表述，必须继续追问同一维度，不能进入 `requirement-evaluation`、PRD、工作量估算或接纳建议。

每轮追问必须服务于边界、设计输入或测试输入。澄清阶段可以使用 `requirement-sizing` 的业务范围、方案未知数、依赖面、数据影响、权限 / 稳定性和评审风险六类风险信号决定追问深度，但澄清阶段不得提前输出需求尺寸结论。疑似低风险文案 / 字段类需求只追到首版边界和验收事实；疑似高风险数据、权限、外部依赖或跨系统需求，必须追问数据来源、权限入口、依赖失败降级、评审前提和替代接纳路径。

## 澄清提问输出纪律

面向用户的澄清提问只服务于当前问题，不做执行审计汇报。默认只输出：当前理解一句话、一个问题、A/B/C 选项、推荐选项和选择影响。

不得在澄清提问轮展示 `.ac` 证据路径、JSON 文件名、状态码、校验结果、PMS 状态补充说明或“我没有写哪些文件”的自证说明。这些事实写入过程证据和结果包，只有用户要求查看证据、排查流程或验收产物时才展示。

## docs 草稿写入硬规则

`docs/requirement/**` 是受保护需求事实源。只有需求 workflow 在明确 context、writePolicy、review gate 和 result 证据下，才能创建或更新待评审草稿；普通开发、setup 和未授权 workflow 不得写。

如果本轮目标包含“生成 PRD / 需求评估供用户或 PMS 评审”，且关键澄清、`requirement-evaluation`、`requirement-sizing` 已完成，agent 必须直接写 `docs/requirement/<requirementSlug>/prd.md` 和 `docs/requirement/<requirementSlug>/evaluation.md`。停在 `.ac` 过程证据或 `.ac` candidate 正文就是未完成。

写 docs 草稿不代表需求已接纳。草稿写入后必须先完成 `requirement-analysis-review.subagentPreReview` 并确认材料可提交人工审查，`review-gate.json` 才能等待人工评审；没有人工评审事实时不得写 passed。上下文调整、阻塞条件和写入前置项见 `references/draft-doc-write-policy.md`。

## finalize STOP

`finalize` 只能确认已有待评审草稿，不能从候选包直接首次创建 `docs/requirement/**`。

只有同时满足这些条件，才能运行 `finalize`：

- `docs/requirement/<requirementSlug>/prd.md` 和 `evaluation.md` 已存在。
- 两个文件状态都是待评审草稿。
- review gate 已通过。
- 人工或 PMS 审批事实齐全。
- 上下文明确允许正式需求写入。

如果草稿不存在、审批事实不足或上下文不允许正式写入，必须阻塞并记录原因。不得为了通过流程，从 `.ac` 候选包复制一份当成终稿。

## 产物与证据边界

澄清阶段只写 `.nucleus/runs/<workflowRunId>/requirement-analysis/**` 中的理解、证据、澄清问题、澄清门禁、摘要和结果包。

接纳分析阶段在 `.ac` 写结构化证据：`workload-estimate.json`、`acceptance-recommendation.json`、`analysis-package.json`、`artifact-generation-gate.json` 和 `requirement-sizing.json`。这些是证据，不是给用户评审的 PRD / evaluation 正文。

待评审文档写入阶段写 `draft-docs-gate.json`、`review-gate.json`、`docs/requirement/<requirementSlug>/prd.md` 和 `docs/requirement/<requirementSlug>/evaluation.md`。

终稿确认阶段只更新已有 docs 草稿状态，并写 `finalize-gate.json`。

## Runtime 边界

runtime 脚本只做确定性辅助：读取 context、生成理解与澄清候选、记录人工回答、生成结构化评估证据、校验草稿 / 终稿 gate。脚本失败、依赖缺失或 context 不满足时必须阻塞并记录原因，不得手工模拟正常产物。

本 Skill 不改变机器契约字段、路径、schema、validator、workflow 或 marketplace。需要 runtime 子命令细节时读取现有脚本和 validator；不要把脚本参数说明复制成本 Skill 的主流程。

## 红旗

- 未读仓库、产品上下文或需求输入就提问、估算或写 PRD。
- 关键澄清未回答还生成 PRD、工作量或接纳建议。
- 早期凭需求标题猜 `requirement-sizing`。
- 把 `.ac` candidate 当成正式 docs 正文。
- 用户要的是可评审 PRD / 评估文档，却只写 `.ac` 过程证据后说完成。
- 把 review report、`review-gate.json`、`summary.md` 或 `result.json` 写成人工已审批。
- `finalize` 时从候选包首次创建 docs 文档。
- runtime 没跑通，却手工模拟产物。
- 把数据库、接口、路由、权限码写成需求分析结论。
- 把需求分析推进到需求设计、正式特性拆分或开发计划。

压力场景见 `references/pressure-cases.md`。