spec-driven-review

您正在审查一项已完成的规范驱动变更的代码质量。

此技能的命令

如果您不记得此技能使用的确切命令，请先在此处查找 再运行任何命令。不要猜测。

modify: node {{SKILL_DIR}}/scripts/spec-driven.js modify
apply: node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>
audit-spec-mapping-coverage: node {{SKILL_DIR}}/scripts/spec-driven.js audit-spec-mapping-coverage <spec-path> [--implementation <repo-path> ...] [--tests <repo-path> ...]
audit-unmapped-spec-evidence: node {{SKILL_DIR}}/scripts/spec-driven.js audit-unmapped-spec-evidence [--implementation <repo-path> ...] [--tests <repo-path> ...]

前提条件

.spec-driven/ 目录必须位于项目根目录。继续之前，请确认：

ls .spec-driven/

如果检查失败，说明项目尚未初始化。请先运行 /spec-driven-init。

步骤

1. 选择变更 — 运行 node {{SKILL_DIR}}/scripts/spec-driven.js modify 列出活跃变更。询问要审查哪项变更。如果已经指定，则使用该变更。

2. 确认就绪 — 运行：

   node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>
   

   如果 remaining > 0，请停止 — 该变更尚未准备好接受审查。建议先运行 /spec-driven-apply。

3. 加载上下文 — 阅读：

   • .spec-driven/changes/<name>/proposal.md — 范围和未变更的行为
   • .spec-driven/changes/<name>/specs/ — 描述预期行为变更的增量规范
   • .spec-driven/changes/<name>/design.md — 方案和决策
   • .spec-driven/changes/<name>/tasks.md — 已实现的内容
   • .spec-driven/changes/<name>/questions.md — 已解决的问题，可能有助于解释决策或权衡
   • .spec-driven/config.yaml — 项目上下文和规则，包括 test 规则以及任何 fileMatch 条目
   • 相关主规范文件和增量规范文件中的映射 frontmatter

4. 识别变更文件 — 根据已完成的任务和映射 frontmatter，确定哪些文件是新建或修改的。完整阅读每个文件， 包括相关规范文件映射的实现文件和测试文件。

5. 识别专用审查清单 — 在提交审查结果前， 根据提案、增量规范、设计、任务、 问题、变更文件、映射 frontmatter 和仓库上下文中的证据，对变更进行分类。 应用所有适用的清单；清单路由是累加的，不会取代基线审查检查。对代码的审查应与作者身份无关： 不要因为代码可能由 AI 生成、之前由您生成或由人编写，就轻信或放宽审查标准。

   支持的清单类型：

   • 安全敏感：涉及身份验证、授权、 权限、机密、令牌、输入边界、数据暴露、依赖信任或安全失败行为的变更。
   • UI：涉及面向用户的屏幕、布局、交互状态、可访问性、键盘行为、响应式行为或视觉回归的变更。
   • DX：涉及命令、提示词、生成产物、 文档、运维人员消息、错误消息、设置或本地工作流易用性的变更。
   • 迁移：涉及数据转换、文件系统或架构迁移、向后兼容性、幂等性、回滚或部分失败行为的变更。
   • API：涉及公共或内部契约、命令参数、JSON 结构、错误语义、验证行为、版本控制或调用方影响的变更。
   • 维护：涉及定期或手动维护、依赖更新、生成文件、仓库整洁、可重复性或避免无关变更的变更。

