はじめに
Godotで開発を進める中で、Claude CodeなどのAIコーディングエージェントと連携する場合、コードの品質をどう担保するかは重要な課題です。
- パス間違いや参照エラー
- コードスタイルの不統一
- AIが生成したコードがコンパイルエラー
こうした問題を解決するため、いくつかのツールを使ってコードの品質チェックを自動化する仕組みを紹介します。
本記事で紹介および検証を行なっているツール、ライブラリのバージョンは次の通りです。
- Godot Engine v4.4.1.stable.official
バージョンによっては挙動に差異がある場合もありますので、ご了承ください。
使用するツール
1. gdtoolkit (GDScript Toolkit)
gdtoolkitは、GDScriptの静的解析やフォーマットを行うためのPython製ツールスイートです。以下のコマンドでインストールします。
pip install gdtoolkit
gdtoolkitの以下の2つのツールを使用します。
- gdformat: GDScriptのフォーマッター。コードのスタイル（インデント、スペース等）を補正します。
- gdlint: GDScript用の静的解析ツール。未使用変数や命名規則違反など、潜在的なバグや規約違反を検出します。
2. Godot コマンドラインツール
godot --headless --editor --quit-after 1コマンドを使用します。プロジェクト全体のスクリプトをコンパイルし、preloadのパス間違いや型エラーといった、GDScriptの文法エラーを検出します。--quit-after 1自体は起動時の初期化を終えて1フレーム後に落としてるだけです。これでコンパイルなどは実行されるので、その結果を利用します。
スクリプト単体でならgodot --headless --check-only --script hogehoge.gd --quitでもいいんですが、複数の依存関係込みでのテストだと--editor --quit-after 1が良いっぽいです。（違ったら指摘してください）
Makefileの作成
これらのツールを毎回手で実行するのは手間なので、Makefileを使って一連の処理をコマンド一つにまとめます。
プロジェクトのルートに、以下の内容でMakefileファイルを作成します。
# Makefile
# 1. フォーマットをチェックする
format-check:
gdformat --check .
# 2. フォーマットを自動で整形する
format:
gdformat .
# 3. 静的解析を実行する
lint:
gdlint .
# 4. Godotエンジンでコンパイルチェックする
compile-check:
godot --headless --editor --quit-after 1
# --- 統合コマンド ---
# フォーマットと静的解析をまとめて実行
validate: format-check lint
# 全てのチェックをまとめて実行
full-validate: format-check lint compile-check
.PHONY: format-check format lint compile-check validate full-validate
これにより、ターミナルで make full-validate と呼び出し、すべてのチェックが行われるようになります。
Claude Codeのカスタムコマンドとして定義
.claude/commandsなどにmd形式でコードチェックや、エラーが出た時に適切に対応することを指示し、カスタムコマンドひとつ実行するだけでClaude Codeに実行させるようにします。 サンプルはこんな感じです。
# コード検証プロトコル ## 概要 gdtoolkitとGodot headlessモードを使用したGDScriptファイルの完全なコード品質・コンパイル検証 ## 実行手順 ### 1. フォーマットチェック make format-check フォーマットエラーがある場合: make format ### 2. 静的解析 make lint ### 3. コンパイル検証 make compile-check ### 4. 統合検証 make validate # フォーマット + 静的解析のみ make full-validate # フォーマット + 静的解析 + コンパイル検証 ## エラー解決プロトコル ### フォーマットエラー - `make format`で自動修正 - 意図しない変更の確認 - フォーマット後のコードを個別コミット ### Linterエラー 表面的な修正ではなく、適切な設計改善による解決が必須 #### 命名規則エラー - セマンティックな明確性の見直し - ドメイン言語に従った命名の確保 - 関連ドキュメントの更新 #### スタイル違反 - 違反が設計問題を示唆していないか検討 - より良いコード構造への リファクタリング - 既存コードベースとの一貫性維持 #### 複雑度警告 - 複雑な関数の分割 - 単一責任原則に従ったメソッド抽出 - 設計パターンの改善検討 ### コンパイルエラー 実際のGodotエンジンによるコンパイル検証で検出されるエラー #### 参照エラー - enum値のリネーム時の参照更新漏れ - クラス名変更時の参照整合性 - メソッド名変更時の呼び出し箇所の更新 #### 型エラー - 型の不整合 - 未定義変数の参照 - メソッドシグネチャの不一致 #### リソースエラー - 存在しないリソースファイルの参照 - バージョン不整合によるリソース読み込み失敗 - シーンファイルの依存関係エラー ## 実行義務 - コード変更後の必須実行 - コミット前の必須通過 - コードレビュー前の完全パス必須 ## 失敗時の対応 検証失敗時: 1. 根本原因の分析 2. 適切な設計解決の適用 3. 検証の再実行（`make full-validate`） 4. 全チェック通過まで反復 適切な設計原則を迂回するクイックフィックスの適用禁止
実行するとこんな感じで実行されます。
Claude Codeに使わせたい
手動で使うのもいいですが、どうせならコードを更新したらClaude Codeに使ってほしいです。
プロジェクトに .claude/commands/code-validate.md のようなAIへの指示ファイルを用意し、「コードを変更したら、必ずこのコマンドで検証すること」というルールを定義しておきます。
## コード検証プロトコル
コードを変更した後は、必ず @.claude/commands/code-validate.md のコマンドに従い、品質チェックを厳守してください。
エラーが出た場合は、その場しのぎの修正ではなく、設計を見直して根本的な解決を図ってください。
こうすることで、ルールを忘れない限りは実装を終えた後にコードの検証を行なってくれます。 Gitのprecommitに仕込んでおくのもありだと思います。
#!/bin/sh
# Pre-commit hook for merchant project
echo "=== Pre-commit Code Validation ==="
if make validate; then
echo "Code validation passed"
exit 0
else
echo "Code validation failed"
echo "Please fix the issues and try again"
echo "Run 'make validate' to see detailed errors"
exit 1
fi
まとめ
GDScriptのlinterやコマンドラインツールを使ったコード検証を行うことで、品質のベースラインを保つための強力なガードレールとなります。
この仕組みにさらにgdUnit4などの単体テストによるテスト検証を組み合わせるのも良さそうです。
