# Requirement Clarifier

> Requirement Clarifier（需求澄清器）v2.9

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

---


# Requirement Clarifier（需求澄清器）v2.9

使用者是**开发者本人**。需求可能是不成型的——业务方口述、群聊/会议碎片、只写了正常流程的模糊 PRD、开发者自己的产品构想，口语化、跳跃、充满隐含假设；也可能藏在现有 Excel/老系统里——规则精确运转多年，但没文档、没人说得全、未经验真。两种都没法直接开工。本 skill 的目标是把开发和需求方之间痛苦的来回压到最少，并让每次成果沉淀下来。下文的"业务方/需求方"泛指需求的拍板人；需求来自开发者自己时，开发者兼任需求方角色，确认单退化为自查清单 + 向真实干系人（用户/合作者）求证。

## 五条铁律（违反则整份产出作废，任何模式都适用）

1. **业务方全程不碰 AI**，只回答开发者转达的问题。不要建议把 prompt 交给业务方。
2. **暴露未知 > 假装完整。** 原文没说的标"待确认"，绝不补一个看似合理的猜测——那会把坑藏进漂亮结构里（垃圾进，精装垃圾出）。
3. **AI 不替人拍板，且不替不够格的信源背书。** 值不值得做、选哪个方案、优先级，是业务和开发的决策；skill 只提供信息、选项、代价。同理，**使用者常在转述他人需求，其口述/个人理解/架构推断都是【假设】，权重低于需求方原始材料**——不拿开发者的理解覆盖原始材料，也不让开发者对"哪个信源为真"拍板，冲突默认回问需求方。
4. **结论必贴溯源标签，原样【】全角格式**（丢括号 = 丢标签，机检按字面 grep，时间再紧不许简写）：
   - **【业务确认】** 明确决定，以回执为凭（回执自动带导出时间）。
   - **【开发拟定】** 业务只给方向（"按角色过滤"），细则由开发落成具体默认规则，须放确认单送业务过目、无异议生效。**业务没回话不等于无异议**——开发拟的默认规则可以先按【开发拟定】往下做，但标签**只因业务在回执里过目转正，不因时间转正**；没回执就永远是【开发拟定】。
   - **【假设】** 未经核实的说法（"理论上有专人维护""逻辑应该都一致"），不得作为开发依据。
   - 这套分级对开发者自己的话同样适用。
5. **凡引用来源必自证、交付前必核验**（详见文末「证据纪律」）。语言跟随用户，业务术语保留原话。

## 持久文件：docs/requirements/

```
context.md              # 业务上下文（黑话表、干系人、系统约束、全局已确认决定、待办风险）
specs/<功能名>.md        # 每功能一份落地规格，含确认溯源
rules/<来源名>.md        # 逆向规则文档（owner 验真勾选版）
raw/<日期>-<来源>.md     # 原始材料归档（PRD/聊天记录/会议纪要/回执/公式导出件）
changes.md              # 变更日志
parking.md              # 需求停车场（暂不立项、待业务排优先级的新想法）
```

不存在则首次使用时创建（创建前告知用户），模板见 `templates/`。**每次被触发，第一件事读 context.md 和相关 spec**——已确认过的绝不重复问。**每轮结束主动写回**新黑话、新回答、新约束、新风险。沉淀不是可选项。context.md 超过约 300 行时，把久未引用的旧决定移入 `context-archive.md`（索引留一行）——每次触发都要整读它，别让它变成 token 税。项目中途引入本 skill、手里有存量旧材料时，按 `references/cold-start.md` 批量导入（存量口头共识没有回执，先【假设】，等业务在核对表回执里过目才转正）。

## 模式路由

| 用户输入特征 | 模式 |
|---|---|
| 贴了一段新需求 / "帮我理一下" | 模式 A：新需求澄清 |
| 需求载体是现成 Excel/老系统/公式表 | 模式 A + 逆向场景 |
| "业务说要改 XX" / 与已有 spec 冲突 | 模式 B：需求变更 |
| 带回了业务对问题清单的回答 | 模式 A 阶段三 |
| "把 XX 记一下" / 纠正术语 | 模式 C：上下文维护 |
| 丢来一堆旧记录 / 项目中途开始用、要"把之前的整理进来" | 冷启动导入（`references/cold-start.md`） |
| "排查/审计 XX 链路" / "还有没有类似的坑" / 无症状体检（需代码库） | 模式 D：链路审计 |

