spec-traceability

用途

spec-traceability 用于让每个开发任务都能证明自己服务于规格中的哪一部分。应用规格以 Markdown 形式保存在一个规格文件夹中，每条需求（REQ-）、界面（SCR-）、决策（DEC-）、不可让步规则（NN-）和范围外条目（OOS-）都有稳定 ID；首个失败的测试、代码注释、端到端流程、提交正文和报告都会引用相应 ID，两个脚本则用于原样打印条目并证明仓库及历史中的每处引用都能解析。该技能对 iOS 和 Android 同样适用；没有规格的应用会得到 NOT APPLICABLE 的干净结果。

主要规则

规格决定做什么，其中的不可让步规则（NN- 条目）不能违背；若任务、设计、库或其他需求会破坏某条规则，应先停下来询问，而不是写代码。
引用规格必须原样打印条目（如 spec-lookup.mjs <id>），不得凭记忆转述，避免记错数字后测试也断言同一个错误值。
ID 必须严格按规格定义书写，界面名与 ID 一起出现，如 “Task list (SCR-1)”；前缀来自应用的 contracts/spec.json，默认 NN-、SCR-、REQ-、DEC-、OOS-。
当规格对用户可见内容沉默、模糊或自相矛盾时，应停下来提问：引用相关行，给出两三个选项及推荐默认值，同时继续处理其他部分；绝不发明产品行为，也不重复询问规格已回答的问题。
开放决策使用其文档化的 Default: 并在报告中说明，仅在默认值失效时询问；已定决策（Decided:）不再追问。
不构建规格标为范围外（OOS-）的内容，规格中的数字视为上限而非目标。
ID 永久稳定：新条目取下一个可用编号，不得重命名、重新编号或复用，被丢弃的条目保留 Status: dropped。
已构建的需求必须有测试或流程引用；在添加引用它的绿色测试的同一提交中把需求或界面标记为 Status: built，已构建界面的 Route: 必须指向真实存在的文件。
被追溯的 ID 必须符合提交信息和测试引用模式；contracts/commits.json 的 requirementRef（或 scripts/git/requirement-ref.json）以及 tdd-workflow 的 requirementIdPattern 都应接受每个被追溯的 ID。
平台差异必须写明而不能假定：iOS 与 Android 行为不同时，条目用 Platforms: 说明或拆分为每个平台一个子条目，各自由自己的测试或流程追溯；只描述一个平台的规格对另一平台是沉默的。
多个功能共用的行为应构建一次放在共享层，并在测试该共享部分的地方引用，不要复制到单个功能内。

使用方式

工作流程大致为：

用 node ${CLAUDE_SKILL_DIR}/scripts/spec-lookup.mjs . --list 判断应用是否维护规格；没有规格时（NOT APPLICABLE）从 issue 或验收标准中引用需求键（如 TASKS-12、#41）并跳到第 6 步；仅在开发者需要时再启动规格（第 9 步）。
打印任务所服务的条目，如 node ${CLAUDE_SKILL_DIR}/scripts/spec-lookup.mjs . REQ-4 SCR-2，支持 --list --kind screen、--brief、--from <file>；标记为 dropped 或 out-of-scope 的条目会打印 NOTE，提示不要构建。
阅读任务涉及的不可让步规则（--list --kind non-negotiable），网络、数据、布局、文本、无障碍或权限相关工作至少触及一条。
查看决策与范围（--list --kind decision、--kind out-of-scope），使用开放决策的默认值并记录，不构建范围外内容。
规格沉默、模糊、矛盾或只覆盖一个平台时，按 references/questions-and-decisions.md 写出需求问题（引用行、选项、默认值）并按 git-commits-and-reporting 的请求格式发送，同时继续其余工作。
把 ID 写进工作产物：首个失败测试的标题或注释引用规则（如 it('moves the task to Done (REQ-2)')），保存决策默认值的常量引用该决策，流程以 “Task list (SCR-1)” 命名界面，提交正文写明 ID，报告以标题加 ID 命名界面。
在同一提交中更新规格：切片开始时设 Status: in-progress，引用测试变绿时设 Status: built；变更需求改变测试预期时，该提交更新条目、在正文说明原因并带上 Spec-Change: <ID> <what changed>。
在仓库根目录运行 node ${CLAUDE_SKILL_DIR}/scripts/check-spec-refs.mjs .，对本次会话的提交运行 node ${CLAUDE_SKILL_DIR}/scripts/check-spec-refs.mjs . --range <base>..HEAD（--trace 为报告添加需求到测试的矩阵），修复所有 FAIL 行直到输出 RESULT: PASS。
启动规格（每个应用一次）：把 templates/docs/spec/ 复制到 docs/spec/，把 templates/contracts/spec.json 及其 schema 复制到 contracts/，用应用自己的条目替换 Tasks 示例（全部标记为 planned），除非应用已有 ID，否则保留默认前缀。若提交契约自定义了 requirementRef 模式，需让它接受规格 ID。当应用此前没有 docs/ 时，需在同一提交中把 docs/ 加入 .prettierignore、把 'docs/**' 加入 eslint 配置的 PRE_EXISTING（带 Gate-Change: trailer），或在 rn-skills.config.json 的 layoutEntries 中声明 “docs”。

完成定义

工作所服务的条目已用 spec-lookup.mjs 打印，并在首个失败测试（标题或注释）和提交正文中引用。
未牺牲任何不可让步规则；任何冲突都在构建前提出。
工作依赖的每个开放决策都在报告中连同所用默认值点名，每个规格空白都以引用行和默认值提问。
未构建任何范围外内容；规格中的数字按上限使用。
本次工作完成的条目为 Status: built，各自由测试或流程引用；平台差异行为已按平台分别说明和追溯。
检查不打印 SKIP 行；无规格应用打印 NOT APPLICABLE 即通过。
check-spec-refs.mjs . --range <base>..HEAD 输出 RESULT: PASS（本次会话首个提交前范围为空，会打印一条 NOTE 并只检查文件）。

适用场景与限制

适用于维护需求规格或验收标准、需要在测试、提交流程与报告中形成证据链的 React Native 迭代开发，尤其是同时覆盖 iOS 与 Android 的项目。该技能依赖 Markdown 规格文件夹与两个 Node 脚本，规则较严格：不得凭记忆引用、不得发明产品行为、不得构建范围外内容，并对提交与测试的引用模式有格式要求。资料未提供具体的运行环境版本要求、脚本依赖之外的额外配置细节或收费信息。

技能介绍

用途

主要规则

使用方式

完成定义

适用场景与限制

相关技能