Claude Code Game Studios 中的 /code-review 技能：九阶段架构级代码审查工作流实战指南-育师

Claude Code Game Studios 中的 /code-review 技能：九阶段架构级代码审查工作流实战指南

【免费下载链接】Claude-Code-Game-StudiosTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.项目地址: https://gitcode.com/GitHub_Trending/cl/Claude-Code-Game-Studios

导读

/code-review是 Claude Code Game Studios（CCGS）为lead-programmer角色内置的架构级代码审查技能：它以九阶段流水线的方式，对指定文件或目录执行编码标准合规、ADR 架构决策合规、SOLID 原则、可测试性与游戏性能专项检查，并输出标准化的审查报告与三级裁决（APPROVED / APPROVED WITH SUGGESTIONS / CHANGES REQUIRED）。阅读本文后，你将掌握该技能每个阶段的执行逻辑、检查项的量化门槛、输出报告格式，以及它如何与/story-done、/architecture-decision等技能协作，把代码审查嵌入到“故事实现 → 完成验收”的研发闭环中。

技能概览：谁在何时使用 /code-review

/code-review定义在 .claude/skills/code-review/SKILL.md，其 frontmatter 声明了技能的关键契约：

元数据字段	值	含义
`name`	`code-review`	技能标识，对应命令`/code-review`
`description`	对指定文件/文件集执行架构与质量代码审查，检查编码标准合规、架构模式遵循、SOLID 原则、可测试性与性能隐患	触发时向模型说明职责
`argument-hint`	`[path-to-file-or-directory]`	参数为一个文件或目录路径
`user-invocable`	`true`	用户可显式调用
`allowed-tools`	Read, Glob, Grep, Bash, Task	只读工具 + Task（用于并行派生专家子代理）
`agent`	`lead-programmer`	该技能绑定给主程序（Lead Programmer）代理

该技能由 .claude/agents/lead-programmer.md 代理持有——该代理的skills字段声明为[code-review, architecture-decision, tech-debt]，其核心职责之一就是“Review all code for correctness, readability, performance, testability, and adherence to project coding standards”。技能内部自述“This skill is read-only — no files are written”，因此它天然是建议性（advisory）的审查工具，绝不修改源码。

在整个研发流程中的位置可对照 .claude/docs/review-workflow.md：代码变更需要相关部门主管代理审查，而/code-review正是这一原则在代码层面（而非设计、架构、跨域层面）的落地执行器。

Phase 1：加载目标文件与项目编码标准

审查的第一步不是看代码，而是先建立“审查基准”：

完整读取目标文件：把用户传入的文件（或目录下的文件）全文读入上下文；
读取CLAUDE.md获取项目编码标准：根目录的 CLAUDE.md 以及 .claude/docs/coding-standards.md 是项目编码标准的权威来源。

后者明确写入了与 Phase 4 直接呼应的六条硬性规则：

所有游戏代码必须在公共 API 上包含 doc comments；
每个系统必须在docs/architecture/下拥有对应的架构决策记录（ADR）；
玩法数值必须数据驱动（外部配置），严禁硬编码；
所有公共方法必须可单元测试（用依赖注入取代单例）；
提交必须引用相关的设计文档或任务 ID；
验证驱动开发：新增玩法系统先写测试，UI 变更用截图验证，任何实现都要有“能证明它工作”的证据。

Phase 2：定位引擎专家

CCGS 将“审查什么文件由谁来看”的策略集中存放在 .claude/docs/technical-preferences.md 的## Engine Specialists一节（由/setup-engine在配置引擎时写入）。/code-review在此读取四个角色：

Primary Specialist：负责架构与广泛引擎问题；
Language/Code Specialist：负责项目主语言文件；
Shader Specialist：负责着色器文件；
UI Specialist：负责 UI 代码。

若该节内容为[TO BE CONFIGURED]，说明项目尚未绑定引擎——此时技能会跳过引擎专家相关步骤，避免凭空捏造专家角色。该文件还提供了一张“文件扩展名 → 专家”路由表（File Extension Routing），当行为[TO BE CONFIGURED]时回退到 Primary Specialist；/code-review会在 Phase 7 依据这张表把不同类型的文件分发给不同的专家。

Phase 3：ADR 合规检查

架构决策记录（ADR）是 CCGS 约束代码演进的核心机制。本阶段在故事文件、提交信息和文件头注释中搜索ADR-NNN或docs/architecture/ADR-形式的引用：

若未发现任何 ADR 引用，记录“No ADR references found — skipping ADR compliance check.”；
对每个被引用的 ADR：读取文件，提取Decision与Consequences两节，然后对偏差做三级分类：

