Requirements Matrix Generator

将差距分析文档转化为技术分层需求矩阵，输出 requirements/ 目录。

语言约定：正文一律中文；EARS/FPF/模板结构关键字保留英文（SHALL / WHEN / Status / Validates / P0-P3 等）。

Quick Reference

核心流程:

差距分析文档 → 提取问题 + runtime 复核 → 10层分类映射 → 00-INDEX.md + N个需求文档 → 场景覆盖度审计

输入: 任何结构化的问题清单（FPF 审计报告、竞品差距、用户反馈、技术债务等） 输出: requirements/ 目录（00-INDEX.md + 按技术层级组织的需求文档） 下游: 每个需求文档可作为 /spec-dev 的输入，生成 4 文件 Kiro Specs（01-04；矩阵模式下 00-discovery 由需求文档替代，默认跳过）

10 层技术分类法

不是每次都需要 10 层全部填充。根据差距分析按需选择相关层级；未填充的层级必须在 INDEX 写「空层不填充理由」（见 Step 3）。

Standard Workflow

Step 1: 分析输入文档（含 runtime 复核）

1. 识别输入类型（审计报告 / 差距分析 / 问题清单 / 用户反馈）
2. 提取所有问题，建立问题清单表：

| # | 问题描述 | 优先级 | 证据/来源 | runtime 复核（方式+日期） | 技术层级（待分配） |
|---|---------|--------|----------|--------------------------|------------------|

3. runtime 复核（硬步骤，runtime > canon，不可跳过）：
   • 每个从审计/文档提取的问题，矩阵化前必须 runtime 抽查（grep/实测），并在清单中标注验证方式 + 日期
   • 对老文档断言做对抗 confirm/refute（双向证伪：既找支持证据也找反驳证据）。历史实锤双向翻车：把"设计过但从未实现"当"已实现有 bug"；把文档"未接线"当真（实际已接线）
   • 暴露度检查先于优先级：已确认但休眠（无真实流量触达）的问题 → 状态记 Frozen (tripwire)（登记数据触发条件 + 测量探针），而非立即 spec