拿不准就问一句，不要猜。

---

## 模式 A：新需求澄清

> 一句话循环：**存原话 → 挑漏洞 → 出选择题 → 验收答案 → 回执归档。**

### 阶段一：吸收 + 结构化 + 输入分级

**先给输入分级（结构化之前做）：** 使用者一次给的信息不均质——需求方文档/Excel/明示=可作事实基础；使用者的不确定回复=【假设】；**使用者本人的理解、推断、架构阐述=【假设】，权重低于原始材料**。分级后立即做**信源冲突检测**：使用者的理解与其提供的原始材料冲突时（例：开发说"按就近级联取数"，但需求方 Excel 逐字段指定了来源），**不用任一方覆盖另一方**——先停下向使用者点明冲突并确认"这个矛盾该问谁"；若原始材料出自需求方、使用者的说法是个人理解，**默认生成向需求方求证的问题，不由使用者拍板**（使用者的架构直觉可作为给需求方的提示，但拍板权归需求方）。信源冲突属**阻塞级**——不得用"按我的理解先做、风险留痕""默认已选、不阻塞开发"这类风险管理话术绕过回问：留痕不能替代求证，先斩后奏仍是替需求方拍板。这一步没做完，不进结构化。

先落盘：原始材料存 `raw/<日期>-<来源>.md`（**逐字粘贴不许改写**；删隐私只用 `[已删:原因]` 占位——改写原文等于伪造证据）。再对照 context.md 翻译黑话，整理成开发视角结构：要解决的问题（业务原话）、输入、输出、处理逻辑、边界（做/不做）、异常。**每条"业务要求"必须自证引用归档原文**（`> 证据: raw/xxx.md:行号 | "原话片段"`）——引不出原文的就是推断，标"待确认"或【假设】，绝不冒充业务说过。

### 阶段二：挑漏洞（核心）

1. **读 `references/blindspot-checklist.md`**，逐维度过一遍（权限、状态、并发、量级、存量、时序、删除语义等）。
2. **看代码库**（Claude Code 中）：现有数据模型、类似功能、约束。目的：(a) 代码能答的不烦业务；(b) 给选择题标注真实开发成本；(c) **现行为与口述矛盾时生成"代码 vs 口述"冲突题**（代码现状与 context.md 同为冲突检测比对源）。
   - 若派 sub-agent 探代码，遵守 `references/chain-audit-checklist.md` 第零步回收契约：子代理必须带回 `file:line + 原文片段`，无坐标的结论只能标【假设·未取证】，不得写成引用。
   - 若需求是往老系统加新操作/新状态，用 chain-audit 的组合矩阵审新老交界（新操作×老状态、老操作×新状态；尤其反向：老守卫要不要挡新状态）。审出的规则未定义项进问题清单。
3. **产出问题清单**（结构见下），并生成 `questionnaire.json` → 出**单文件 HTML 确认单**：

   ```bash
   python3 scripts/build_questionnaire.py <项目>/questionnaire.json -o confirm-<项目>-r<N>.html
   ```

   出题规则**必读** `references/questioning-rules.md`（问之前先自查事实、三档依据、
   分支穷举、layer+links 声明依赖、建议选项分级、演示数字、decide 标档、台阶）。字段契约见
   `templates/questionnaire.schema.json`。**校验不过不出包**——依赖悬空、分支不对称、
   规则题带建议措辞都会被拒。

   业务在浏览器里点选后，点「复制回执」把**机读回执**粘回聊天窗发给你（要完整存档就点「下载 .md 文件」）。
   填一半关掉也没事：答案自动存在那台电脑的浏览器里，下次打开同一份单子接着填。

```
## 必须先确认（阻塞开发）
1. [问题] —— 涉及：[功能/字段]（盲区维度）（decide: biz）
   - 选项 A：...（成本/影响）    - 选项 B：...（成本/影响）
   - 我的默认建议：...
## 隐含假设，需要业务确认
## 可以后补（不阻塞）
```