分类	严重级别	判定条件
ARCHITECTURAL VIOLATION	BLOCKING（阻断）	使用了 ADR 中明确拒绝的模式
ADR DRIFT	WARNING（警告）	与选定方案产生有意义的分歧，但未使用禁止模式
MINOR DEVIATION	INFO（提示）	与 ADR 指引的小差异，不影响整体架构

这一分类贯穿整个技能：ARCHITECTURAL VIOLATION 会直接进入 Phase 8 报告的Required Changes（必改项）与Verdict判定，并在 Phase 9 触发/architecture-decision来记录正确方案。

Phase 4：编码标准合规检查

技能首先判断目标代码所属的系统类别（engine、gameplay、AI、networking、UI、tools），然后逐项核验六条检查项：

公共方法与公共类具有 doc comments
每个方法的圈复杂度（Cyclomatic complexity）低于 10
方法长度不超过 40 行（不含数据声明）
依赖注入，游戏状态不使用静态单例
配置值从数据文件加载（不硬编码）
系统暴露接口（而非依赖具体类）

这六条与 .claude/docs/coding-standards.md 中“coding standards enforcement”的量化门槛完全一致（lead-programmer代理的 Coding Standards Enforcement 段落逐条列出相同指标），因此审查结果可直接落地为可执行的整改清单。Phase 8 输出中会以[X/6 passing]形式汇总，并列出带行号引用的失败项。

Phase 5：架构与 SOLID 检查

架构维度的检查聚焦系统间结构与依赖方向：

依赖方向正确（engine <- gameplay，不允许反向依赖）
模块之间无循环依赖
层次分离正确（UI 不拥有游戏状态）
跨系统通信使用事件/信号（events/signals）
与代码库既有模式保持一致

SOLID 维度逐条对照五原则：

单一职责（Single Responsibility）：每个类只有一个变更理由
开闭原则（Open/Closed）：可扩展而不需修改
里氏替换（Liskov Substitution）：子类型可替换基类型
接口隔离（Interface Segregation）：不出现臃肿接口
依赖倒置（Dependency Inversion）：依赖抽象而非具体实现

从源码结构可以推断，lead-programmer代理的职责定义（“Design the class hierarchy, module boundaries, interface contracts, and data flow for each system”“Ensure consistent use of design patterns”）正是本阶段审查标准的制定依据。

Phase 6：游戏专用关注点

区别于通用代码审查，本阶段针对游戏运行时特性提出五项检查：

帧率无关性（正确使用 delta time）
热路径（update loops）内无内存分配
空值/空状态的正确处理
需要处具备线程安全
资源清理（无泄漏）

这五项直接对应 .claude/docs/coding-standards.md 中“What NOT to Automate”与性能约束的思路：游戏性能问题（如每帧分配、泄漏）无法靠测试套件自动捕获，必须在审查阶段人工拦截。

Phase 7：并行专家审查（Specialist Reviews）

本阶段是技能的并行化核心：通过 Task 工具同时派生所有适用专家，不等待一个完成再启动下一个。

引擎专家分派（当引擎已配置时，按文件类型并行派生）：

主语言文件（.gd、.cs、.cpp）→ Language/Code Specialist
着色器文件（.gdshader、.hlsl、shader graph）→ Shader Specialist
UI 屏幕/控件代码 → UI Specialist
跨领域或不明确 → Primary Specialist
涉及引擎架构（场景结构、节点层级、生命周期钩子）的文件 → 同时派生 Primary Specialist

QA 可测试性审查：对 Logic（逻辑）与 Integration（集成）故事，除引擎专家外还要并行派生qa-tester，传入实现文件、故事的## QA Test Cases一节（qa-lead 预写的测试规格）与## Acceptance Criteria，评估五项：

测试钩子与接口是否全部暴露（而非藏在 private/internal 访问之后）
故事中的 QA 测试用例是否映射到可测试的代码路径
是否存在按当前实现无法测试的验收标准（如硬编码值、无注入接缝）
实现是否引入现有 QA 用例未覆盖的新边界情况
是否有应被测试覆盖却缺失的可观察副作用

对 Visual/Feel 与 UI 类故事，qa-tester 改为评估## QA Test Cases中的手工验证步骤在当前实现下是否真的可达（例如“手工检查器需要到达的状态是否真的能到达”）。所有专家结论汇总后，才进入输出阶段。

Phase 8：输出审查报告

技能定义了严格的报告模板（以下为原样保留的输出骨架）：

