はじめに

Godotで開発を進める中で、Claude CodeなどのAIコーディングエージェントと連携する場合、コードの品質をどう担保するかは重要な課題です。

パス間違いや参照エラー
コードスタイルの不統一
AIが生成したコードがコンパイルエラー

こうした問題を解決するため、いくつかのツールを使ってコードの品質チェックを自動化する仕組みを紹介します。

本記事で紹介および検証を行なっているツール、ライブラリのバージョンは次の通りです。

Godot Engine v4.4.1.stable.official

バージョンによっては挙動に差異がある場合もありますので、ご了承ください。

使用するツール

1. gdtoolkit (GDScript Toolkit)

github.com

gdtoolkitは、GDScriptの静的解析やフォーマットを行うためのPython製ツールスイートです。以下のコマンドでインストールします。

pip install gdtoolkit

gdtoolkitの以下の2つのツールを使用します。

gdformat: GDScriptのフォーマッター。コードのスタイル（インデント、スペース等）を補正します。
gdlint: GDScript用の静的解析ツール。未使用変数や命名規則違反など、潜在的なバグや規約違反を検出します。

2. Godot コマンドラインツール

docs.godotengine.org

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