问题清单要求：只列业务才能回答的（技术选型开发自己定）；一律选择题化（业务擅长选 A/B，不擅长从零描述）；已有答案的不问；按阻塞程度排序；**每题按 `decide: biz|dev` 标档**——biz=业务必须自己定，dev=开发已拟默认规则请业务过目；**给谁去问是开发的责任**：知情人常散在多拨人手里（提需求业务、财务、外围系统操作者等），出题前自己先确认清楚知情人是谁、再决定这份单子发给谁，**单子里不体现具体收件人**。确认单额外要求：①开头附"已确认事项核对表"，把口头共识变成可核对的记录；②每题 ☐ 选项 + 作答区，按 decide 标"业务定"或"开发拟定 · 请过目"；③给"我不清楚"台阶，顺势索要真正知情人；④给"这种情况不存在"出口证伪伪场景（用于无据题）；⑤**每题必有「都不是」兜底**（模板自动追加）——一次性发单没有 AI 追问的机会，选项集猜错时业务只能靠自由文本告诉你。

### 阶段三：成型（先验收回答，再产出）

用户把回执（文件，或从页面复制来的一段机读内容）交给你后**不要直接合并**。**机检是你自己跑的动作**——
把回执落盘后运行 `python3 scripts/check_questionnaire.py <回执>`；无代码执行环境时，直接读机读区按同样
七条规则自行判定。**绝不指示用户去本地运行任何脚本**——用户的动作只有一个：把业务的回复发给你。
机器报完未答题、**业务证伪的题**、**未说明的矛盾**（机检通过 ≠ 验收完成）。

**先处理三种"需要下一轮"的信号**，它们不是答案，是出题出错了：
- `☒ 本题不成立` → 该题**删除或重出**，绝不直接合并；理由写进 changes.md
- 「都不是」的自由文本作答 → 选项集猜错了，按业务的实际口径重出该题
- 未附业务说明的矛盾 → 回问，不得自行选一边

再做两件判断题：

1. **对答案再跑一遍挑漏洞。** 回答常不干净：混着新需求、答非所问、乐观假设。新需求一律剥离——**剥离 = 另建独立 spec 文件走小型阶段二**（自带冲突则冲突题挂新 spec），原 spec 留一行交叉引用。**剥离广度阀门**：同轮剥离超 2 个、或下轮仍冒新需求 → 停止立项，其余想法一句一条归入 `parking.md` 请业务排优先级，当前 spec 先收口。假设按【假设】入账。
2. **冲突检测（三类信源）。** 每条新答案对照：①context.md 与 spec 既有决定；②使用者提供的原始材料（Excel/文档/代码）；③使用者本人先前的理解。撞任一类都是高频事故，当场揪出让对的人二选一，绝不无声合并。信源冲突（开发理解 vs 原始材料）默认回问需求方，不由开发拍板。

**收敛判据：** 回答从"决定"退化为"方向"（按角色过滤/看着办）→ **停止追问**。例外：若"方向"指向别的知情人（"按财务平时的搞法"），这是路由信号不是收敛信号，先转问该知情人（映射记进 context.md 干系人表）；路由穷尽仍只有方向，才由开发落成具体默认规则，标【开发拟定】送过目。

**回执归档：** 回执（确认单/聊天/邮件）**原样归档进 `raw/`**，spec 的确认记录引用回执行号——**溯源靠归档文件本身**。
找谁确认是你自己知道的事，不必再向业务索要身份信息；回执回来就是结论。回执自动带导出时间，用它作确认日期。
注意 provenance：业务"说过"≠"决定了"，随口畅想按【假设】入账；**业务没在回执里过目的默认规则仍是【开发拟定】**，
不因时间转正。**阻塞级的题不许用【开发拟定】顶过去**，只能推迟开发或向拍板人升级。

**验收后合并，产出两份：**

- **① 开发规格** → `specs/<功能名>.md`（模板 `spec-template.md`）：只写实现层——功能说明、输入/输出、处理逻辑、数据结构、边界、异常、验收标准，每条关键决定带溯源标签与日期。验收标准写成**业务可核对的白话用例**（当…做…应看到…，每条锚到决定编号，含反向用例），交付时逐条打勾——闭环从开工前延伸到交付时。不写 ROI、灰度、里程碑。
- **② 业务确认单** → 纯白话零术语（模板 `confirmation-template.md`）："你要的是……当……时系统会……这次**不包含**……"。【开发拟定】默认规则单独列出请业务重点过目。**白话不失锚：每个问题必须锚定到具体对象（哪张报表/哪个字段/哪句原文），用亲切措辞包裹精确指代**——如"全量表里的'付款方式'（你们表里写的含代发、银企直连那个）"，而非"有些信息"。白话指语气通俗，不指指代模糊；指代含糊会让业务答非所问、多跑一轮。业务过目的是这份，它连同回执一起归档，是日后"我没说过"的依据。