6. 审查代码质量——针对每个已更改的文件，运行基线审查检查，以及第 5 步中确定的任何专项检查清单：

   • 公正性：评判实际存在的代码，而非代码的作者；不要因为代码由 AI 编写或自己编写，就压下、弱化或跳过问题
   • 可读性：命名清晰，函数长度合理，没有不必要的复杂性
   • 安全性：不存在注入漏洞，不硬编码机密，在系统边界正确验证输入
   • 错误处理：妥善处理外部调用和用户输入的错误；不吞掉错误
   • 性能：不存在明显的 N+1 查询、不必要的内存分配，或异步上下文中的阻塞调用
   • 最佳实践：遵循项目约定（参考 config.yaml 上下文），没有死代码，未遗留调试产物
   • 安全敏感检查清单：验证授权边界、机密处理、注入防护、数据暴露、输入验证和安全失败行为。
   • UI 检查清单：验证关键交互、无障碍访问、布局稳定性、状态转换、响应式行为，以及用户可见回归的覆盖情况。
   • DX 检查清单：验证命令使用体验、文档或提示词的清晰度、错误信息是否可采取行动、设置兼容性，以及与现有工作流的一致性。
   • 迁移检查清单：验证幂等性、向后兼容性、回滚或恢复预期、部分失败处理和数据保留。
   • API 检查清单：验证契约兼容性、输入验证、错误语义、版本管理或迁移预期，以及对调用方的影响。
   • 维护性检查清单：验证可重复性、依赖项或生成产物的安全性、仓库整洁度，以及没有无关改动。

7. 检查测试质量——阅读与此变更相关的测试文件：

   • 测试是否覆盖增量规范中的关键场景？
   • 测试是否相互独立且可重复？
   • 测试是否遵循 config.yaml 中的 rules.test？
   • mapping.tests 条目是否保持最新，并有助于今后的验证？
   • 对于相关专项检查清单中的风险，在风险可观察且可测试时，测试是否覆盖这些风险？

8. 审查映射质量——对于与此变更相关的每个已修改规范文件：

   • 将 mapping.implementation 和 mapping.tests 与此变更的主要实现文件及直接验证该变更的测试文件进行比较
   • 使用来自已更改文件、增量规范、已完成任务和已阅读映射文件的最小可信证据集
   • 在有助于明确比较时，运行 node {{SKILL_DIR}}/scripts/spec-driven.js audit-spec-mapping-coverage <spec-path> [--implementation <repo-path> ...] [--tests <repo-path> ...]
   • 在有助于确认已审查的实现或测试文件是否缺失于所有主规范映射时，运行 node {{SKILL_DIR}}/scripts/spec-driven.js audit-unmapped-spec-evidence [--implementation <repo-path> ...] [--tests <repo-path> ...]
   • 将过时或具有误导性的映射至少列为 SHOULD FIX
   • 如果不匹配会实质性误导后续验证或归档准备工作，则升级为 MUST FIX
   • 如果未映射审计显示，此次审查变更的主要实现文件或直接验证该变更的测试文件未被纳入任何主规范映射，则将其视为 MUST FIX
   • 如果未映射审计仅发现审查范围之外或关联较弱的候选文件，则将其另列为 SHOULD FIX 或仓库遗留问题

9. 输出审查报告：

   MUST FIX（阻碍归档）：
     - [列表或“无”]
   
   SHOULD FIX（建议修复）：
    - [列表或“无”]
   
   NITS（可选）：
    - [列表或“无”]
   

10. Recommend next step:

    • If MUST FIX issues: address them before archiving
    • If only SHOULD FIX: ask user if they want to address them or proceed
    • If clean: suggest /spec-driven-archive <name>

Rules

• Read every changed file before commenting on it — never review code you haven't read
• Focus on real issues, not style preferences already handled by linters
• Review code based on evidence in the code and tests, never on authorship or assumed intent
• MUST FIX = security vulnerabilities, data loss risks, broken functionality
• SHOULD FIX = maintainability concerns, missing error handling, unclear logic
• NITS = naming suggestions, minor simplifications, documentation gaps
• Do not re-review code that was not changed by this change
• Respect config.yaml rules — violations of project rules are SHOULD FIX at minimum
• Report stale or misleading spec mappings when they would make future verification unreliable
• Specialized checklist findings use the same severity model as the baseline review: MUST FIX for archive blockers, SHOULD FIX for recommended fixes, and NITS for optional cleanup
• Never give self-authored or AI-authored code lighter treatment than human-authored code