Claude-Code-Game-Studios 提交前代码质量门禁pre-commit-code-quality Hook 实战指南【免费下载链接】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导读本文深入剖析 Claude-Code-Game-StudiosCCGS仓库中.claude/docs/hooks-reference/pre-commit-code-quality.md定义的提交前代码质量检查 Hook它会在任何修改src/目录文件的提交执行前运行用于拦截风格违规、缺失文档注释、过度复杂的方法以及本应数据化的硬编码数值。读完本文你将掌握该 Hook 的完整 Bash 实现、如何按引擎Godot / Unity / Unreal与语言适配检查项、如何通过.claude/settings.json接入 Claude Code 的 PreToolUse 事件以及 Hook 失败时如何联动lead-programmer、gameplay-programmer、qa-tester等 Agent 自动修复。Hook 的设计定位代码进入版本库前的最后一道防线在 CCGS 的多 Agent 协作体系里代码质量不是靠事后 review 兜底而是靠“进入版本控制之前”的自动化门禁来强制。该 Hook 的设计意图Purpose非常明确在执行git commit之前用脚本化的检查捕获四类典型问题风格违规style violations——不符合项目编码规范的写法缺失文档missing documentation——公共 API 没有注释、提交未关联设计文档过度复杂的方法overly complex methods——难以阅读和维护的代码结构硬编码数值hardcoded values——本应通过数据文件配置的玩法数值直接写死在代码里。触发条件Trigger是任何修改src/目录下文件的提交。这与同目录下的姊妹 Hook 形成分工pre-commit-design-check.md在修改design/或assets/data/的提交前校验设计文档必需章节与 JSON 数据合法性pre-push-test-gate.md在 push 到develop/main等受保护分支前执行构建、单元测试、集成测试与性能回归检查本 Hookpre-commit-code-quality守住src/代码本身的静态质量底线。三个 Hook 一前一后构成“提交级静态检查 → 推送级动态验证”的质量防线这与 .claude/docs/hooks-reference.md 中列出的整个 Hook 家族validate-commit.sh、validate-push.sh、validate-assets.sh等的设计哲学一致自动化门禁尽量前置问题越早发现修复成本越低。完整实现脚本与逐段拆解文档给出的参考实现是一份可直接放入.git/hooks/pre-commit或通过 Git Hook 管理器托管的 Bash 脚本。其核心逻辑分四步筛选变更文件 → 逐文件静态检查 → 运行测试 → 汇总退出码。第一步只处理暂存区中属于src/的文件CODE_FILES$(git diff --cached --name-only --diff-filterACM | grep -E ^src/) EXIT_CODE0git diff --cached只读取已暂存staged的改动不会因为工作区里未 add 的草稿代码误触发检查--diff-filterACM只关心Added新增、Copied复制、Modified修改三类文件删除D和重命名R不参与内容检查grep -E ^src/把检查范围收敛到源码目录避免对美术资源、配置、文档等文件误报。对照仓库中实际部署的 .claude/hooks/validate-commit.sh它同样采用git diff --cached --name-only获取暂存清单再按路径前缀^design/gdd/、^assets/data/.*\.json$、^src/gameplay/、^src/分别分发到不同的检查逻辑两者在“基于暂存区 路径过滤”这一策略上完全一致。第二步对每个变更文件做三类静态检查if [ -n $CODE_FILES ]; then for file in $CODE_FILES; do # 检查 1游戏玩法代码中的硬编码魔法数字 if [[ $file src/gameplay/* ]]; then if grep -nE (damage|health|speed|rate|chance|cost|duration)[[:space:]]*[:][[:space:]]*[0-9] $file; then echo WARNING: $file may contain hardcoded gameplay values. Use data files. # Warning only, not blocking fi fi # 检查 2无属主的 TODO/FIXME 注释 if grep -nE (TODO|FIXME|HACK)[^(] $file; then echo WARNING: $file has TODO/FIXME without owner tag. Use TODO(name) format. fi # 检查 3语言专用 Linter按引擎取消注释 # For GDScript: gdlint $file || EXIT_CODE1 # For C#: dotnet format --check $file || EXIT_CODE1 # For C: clang-format --dry-run -Werror $file || EXIT_CODE1 done逐条解读硬编码玩法数值检查正则(damage|health|speed|rate|chance|cost|duration)[[:space:]]*[:][[:space:]]*[0-9]匹配诸如damage 25、health: 100、cost: 50这类“关键词紧跟数字”的模式。这是对 .claude/rules/gameplay-code.md 中铁律“ALL gameplay values MUST come from external config/data files, NEVER hardcoded”的机器化落地——该规则文件给出的反例正是var damage: float 25.0 # VIOLATION: hardcoded gameplay value而正确写法是var damage: float config.get_value(combat, base_damage, 10.0)。注意文档特意将其设计为WARNING仅警告、不阻断因为正则无法区分真正的平衡数值与边界值常量粗暴拦截会误伤合法代码无属主 TODO 检查正则(TODO|FIXME|HACK)[^(]匹配后面没有紧跟左括号的待办注释即要求所有 TODO 必须写成TODO(name)格式——把责任归属写进注释避免“永远待办”的悬空标记。同样只警告不阻断语言专用 Linter文档为 CCGS 支持的三种技术栈分别预留了命令——GDScript 用gdlint、C# 用dotnet format --check、C 用clang-format --dry-run -Werror。这部分才是真正可能阻断提交EXIT_CODE1的硬门禁。CCGS 根目录 CLAUDE.md 的 Technology Stack 声明引擎可在 Godot 4 / Unity / Unreal Engine 5 中选型语言对应 GDScript / C# / C / Blueprint因此“按选型取消注释对应 linter”是接入前必做的适配动作。第三步为被修改的系统运行单元测试# 运行被修改系统的单元测试 # Uncomment and adapt for your test framework # python -m pytest tests/unit/ -x --quiet || EXIT_CODE1 fi exit $EXIT_CODE测试门禁是默认关闭、注释保留的需要项目落地时取消注释并替换为实际测试框架。仓库在 .claude/docs/coding-standards.md 中给出了配套的测试规范可供对齐测试命名文件用[system]_[feature]_test.[ext]函数用test_[scenario]_[expected]确定性测试必须每次运行结果一致禁止随机种子与时间相关断言隔离性每个测试自建自毁状态不依赖执行顺序独立性单元测试不得调用外部 API、数据库或文件 I/O使用依赖注入引擎 CI 命令参考Godot 用godot --headless --script tests/gdunit4_runner.gdUnity 用game-ci/unity-test-runnerv4Unreal 用带-nullrhi的无头 runner。仓库实测validate-commit.sh 如何把“文档示例”工程化.claude/docs/hooks-reference/pre-commit-code-quality.md提供的是通用参考实现而仓库中真正通过 .claude/settings.jsonPreToolUse→Bashmatcher →validate-commit.sh超时 15 秒挂载到 Claude Code 的是工程化版本 .claude/hooks/validate-commit.sh。对照阅读可以清晰看到从“参考脚本”到“生产脚本”的演进能力参考脚本本文档生产脚本validate-commit.sh输入方式直接依赖git diff --cached通过 stdin 接收 PreToolUse JSON用jq回退grep解析tool_input.command先判断是否为git commit命令再放行退出码语义EXIT_CODE1表示失败遵循 Claude Code Hook 约定0 允许、2 阻止stderr 展示给 Claude其余退出码视为错误但工具继续执行见 hook-input-schemas.md 的 Exit Code Reference 表检查范围仅src/代码扩展为设计文档章节design/gdd/需含 Overview、Player Fantasy、Detailed、Formulas、Edge Cases、Dependencies、Tuning Knobs、Acceptance Criteria 八个小节见 validate-commit.sh、assets/data/JSON 合法性用python -m json.tool校验非法 JSON 直接exit 2阻断L46-L69、src/gameplay/硬编码数值L73-L82、全src/的 TODO 格式L84-L94硬编码检查结果仅 echo 警告汇总到WARNINGS变量统一以 Commit Validation Warnings 区块输出到 stderr仍不阻断提交保留“警告不阻塞”的保守策略跨平台未提及显式使用grep -EPOSIX 扩展而非grep -PPerl兼容 Windows 环境路径比较前用sed s|\\|/|g归一化反斜杠特别值得注意的是生产脚本把硬编码玩法数值的正则完全复刻了参考文档中的模式(damage|health|speed|rate|chance|cost|duration)[[:space:]]*[:][[:space:]]*[0-9]证明本文档是该 Hook 家族的直接设计来源同时生产脚本给 JSON 校验加上了“找不到 python 时降级为警告”的容错分支避免 CI 环境缺依赖导致假阳性阻断。接入方式如何让 Hook 在 Claude Code 中自动触发参考脚本可以按传统方式放置为 Git 原生 pre-commit Hook# 将脚本保存为仓库 .git/hooks/pre-commit 并赋予执行权限 # 或用 husky、pre-commit 等 Hook 管理器统一托管而在 CCGS 中更推荐的是 Claude Code 的PreToolUse机制它在 Claude 尝试执行git commit命令之前就介入与 Claude 的 Agent 生态天然打通。配置位置在 .claude/settings.jsonPreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: bash .claude/hooks/validate-commit.sh, timeout: 15 }, { type: command, command: bash .claude/hooks/validate-push.sh, timeout: 10 } ] } ]Hook 收到的 stdin 负载格式hook-input-schemas.md大致如下{ tool_name: Bash, tool_input: { command: git commit -m feat: add player health system, description: Commit changes with message, timeout: 120000 } }脚本用INPUT$(cat)捕获整段 JSON 后jq -r .tool_input.command // empty提取待执行命令若命令不以git commit开头则直接exit 0放行只有真正的提交才进入检查逻辑——这与 settings.json 中Bash(git commit*)类权限白名单见 .claude/settings.json的粒度控制思想一脉相承。Agent 集成Hook 失败后的自动修复分工参考文档为“Hook 失败后谁来解决”给出了明确的 Agent 路由表这正是 CCGS 把静态检查与 49 个专业 Agent 联动起来的精髓Hook 失败类型处置动作对应 Agent风格违规用格式化器自动修复或交由架构与代码负责人处理自动格式化 /lead-programmer见 .claude/agents/lead-programmer.md硬编码玩法数值把数值外置到数据文件gameplay-programmer见 .claude/agents/gameplay-programmer.md测试失败先定位失败测试再修复实现qa-tester诊断见 .claude/agents/qa-tester.mdgameplay-programmer修复这套分工与gameplay-programmerAgent 的职责定义高度吻合——其 Key Responsibilities 明确写着“Data-Driven Design: All gameplay values must come from external configuration files, never hardcoded. Designers must be able to tune without touching code.”.claude/agents/gameplay-programmer.md与 Hook 的硬编码检查形成“规则发现 → Agent 修复”的闭环。同理.claude/rules/gameplay-code.md 提供的正反例数据驱动 vs 硬编码可以直接作为gameplay-programmer重构时的判定标准。当 Hook 失败发生在 Claude Code 会话中时Hook 的 stderr 会作为上下文回传给 ClaudeClaude 可以据此自动发起上述 Agent 修复流程若按传统 Git Hook 方式部署则输出直接打印在终端供人工或 CI 读取。适配清单接入前需要决策的五个问题综合参考文档与仓库实现将一个通用 pre-commit 质量检查落地到具体项目时建议按以下清单决策语言与 linter 选型GDScript 用gdlintC# 用dotnet format --checkC 用clang-format --dry-run -Werror未选定的引擎对应的注释行保持注释状态阻断 vs 警告策略参考实现与生产实现都把硬编码数值、TODO 归属标记设为仅警告防止正则误报阻断开发而 JSON 非法、linter 失败设为阻断接入时应延续这一“可恢复问题警告、确定性错误阻断”的分级策略测试命令的本地化按 coding-standards.md 的 CI/CD 规则替换pytest示例并决定是“只测被修改系统”还是全量回归跨平台兼容Windows 环境避免grep -P路径用sed s|\\|/|g归一化——这些坑在 hook-input-schemas.md 的 Notes 中都有明确提示与上层门禁的衔接本 Hook 只覆盖src/的静态质量设计文档与数据文件由 pre-commit-design-check.md 守护构建与集成测试由 pre-push-test-gate.md 在 push 阶段兜底三者叠加才构成完整质量闭环。延伸阅读.claude/docs/hooks-reference.mdCCGS 全部 11 个 Hook 的触发事件与行为总览.claude/docs/hooks-reference/hook-input-schemas.mdHook 的 JSON 输入输出 Schema 与退出码约定.claude/hooks/validate-commit.sh本 Hook 的工程化生产实现.claude/docs/coding-standards.mdHook 所捍卫的编码、设计与测试标准.claude/rules/gameplay-code.md硬编码数值检查背后的 gameplay 铁律.claude/agents/gameplay-programmer.md负责修复硬编码与测试失败的 Agent.claude/settings.jsonHook 在 Claude Code 中的实际挂载配置.claude/docs/hooks-reference/pre-commit-design-check.md 与 .claude/docs/hooks-reference/pre-push-test-gate.md配套的提交/推送质量门禁【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考