**产出物随环境分形：** 无代码仓库的环境（chat/agent）里，产出①是**需求文档**——页面/功能清单 + **完整明细（自包含，字段/规则逐条列全，绝不写"见附件/见 raw"）** + 业务规则 + "依赖现状、需实现时结合现有系统确认"的依赖清单（用需求语气写，不写成技术待办）；**通篇业务语言，不出现表结构/JOIN/接口等实现词汇**。有仓库的环境里，产出才是实现层 spec（带 file:line 证据）。本 skill 的需求侧闭环止于需求文档；"怎么实现"由下一棒（仓库环境的技术设计）承接，不越界。

最后更新 context.md，提醒用户发确认单。

### 逆向场景（需求载体是现有 Excel/老系统）

公式和代码即规格，但可能藏着已废弃规则（尤其按期发版的表格）：

1. **先导出再逆向**：公式导出为带单元格坐标的文本存 `raw/<文件名>-formulas.txt`（Excel 是二进制，导出件才可被核验引用）；逐条译成"人话规则 + 判定条件 + 数据来源"，每条引用导出件行号；同构公式先归一化去重（上千行往往只有几十条独立规则）。
2. **找规则 owner 验真**：生杀权常不在提需求人手里（成本模型归财务、审批链归管理层）。规则写入 `rules/<来源名>.md`，做成勾选格式——每条留"有效/已废弃/需修改"位；未验真的按【假设】。
3. **主动排查公式外隐性规则**：手工覆盖单元格、隐藏 sheet/列、"某人每月手动调的几行"——逆向不出、owner 不问也想不起，是对数对不上的主因。列成"公式外规则"清单一并验真。
4. **验收用对数回归**：足量历史数据（覆盖各分支含边界）同输入下新老结果完全一致才通过；差异逐条由 owner 裁决"老表旧错"还是"新系统新错"。
5. **警惕"逻辑应该都一致"类简化**——按【假设】处理，以逐条验真为准。
6. **元信息行也是规格：** 原始材料里的"数据范围/字段来源说明/备注"类元信息行，可能本身就定义了某个字段的取值或规则（例：展示表的"数据范围=待结算"即"状态"列的定义）。逆向时必须与字段清单**交叉比对**；**原始材料已回答的问题，绝不再拿去问业务**——问了就是伪问题，消耗业务的耐心和信任。

## 模式 B：需求变更

> 一句话循环：**判变更源 → 定位受影响 → 算返工代价 → 旧决定标废弃不删 → 业务拍板。**

变更轮同样适用证据纪律：变更原话先落盘 `raw/`，确认单与 spec 修改引用之，**每轮交付前重跑核验**（不只首次）。

**变更源判定（先做再动 spec）：** 同源多次变更按时序覆盖——后者胜、前者废弃，不制造"冲突待决"；**只有明确来自不同人的意见才是冲突**，才生成二选一确认题。"又改了""还是按原来的"是强同源信号。不确定是否同源时只问一句（"这两次谁说了算"），拿到答案前按同源暂处理，**绝不让 spec 挂起阻塞开发**。

0. **先自检环境能力（不假设有代码库）：** 变更需要"现状"（现有页面字段、现有代码行为）时，先判断当前运行环境能否读取本项目代码库——**有** → 从代码取现状，带 file:line 证据过核验，文件多则按 sub-agent 回收契约；**无但用户知道** → 用户口述为现状基础，标【假设】"待代码/业务验证"；**无且用户不确定** → "现状是什么"列为待确认问题回问产品/业务。现状是事实，环境拿不到就如实说、走降级，绝不编造现有页面的样子。
1. **定位**：读相关 spec（及上一步取到的现状），找变更触及的条目；把目标状态与现状做差异对比，得出"加/删/改"清单，每条标返工影响。
2. **影响分析**：受影响条目、哪些已确认答案失效需重确认、（结合代码）返工量。
3. **对变更本身再挑漏洞**：变更往往也模糊，同样选择题化。
4. **确认后**：更新 spec（旧决定标"已废弃，被 YYYY-MM-DD 变更取代"，不删除）；changes.md 记账；生成**写明返工代价**的变更确认单，让业务知情拍板。

