Back to Details

spec-driven-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
You are reviewing the code quality of a completed spec-driven change.
你需要评审一项已完成的基于规范驱动（spec-driven）的变更的代码质量。

Prerequisites

前提条件

The 
.spec-driven/
directory must exist at the project root. Before proceeding, verify:
ls .spec-driven/
If this fails, the project is not initialized. Run 
/spec-driven-init
first.
项目根目录下必须存在 
.spec-driven/
目录。开始前，请执行以下命令验证：
ls .spec-driven/
如果命令执行失败，说明项目未初始化，请先运行 
/spec-driven-init
。

Steps

评审步骤

  1. Select the change — run 
    node {{SKILL_DIR}}/scripts/spec-driven.js modify
    to list active changes. Ask which change to review. If already specified, use it.
  2. Confirm readiness — run:
    node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>
    If 
    remaining > 0
    , stop — the change is not ready for review. Suggest 
    /spec-driven-apply
    first.
  3. Load context — read:
    • .spec-driven/changes/<name>/proposal.md
      — scope and unchanged behavior
    • .spec-driven/changes/<name>/design.md
      — approach and decisions
    • .spec-driven/changes/<name>/tasks.md
      — what was implemented
    • .spec-driven/config.yaml
      — project context and rules (including 
      test
      rules and any 
      fileMatch
      entries)
  4. Identify changed files — from the completed tasks, determine which files were created or modified. Read each file fully.
  5. Review code quality — for each changed file, check:
    • Readability: clear naming, reasonable function length, no unnecessary complexity
    • Security: no injection vulnerabilities, no hardcoded secrets, proper input validation at system boundaries
    • Error handling: appropriate error handling for external calls and user input; no swallowed errors
    • Performance: no obvious N+1 queries, unnecessary allocations, or blocking calls in async contexts
    • Best practices: follows the project's conventions (from config.yaml context), no dead code, no debug artifacts left behind
  6. Check test quality — read the test files associated with this change:
    • Do tests cover the key scenarios from the delta specs?
    • Are tests independent and repeatable?
    • Do tests follow 
      rules.test
      from config.yaml?
  7. Output a review report:
    MUST FIX (blocks archive):
  - [list or "none"]

SHOULD FIX (recommended):
  - [list or "none"]

NITS (optional):
  - [list or "none"]
  8. 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>
  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>/design.md
      — 变更实现方案及决策依据
    • .spec-driven/changes/<name>/tasks.md
      — 已完成的实现任务
    • .spec-driven/config.yaml
      — 项目上下文及规则（包括 
      test
      规则和所有 
      fileMatch
      条目）
  4. 识别变更文件 — 根据已完成的任务清单，确定哪些文件是新增或修改的。完整读取每个变更文件。
  5. 评审代码质量 — 针对每个变更文件，检查以下维度：
    • 可读性：命名清晰、函数长度合理、无不必要的复杂逻辑
    • 安全性：无注入漏洞、无硬编码密钥、在系统边界处有恰当的输入验证
    • 错误处理：对外部调用和用户输入有合适的错误处理；无被隐藏的错误
    • 性能：无明显的N+1查询、不必要的内存分配，或在异步上下文里的阻塞调用
    • 最佳实践：遵循项目约定（来自config.yaml的上下文）、无死代码、无残留的调试代码
  6. 检查测试质量 — 读取与该变更相关的测试文件：
    • 测试是否覆盖了增量规范中的核心场景？
    • 测试是否独立且可重复执行？
    • 测试是否遵循了config.yaml中的 
      rules.test
      规则？
  7. 输出评审报告：
    必须修复（阻止归档）：
  - [问题列表或“无”]

建议修复（推荐）：
  - [问题列表或“无”]

细微优化（可选）：
  - [问题列表或“无”]
  8. 推荐后续步骤：
    • 若存在“必须修复”的问题：建议在归档前修复所有问题
    • 若仅存在“建议修复”的问题：询问用户是否要修复后再归档，或直接进行归档
    • 若评审无问题：建议执行 
      /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
  • 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
  • 在发表评论前必须读完所有变更文件 — 绝不评审未读过的代码
  • 聚焦实际问题，不要纠结于已由代码检查工具（linters）处理的风格偏好
  • 必须修复 = 安全漏洞、数据丢失风险、功能损坏
  • 建议修复 = 可维护性问题、缺失的错误处理、逻辑不清晰
  • 细微优化 = 命名建议、小幅度简化、文档缺口
  • 不要评审本次变更未涉及的代码
  • 遵守config.yaml中的规则 — 违反项目规则至少属于“建议修复”级别