4. 确认项目约束（首次使用时与用户确认，后续复用；已有权威约束的项目优先引用其规则文件而非重问，本工作区见 .claude/rules/*）：

| 约束类型 | 规范要求 |
|---------|---------|
| 导入路径 | {如：@/ 绝对路径} |
| 主键生成 | {如：nanoid()} |
| i18n | {如：next-intl zh/en} |
| 认证中间件 | {如：adminActionClient} |
| 输入验证 | {如：Zod schema} |
| 错误处理 | {如：标准 error response} |

Step 2: 技术分层映射（含决策依赖识别）

1. 将每个问题映射到 10 层中的对应层级
2. 分配编号：{前缀}-{序号}（如 UI-001, DB-001）
3. 决策依赖识别：逐问题标注阻塞决策 ID（无则填「无」）；未拍板决策登记进 INDEX 决策台账，被阻塞需求在文档中写成条件组（方案 A/B/C 各一组需求，拍板后回填）
4. 输出映射表供用户确认：

| 问题 | → 层级 | 编号 | 文档标题 | 阻塞决策 |
|------|--------|------|---------|---------|
| Dashboard 假数据 | 40-frontend | UI-001 | Dashboard模板残留清理 | 无 |
| N+1 查询 | 30-database | DB-001 | Dashboard批量查询优化 | 无 |

5. 等待用户确认映射后再继续；批量授权模式下（见「批量生成模式」）本确认门降级为"输出映射表供事后审查"

Step 3: 生成 00-INDEX.md

使用 templates/00-INDEX.template.md 生成导航枢纽，包含：

• 文档矩阵概览（ASCII 图）+ 按任务类型快速定位表 + 文档清单（每层文档列表 + 描述 + 优先级）
• 项目约束清单（权威单点） — 全矩阵唯一权威约束表（单点化规则见 Step 4）
• 决策台账 — 决策 ID / 问题 / 选项 / 状态 open|decided / 拍板值+日期+理由；无法当期验证/休眠的开放项用 tripwire 冻结收口（数据触发条件 + 测量探针），而非模糊时间欠账
• 共享文件热点表 — 文件 → 触碰它的需求 ID 列表（静态可预判），供实施期共享资源冲突规划：热点文件用合并者模式，并行 agent 按文件不相交分组
• 波次实施计划 — P0→P3 分波执行顺序；每波末尾设全量回归门（tsc + 全量测试 + 生产 build）；波间提示「实施下一波前先做前提复核（file:line 锚点对当前 HEAD 重验）」；structure-first 需求标注「{ID} 落地后下游锚点须重验」
• 空层不填充理由 — 未使用的层级逐条写明为空原因（确认无问题 vs 未审计到），防止"空层"与"漏审"混淆
• 跨切面实施告警 — 跨多层/多文件的需求显式标注，提醒实施期不可按单文档孤立处理

Step 4: 逐个生成需求文档

按优先级顺序（P0 → P3）逐个生成，使用 templates/requirement.template.md。

每个文档包含：

1. Document Info（版本、状态、优先级、来源、runtime 复核方式+日期）
2. 项目约束遵循表 — 共享硬约束单点化：权威约束表只在 00-INDEX.md 维护一份，需求文档只引用（"遵循 INDEX 项目约束清单"）并登记本文档差异项（新增/豁免/收紧），禁止整表复制造成多份漂移
3. 阻塞决策表（决策 ID / 状态 / 拍板值与日期；无则填「无」）
4. 问题描述（引用差距分析中的证据 + runtime 复核结论）
5. 实现方案（概要级代码片段或流程图）
6. 交叉引用（关联的其他需求文档编号）

完成后输出提示：

✅ 需求矩阵已生成，共 N 个需求文档。

接下来请对每个需求文档调用 /spec-dev 生成 4 文件 Kiro Specs
（01-04；矩阵模式下 00-discovery 由需求文档替代，默认跳过）：

1. /spec-dev → 输入 {前缀}-{序号}-{标题}.md
2. /spec-dev → 输入 {前缀}-{序号}-{标题}.md
...

输出目录：requirements-specs/{层级编号}-{类别}/{前缀}-{序号}-{英文slug}/
（与 spec-dev 的 requirements-specs/{NN-layer}/{PREFIX-NNN-slug}/ 为同一路径，
两种占位符记法等价，具体如 requirements-specs/40-frontend/UI-001-dashboard-cleanup/）

Step 5: 场景覆盖度审计

矩阵生成后、交付前的收尾硬步骤（技术分层是组织视角，不是完备性证明）：

1. 列出该模块的全部用户旅程（端到端场景：从入口动作到业务闭环）
2. 逐旅程逐步骤映射需求覆盖：哪一步由哪个需求 ID 承接
3. 输出覆盖率 % + 断链清单（旅程中无任何需求承接的步骤）
4. 断链项回填 Step 2 重新映射，或显式记入 INDEX（决策台账 / 空层不填充理由 / 已知缺口）

依据：002 批次实锤——纯技术分层自查全过，按用户旅程映射才暴露 55% 覆盖率与 3 个致命断链。

批量生成模式（Authorized Batch Mode）

默认：各确认门照旧（交互式）。当用户给出明确常设授权（goal / "依次实施不要停止，自行做最优选择"类指令）时启用本模式：

• 映射确认（Step 2）降级为"输出映射表供事后审查"
• 一轮生成多套需求文档/多个矩阵时，按依赖序排列（被依赖者先生成，供后续引用）
• 逐项确认门由以下替代物满足：
  • (a) 批次级一次性授权记录（记入 INDEX 或批次文档）
  • (b) 每波全量回归门（tsc + 全量测试 + 生产 build）绿后才 commit —— 经波次实施计划约束下游实施
  • (c) 每 spec 收口记录 —— 约束下游实施闭环（无收口记录 = 未收口）
  • (d) 批次终报（执行结果 + 落地结论；矩阵生成阶段 = 生成结果 + 场景覆盖率/断链清单）
• 不可逆/对外动作（生产部署、删数据、对外发布）不在默认授权范围，仍须逐次确认，除非授权明确覆盖

文件命名规则

{层级编号}-{类别}/{前缀}-{序号}-{中文标题}.md

示例：
10-business-logic/BL-001-Admin运营数据聚合.md
40-frontend/UI-001-Dashboard模板残留清理.md
60-security/SEC-001-Admin权限统一检查.md

状态流转词汇表

需求文档与 INDEX 的 Status 字段使用固定词汇（禁止自创变体）：

Draft → Ready-for-Specs → Specs-Generated → Implemented → Gray-Verified → Closed

旁路状态：

• Frozen (tripwire) — 已确认但休眠（无真实流量触达），挂数据触发条件 + 测量探针，触发后回到主链
• Blocked (decision) — 等待决策台账拍板；拍板后 Status 转出并回填拍板记录，未选分支保留存档

Critical Rules

ALWAYS

1. ALWAYS 在 Step 1 做 runtime 复核 — 每个提取问题 grep/实测，标注验证方式+日期（runtime > canon）
2. ALWAYS 在 Step 2 等待用户确认映射 — 分类可能有歧义；批量授权模式下降级为"输出映射表供事后审查"
3. ALWAYS 在 00-INDEX.md 维护决策台账 — 未拍板决策显式登记，被阻塞需求标注阻塞决策 ID
4. ALWAYS 让需求文档引用 INDEX 权威约束表并登记差异项 — 确保约束单点维护、任何上下文可感知
5. ALWAYS 引用差距分析中的原始证据 — 需求必须可追溯到源头
6. ALWAYS 在完成后输出 Skill 2 调用提示 — 引导用户进入下一阶段

NEVER

1. NEVER 把未经 runtime 复核的文档断言直接矩阵化 — 老文档断言必须先做对抗 confirm/refute
2. NEVER 在需求文档中放完整实现代码 — 完整代码属于 specs/02-design.md
3. NEVER 跳过 00-INDEX.md — 它是整个矩阵的导航枢纽
4. NEVER 使用模糊优先级 — 必须明确 P0/P1/P2/P3

References

• 10 层分类法详解 — 每层的详细定义、判断标准、边界案例
• 文档模板库 — INDEX 和需求文档的模板讲解（权威源为 templates/）
• 完整案例 — 管理后台审计 → 9 个需求文档的映射过程

Changelog

v2.1 (2026-07-08) — 008 端到端实施验证

蒸馏来源：008 docs 优化专项（SSD 全链首次端到端跑通，本 skill 生成 12 需求矩阵 → 12/12 spec 全终态）。追加式：v2.0 的四个核心机制（热点表 / 波次 structure-first / 追溯表 / 决策依赖+tripwire）在实施期得到实锤验证，无机制返工，仅补一批实施期证据 lessons。详见 references/case-study.md 新增「008 实施期验证」小节。要点：

• 共享文件热点表 = 零冲突的实施合约（实锤）：billing.mdx 被 UI-002/UI-004/UI-005/SEC-001 四需求跨 3 波触碰，热点表预判 + 合并者模式（UI-004 为主改者、其余申报差异）使四波串行实施零冲突。教训固化进 Step 3：热点表不是「参考」而是并行/串行分组的依据，主改者字段必须落表。
• 波次 structure-first 标注 = 下游锚点漂移的唯一防线（实锤）：CODE-001 全域 252 处域名替换（32 文件）先行落地（8ba094ed），使下游 11 需求 file:line 锚点全部漂移；波次计划的「structure-first 先行 + 波间前提复核」提示在实施期兑现——下游需求逐一重验锚点后再动手，无一处改错行。structure-first 需求必须排 Wave 1 首个。
• 追溯表在实施期是「零遗漏」的可核对账本（实锤）：95 发现→12 承接 + 8 条 INDEX 显式登记，实施收口时逐条回填 Status，无一发现掉队。教训：追溯表要覆盖不立需求的去向（拍板不立 / Frozen / 人工 / open 条件组 / 正向核销五类），否则「零遗漏」不可核销。
• 决策依赖（条件组）+ Frozen(tripwire) 在实施期正确解卡（实锤）：open 决策 COV-10/11 的条件组让 UI-002/UI-006 走默认分支落地不阻塞；Frozen 的 BS-7/BS-8 与截图族 tripwire 在实施期被正确「不做」（触发器未命中）。教训：open 决策必须给默认分支（否则实施期卡死），dormant 高危必须给触发器（否则要么漏做要么过度工程）。

v2.0 (2026-07-06)

蒸馏来源：007/004/006/003/002/105 等批次收口记录 + 记忆层，共 92 条 lessons。主要变更：

• 下游口径修正：「5 文件 Kiro Specs」→「4 文件 Kiro Specs（01-04；矩阵模式下 00-discovery 由需求文档替代，默认跳过）」
• Step 1 新增 runtime 复核硬步骤（grep/实测 + 验证方式与日期标注；对抗 confirm/refute；暴露度检查 → Frozen (tripwire)）
• Step 2 新增决策依赖识别；批量授权模式下映射确认降级为"输出映射表供事后审查"
• Step 3 INDEX 新增产出：决策台账 / 共享文件热点表 / 波次实施计划 / 空层不填充理由 / 跨切面实施告警
• Step 4 共享硬约束单点化（INDEX 权威表 + 需求文档差异登记）
• 新增 Step 5 场景覆盖度审计（用户旅程映射 + 覆盖率 % + 断链清单）
• 新增「批量生成模式」「状态流转词汇表」章节；Critical Rules 同步扩充
• templates/ 与 references/ 同步升级 2.0（INDEX 四新节、需求模板阻塞决策表 + runtime 复核行 + 相对链接修复、case-study 计数修正、模板库去重）

v1.0

• 初版：10 层分类法 + 4 步工作流 + 模板与参考文档