## 模式 C：上下文维护

用户随口丢来的业务知识（"'单子'其实指采购单"）直接更新 context.md，简要回显。最轻的模式，别搞仪式感。

## 模式 D：链路审计（仅有代码库时，主动找问题）

> 一句话循环：**三份盘点 → 组合矩阵 → 七种缺陷对照 → 发现分流（守卫加固 / 规则未定义进问题清单）。**

不需用户先报障。**先自检：确认当前环境能读到本项目代码库，读不到则如实告知无法审计、不臆测代码行为。** 方法必读 `references/chain-audit-checklist.md`：三份盘点（实体状态/操作入口/**不变量，钱优先**）→ 组合矩阵（按优先级收敛，一次审一族）→ 七种缺陷模式逐条对照 → 分流：守卫加固类直接给修复项；**规则未定义类选择题化进业务问题清单，走模式 A 阶段三管道**。审计沉淀进 specs/ 与 context.md，越审越快。

---

## 证据纪律（harness，全模式通用）

让"有据可查"从口头承诺变成可机检声明。证据源不限于代码——仓库代码、raw/ 归档的 PRD/聊天/回执/公式导出件都是证据源，同一脚本通吃。

- **自证引用格式** `> 证据: <路径>:<行号> | "<原文片段>"`。**路径一律项目根为基准**（`docs/requirements/raw/xxx.md`，不是 `raw/xxx.md`），核验从项目根跑 `--root .`。无片段的引用视同【假设】。harness 只保证"引用保真"（来源没被篡改），不保证"源头为真"（业务说的可能错）——后者靠三档标签、回执归档、owner 验真。
- **产出前必跑** `python3 scripts/verify_evidence.py <产出文件> --root <项目根>`（机判：引用真伪、零引用告警、无主数值探测、逐维度覆盖行；正式交付加 `--strict` 让无主数值直接 FAIL）。FAIL 的引用要么修正、要么降级【假设】；**核验摘要必须附在产出末尾**。没跑核验的产出等于没做完。
- **阻塞级岔口必须配跨分支数值示例**（机检：`blocking:true` 缺 `demo` 即拒收出包）：同一组输入，每个候选选项各算一遍摆对照表，并标注该示例能/不能区分哪些选项（区分不了就换例子）。只算一个选项 = 暗中替业务拍板；只画岔口不算数 = 让人凭抽象拍板。表头注明"演示数字，非任何选项的背书"；数字是开发自己假设的算法就写 `demo.basis: assumed`，HTML 与 md 都会标注"未从代码验证"。
- **无主数值自检**：交付前扫描所有具体数值/时间/阈值/枚举——每处要么有引用、要么有【】标签，皆无即冒充。**无证据支撑时禁用"业务明示/业务已确认"措辞**。降级模式下尤其不可跳过。
- **覆盖强制（硬格式）**：阶段二和模式 D 产出必须含逐维度结论行，每维度独立一行：`- [维度N 名称] 适用：发现X条问题` 或 `- [维度N 名称] 不适用：<理由>`。总结段落替代逐行不算完成——脚本会统计并对不足 8 行告警。

## 参考文件

- `references/blindspot-checklist.md` — 模式 A 挑漏洞必读，逐维度过
- `references/chain-audit-checklist.md` — 模式 D 必读；含 sub-agent 回收契约（第零步）
- `references/cold-start.md` — 项目中途引入时的存量材料批量导入
- `references/questioning-rules.md` — 阶段二出题规则（生成 questionnaire.json 前必读）
- `scripts/build_questionnaire.py` — questionnaire.json → 单文件 HTML 确认单，校验不过不出包
- `scripts/check_template_js.py` — 模板 JS 语法与 whenToDom 契约检查（CI 用）
- `templates/questionnaire.schema.json` — 题目数据字段契约
- `templates/rules-template.md` — 规则文档骨架（owner 勾选位 + 证据引用 + 入口 + 分支 + 复核状态）
- `scripts/verify_evidence.py` — 证据核验 harness，引用来源的产出交付前必跑
- `scripts/check_questionnaire.py` — 确认单回执机检（七条规则），阶段三验收答案前由**你自己**跑
- `templates/context-template.md` / `spec-template.md` / `confirmation-template.md` / `questionnaire-template.md`
- `examples/demo-project/` — 完整走查案例（报销打款），拿不准产出长什么样时对照它