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/明示=可作事实基础；使用者的不确定回复=【假设】；使用者本人的理解、推断、架构阐述=【假设】，权重低于原始材料。分级后立即做信源冲突检测：使用者的理解与其提供的原始材料冲突时（例：开发说"按就近级联取数"，但需求方 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 确认单：

   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/ — 完整走查案例（报销打款），拿不准产出长什么样时对照它