## Code Review: [File/System Name] ### Engine Specialist Findings: [N/A — no engine configured / CLEAN / ISSUES FOUND] [Findings from engine specialist(s), or "No engine configured." if skipped] ### Testability: [N/A — Visual/Feel or Config story / TESTABLE / GAPS / BLOCKING] [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] ### ADR Compliance: [NO ADRS FOUND / COMPLIANT / DRIFT / VIOLATION] [List each ADR checked, result, and any deviations with severity] ### Standards Compliance: [X/6 passing] [List failures with line references] ### Architecture: [CLEAN / MINOR ISSUES / VIOLATIONS FOUND] [List specific architectural concerns] ### SOLID: [COMPLIANT / ISSUES FOUND] [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]

值得注意的细节：

Positive Observations 是强制章节（“always include this section”），保证审查不只有批评；
ARCHITECTURAL VIOLATION 必定出现在 Required Changes 中，无论其他部分如何；
报告每一节都自带状态枚举，便于人与 Agent 机器化解析。

Phase 9：后续动作（Next Steps）

审查不是终点，而是工作流的流转节点：

若裁决为APPROVED：运行/story-done [story-path]关闭故事（见 .claude/skills/story-done/SKILL.md——该技能在 Phase 5 的LP-CODE-REVIEW关卡中正是以/code-review作为质量闸门：full模式派生lead-programmer审查并回传裁决，REJECT会阻断完成裁决）；
若裁决为CHANGES REQUIRED：修复问题后重新运行/code-review；
若发现ARCHITECTURAL VIOLATION：运行/architecture-decision记录正确方案（见 .claude/skills/architecture-decision/SKILL.md——该技能产出的 ADR 又会在未来的/code-reviewPhase 3 中被当作合规基准，形成“决策 → 实现 → 审查 → 再决策”的闭环）。

只读原则与流程定位

/code-review的只读性质由两层机制保证：

frontmatter 工具白名单：allowed-tools仅含 Read、Glob、Grep、Bash、Task，不含 Write/Edit；
技能自述：This skill is read-only — no files are written.

同时它不触发任何导演关卡（director gates）——审查结论是建议性的，不自动阻塞流程、不自动调用代理。这与.claude/docs/review-workflow.md中“代码变更需相关主管代理审查”的规则互补：审查由技能执行，关卡决策留给用户与导演代理。

质量保障：技能测试规范与验收

CCGS 为每个技能维护了可执行验证的测试规格，/code-review的规格位于 CCGS Skill Testing Framework/skills/analysis/code-review.md，由/skill-test static自动校验结构性断言：

frontmatter 必需字段齐全（name、description、argument-hint、user-invocable、allowed-tools）；
至少 2 个阶段标题；
包含裁决关键词 APPROVED / CONCERNS / NEEDS CHANGES（注意：测试规格中使用的裁决词是 APPROVED / CONCERNS / NEEDS CHANGES，而技能本体 Phase 8 模板的裁决为 APPROVED / APPROVED WITH SUGGESTIONS / CHANGES REQUIRED，二者同为“通过/附建议/需修改”的三级语义）；
不得包含“May I write”类写文件语言（只读技能）；
具有下一步交接指引。

规格还通过 5 个用例覆盖行为路径：

Happy Path：src/gameplay/health_component.gd全部达标（doc comments、构造器注入、数值引用assets/data/、文件头引用Status: Accepted的 ADR）→ 逐项 PASS、裁决 APPROVED、不改任何文件；
Needs Changes：src/ui/inventory_ui.gd缺 2 个公共方法 doc comments、使用GameManager.instance单例 → 以行号与方法名精确报告，裁决 NEEDS CHANGES，并建议改为依赖注入；
Architecture Risk：src/core/save_system.gd引用的adr-010-save.md状态为Proposed（未接受）→ 标记 ARCHITECTURE RISK，裁决 CONCERNS（建议性），并提示在代码进生产前解决 ADR；
Edge Case：目标路径src/networking/不存在 → 输出 “No source files found atsrc/networking/”，提示检查src/下有效目录，不崩溃、不产出裁决；
Gate Compliance：任何审查模式下都不调用导演关卡，仅在 CONCERNS 时建议（而非强制）“Consider requesting a Lead Programmer review for architecture concerns”。

覆盖说明（Coverage Notes）也如实标注了边界：目录批量审查未被显式测试（假定逐文件应用同一套检查并聚合裁决）；测试文件存在性检查属于/test-evidence-review的职责范畴。

结语：把代码审查变成可复现的流水线

/code-review的可贵之处在于把“资深程序员凭经验挑毛病”转化为九阶段、带量化阈值（圈复杂度 <10、方法 <40 行）、带三级偏差分类（BLOCKING / WARNING / INFO）、带并行专家分派与固定报告模板的可复现流水线。它不写代码、不设关卡，只产出证据充分的建议，并把手动决策权交还给用户——这让它既能嵌入/story-done的完成闸门，又能独立作为日常开发中的质量体检工具使用。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考