Back to Details

code-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Phase 1: Load Target Files

阶段1：加载目标文件

Read the target file(s) in full. Read CLAUDE.md for project coding standards.
完整读取目标文件。读取CLAUDE.md以了解项目编码规范。

Phase 2: Identify Engine Specialists

阶段2：确定引擎专家

Read 
.claude/docs/technical-preferences.md
, section 
## Engine Specialists
. Note:
  • The Primary specialist (used for architecture and broad engine concerns)
  • The Language/Code Specialist (used when reviewing the project's primary language files)
  • The Shader Specialist (used when reviewing shader files)
  • The UI Specialist (used when reviewing UI code)
If the section reads 
[TO BE CONFIGURED]
, no engine is pinned — skip engine specialist steps.
读取
.claude/docs/technical-preferences.md
中的
## Engine Specialists
部分，记录：
  • Primary（主专家）：负责架构与广泛引擎相关问题
  • Language/Code Specialist（语言/代码专家）：负责评审项目主语言文件
  • Shader Specialist（着色器专家）：负责评审着色器文件
  • UI Specialist（UI专家）：负责评审UI代码
若该部分内容为
[TO BE CONFIGURED]
，则未绑定引擎，跳过引擎专家相关步骤。

Phase 3: ADR Compliance Check

阶段3：ADR合规性检查

Argument: 
/code-review [file(s)]
may optionally include a story file path as the last argument (e.g., 
/code-review src/combat/attack.gd production/epics/combat/story-001.md
). If a story path is provided, read it to extract the governing ADR reference.
Search for ADR references in, in priority order:
  1. The story file (if provided as argument)
  2. Header comments at the top of the implementation files
  3. Commit messages referencing these files (
    git log --oneline -- [file]
    )
Look for patterns like 
ADR-NNN
or 
docs/architecture/ADR-
.
If no ADR references found, note: "No ADR references found — ADR compliance check skipped. For full ADR compliance review, provide the story path: 
/code-review [files] [story-path]
."
For each referenced ADR: read the file, extract the Decision and Consequences sections, then classify any deviation:
  • ARCHITECTURAL VIOLATION (BLOCKING): Uses a pattern explicitly rejected in the ADR
  • ADR DRIFT (WARNING): Meaningfully diverges from the chosen approach without using a forbidden pattern
  • MINOR DEVIATION (INFO): Small difference from ADR guidance that doesn't affect overall architecture
参数说明：
/code-review [file(s)]
可选择性地在最后添加一个故事文件路径作为参数（例如：
/code-review src/combat/attack.gd production/epics/combat/story-001.md
）。若提供了故事路径，需读取该文件以提取对应的ADR引用。
按以下优先级搜索ADR引用：
  1. 故事文件（若作为参数提供）
  2. 实现文件顶部的头部注释
  3. 引用这些文件的提交信息（
    git log --oneline -- [file]
    ）
查找类似
ADR-NNN
或
docs/architecture/ADR-
的格式。
若未找到ADR引用，需记录："未找到ADR引用 — 跳过ADR合规性检查。如需完整的ADR合规性评审，请提供故事路径：
/code-review [files] [story-path]
。"
对于每个找到的ADR引用：读取文件，提取**Decision（决策）和Consequences（影响）**部分，然后对偏差进行分类：
  • ARCHITECTURAL VIOLATION（架构违规，阻塞性）：使用了ADR中明确禁止的模式
  • ADR DRIFT（ADR偏离，警告）：与选定方案存在实质性差异，但未使用被禁止的模式
  • MINOR DEVIATION（轻微偏差，提示）：与ADR指导存在微小差异，但不影响整体架构

Phase 4: Standards Compliance

阶段4：规范合规性

Identify the system category (engine, gameplay, AI, networking, UI, tools) and evaluate:
  • Public methods and classes have doc comments
  • Cyclomatic complexity under 10 per method
  • No method exceeds 40 lines (excluding data declarations)
  • Dependencies are injected (no static singletons for game state)
  • Configuration values loaded from data files
  • Systems expose interfaces (not concrete class dependencies)
确定系统类别（引擎、游戏玩法、AI、网络、UI、工具）并评估：
  • 公共方法和类包含文档注释
  • 每个方法的圈复杂度低于10
  • 方法代码不超过40行（不包含数据声明）
  • 依赖采用注入方式（游戏状态不使用静态单例）
  • 配置值从数据文件加载
  • 系统暴露接口（而非具体类依赖）

Phase 5: Architecture and SOLID

阶段5：架构与SOLID原则

Architecture:
  • Correct dependency direction (engine <- gameplay, not reverse)
  • No circular dependencies between modules
  • Proper layer separation (UI does not own game state)
  • Events/signals used for cross-system communication
  • Consistent with established patterns in the codebase
SOLID:
  • Single Responsibility: Each class has one reason to change
  • Open/Closed: Extendable without modification
  • Liskov Substitution: Subtypes substitutable for base types
  • Interface Segregation: No fat interfaces
  • Dependency Inversion: Depends on abstractions, not concretions
架构：
  • 依赖方向正确（引擎 <- 游戏玩法，而非反向）
  • 模块间无循环依赖
  • 层级分离合理（UI不持有游戏状态）
  • 跨系统通信使用事件/信号
  • 与代码库中已确立的模式保持一致
SOLID原则：
  • 单一职责：每个类只有一个变更理由
  • 开闭原则：可扩展但无需修改原有代码
  • 里氏替换：子类型可替代基类型
  • 接口隔离：无臃肿接口
  • 依赖倒置：依赖抽象而非具体实现

Phase 6: Game-Specific Concerns

阶段6：游戏特定关注点

  • Frame-rate independence (delta time usage)
  • No allocations in hot paths (update loops)
  • Proper null/empty state handling
  • Thread safety where required
  • Resource cleanup (no leaks)
  • 帧率无关性（使用delta time）
  • 热路径（更新循环）中无内存分配
  • 正确处理空/空状态
  • 必要时保证线程安全
  • 资源清理（无内存泄漏）

Phase 7: Specialist Reviews (Parallel)

阶段7：专家评审（并行）

Spawn all applicable specialists simultaneously via Task — do not wait for one before starting the next.
通过Task同时启动所有适用的专家评审任务 — 无需等待前一个任务完成再启动下一个。

Engine Specialists

引擎专家

If an engine is configured, determine which specialist applies to each file and spawn in parallel:
  • Primary language files (
    .gd
    , 
    .cs
    , 
    .cpp
    ) → Language/Code Specialist
  • Shader files (
    .gdshader
    , 
    .hlsl
    , shader graph) → Shader Specialist
  • UI screen/widget code → UI Specialist
  • Cross-cutting or unclear → Primary Specialist
Also spawn the Primary Specialist for any file touching engine architecture (scene structure, node hierarchy, lifecycle hooks).
若已配置引擎，确定每个文件对应的专家并并行启动：
  • 主语言文件（
    .gd
    , 
    .cs
    , 
    .cpp
    ）→ 语言/代码专家
  • 着色器文件（
    .gdshader
    , 
    .hlsl
    , 着色器图）→ 着色器专家
  • UI界面/组件代码 → UI专家
  • 跨领域或不明确的文件 → 主专家
此外，任何涉及引擎架构（场景结构、节点层级、生命周期钩子）的文件，都需启动主专家评审。

QA Testability Review

QA可测试性评审

For Logic and Integration stories, also spawn 
qa-tester
via Task in parallel with the engine specialists. Pass:
  • The implementation files being reviewed
  • The story's 
    ## QA Test Cases
    section (the pre-written test specs from qa-lead)
  • The story's 
    ## Acceptance Criteria
Ask the qa-tester to evaluate:
  • Are all test hooks and interfaces exposed (not hidden behind private/internal access)?
  • Do the QA test cases from the story's 
    ## QA Test Cases
    section map to testable code paths?
  • Are any acceptance criteria untestable as implemented (e.g., hardcoded values, no seam for injection)?
  • Does the implementation introduce any new edge cases not covered by the existing QA test cases?
  • Are there any observable side effects that should have a test but don't?
For Visual/Feel and UI stories: qa-tester reviews whether the manual verification steps in 
## QA Test Cases
are achievable with the implementation as written — e.g., "is the state the manual checker needs to reach actually reachable?"
Collect all specialist findings before producing output.
对于逻辑与集成类故事，需在启动引擎专家评审的同时，通过Task并行启动
qa-tester
任务，并传递以下内容：
  • 待评审的实现文件
  • 故事中的
    ## QA Test Cases
    部分（来自qa-lead的预编写测试规范）
  • 故事中的
    ## Acceptance Criteria
    （验收标准）
要求qa-tester评估：
  • 是否暴露了所有测试钩子和接口（未隐藏在私有/内部访问权限后）？
  • 故事
    ## QA Test Cases
    中的测试用例是否对应可测试的代码路径？
  • 是否存在实现后无法测试的验收标准（例如硬编码值、无注入点）？
  • 实现是否引入了现有QA测试用例未覆盖的新边缘情况？
  • 是否存在应编写测试但未编写的可观察副作用？
对于视觉/体验类和UI类故事：qa-tester需评审
## QA Test Cases
中的手动验证步骤是否可通过当前实现完成 — 例如：“手动检查人员需要到达的状态是否确实可达？”
在生成输出前收集所有专家的评审结果。

Phase 8: Output Review

阶段8：输出评审结果

undefined
undefined

Code Review: [File/System Name]

代码评审：[文件/系统名称]

Engine Specialist Findings: [N/A — no engine configured / CLEAN / ISSUES FOUND]

引擎专家评审结果：[N/A — 未配置引擎 / 无问题 / 发现问题]

[Findings from engine specialist(s), or "No engine configured." if skipped]
[引擎专家的评审结果，若跳过则显示“未配置引擎”]

Testability: [N/A — Visual/Feel or Config story / TESTABLE / GAPS / BLOCKING]

可测试性：[N/A — 视觉/体验或配置类故事 / 可测试 / 存在缺口 / 阻塞性]

[qa-tester findings: test hooks, coverage gaps, untestable paths, new edge cases] [If BLOCKING: implementation must expose [X] before tests in ## QA Test Cases can run]
[qa-tester的评审结果：测试钩子、覆盖缺口、不可测试路径、新边缘情况] [若为阻塞性：实现必须暴露[X]才能运行## QA Test Cases中的测试]

ADR Compliance: [NO ADRS FOUND / COMPLIANT / DRIFT / VIOLATION]

ADR合规性：[未找到ADR / 合规 / 偏离 / 违规]

[List each ADR checked, result, and any deviations with severity]
[列出每个检查的ADR、结果以及任何带有严重程度的偏差]

Standards Compliance: [X/6 passing]

规范合规性：[X/6 通过]

[List failures with line references]
[列出失败项及行号引用]

Architecture: [CLEAN / MINOR ISSUES / VIOLATIONS FOUND]

架构：[无问题 / 轻微问题 / 发现违规]

[List specific architectural concerns]
[列出具体的架构问题]

SOLID: [COMPLIANT / ISSUES FOUND]

SOLID原则：[合规 / 发现问题]

[List specific violations]
[列出具体的违规项]

Game-Specific Concerns

游戏特定关注点

[List game development specific issues]
[列出游戏开发相关的具体问题]

Positive Observations

正面评价

[What is done well -- always include this section]
[做得好的地方 — 此部分必须包含]

Required Changes

必须修改项

[Must-fix items before approval — ARCHITECTURAL VIOLATIONs always appear here]
[批准前必须修复的问题 — 架构违规项必须出现在此部分]

Suggestions

建议

[Nice-to-have improvements]
[锦上添花的改进建议]

Verdict: [APPROVED / APPROVED WITH SUGGESTIONS / CHANGES REQUIRED]

评审结论：[批准 / 附带建议批准 / 需要修改]


This skill is read-only — no files are written.

---

该技能为只读模式 — 不会写入任何文件。

---

Phase 9: Next Steps

阶段9：后续步骤

Use 
AskUserQuestion
:
  • Prompt: "Code review complete — verdict: [APPROVED / CHANGES REQUIRED / MAJOR REVISION]. How would you like to proceed?"
  • Options (adjust based on verdict):
    • If APPROVED: 
      • [A] Run /story-done to mark the story complete
      • [B] Stop here
    • If CHANGES REQUIRED or MAJOR REVISION: 
      • [A] Fix the issues and re-run /code-review
      • [B] Run /story-done anyway with noted exceptions
      • [C] Stop here
If an ARCHITECTURAL VIOLATION is found:
  • If the violation contradicts an existing ADR: fix the implementation to comply with 
    docs/architecture/[adr-file].md
    . If the design has legitimately changed, run 
    /architecture-decision
    to formally revise the existing ADR — do not create a competing one.
  • If no ADR exists for the pattern that was violated: run 
    /architecture-decision
    to document the correct approach before fixing the code.
调用
AskUserQuestion
：
  • 提示语：“代码评审完成 — 结论：[批准 / 需要修改 / 重大修订]。您希望如何继续？”
  • 选项（根据结论调整）：
    • 若为批准： 
      • [A] 运行/story-done标记故事完成
      • [B] 到此为止
    • 若为需要修改或重大修订： 
      • [A] 修复问题后重新运行/code-review
      • [B] 忽略已记录的例外情况，直接运行/story-done
      • [C] 到此为止
若发现架构违规：
  • 若违规与现有ADR冲突：修改实现以符合
    docs/architecture/[adr-file].md
    。若设计确实已变更，运行
    /architecture-decision
    正式修订现有ADR — 请勿创建与之冲突的新ADR。
  • 若违规模式无对应ADR：在修复代码前，运行
    /architecture-decision
    记录正确的实现方案。