Claude Codeや複数AIの連携で開発を自動化・規律化する実装知見

AIエージェントを開発・運用に組み込む際、エージェントの自律的な判断を制御し、ハルシネーションを防ぐ仕組みが求められています。本記事では、Claude CodeのフックやCLAUDE.mdを活用した規律設計、実行結果の再取得を強制する「完了契約」の実装方法を紹介します。さらに、複数AIの連携によるゲーム自動生成パイプラインや、Dockerコンテナ内での環境構築手順など、実践的な知見を整理します。

CLAUDE.mdによるAIの自律的な行動抑制

CLAUDE.mdに「いつ発火するか」という具体的な状況と行動指針を記述することで、AIエージェントが勝手な推測を拒否して人間の判断を仰ぐよう制御できます。例えば、リポジトリ直下に置かれたCLAUDE.mdに「状態について述べるときは、実測するか本人に確認してから発話する」といった規約を記述します。これにより、AIが「go」という2文字の入力だけで作業日誌の不在を検出し、推測で進めずに選択肢を提示して停止する挙動が実測されています。

AIエージェントの運用において、CLAUDE.mdは強制的な設定ではなく文脈として読み込まれるため、記述方法に工夫が必要です。「正確に作業する」といった抽象的な指示ではなく、「Use 2-space indentation」のように対象と合図を指定することが推奨されます。また、誰が使っても同じ「規律」と、個人の稼働記録などの「記録」を別リポジトリに分割して管理することで、不要な情報の流出を防ぎつつAIの自律的な判断を制御できます。

出典: clone しただけのマシンで、AI が「推測で埋めること」を自分から拒否した——AI駆動開発を .md で規律づける

完了契約によるやったつもり幻覚の防止

副作用を伴うタスクの後に別コマンドで状態を再取得する「完了契約」を導入することで、AIエージェントによる虚偽の完了報告を物理的に防ぐことができます。AIエージェントは、ツールの戻り値が空やエラーであっても「成功しただろう」という最尤の続きを生成し、「完了しました」と報告するハルシネーションを起こすことがあります。これを防ぐため、作成・更新・削除などの操作後は、必ず別コマンドで実在や状態を再取得して確認できた値のみを報告させます。

この完了契約は、システムプロンプトやCLAUDE.mdに「副作用のある操作は別コマンドで状態を再取得し、生の結果を提示してから完了と報告せよ」という一段落を加えるだけで、コストゼロで実装可能です。さらに、この規律をコードで強制する仕組みとして、実状態を再取得する関数のみを受け取るライブラリ「@hyuga/genchi」や、Claude CodeのStopフックで未検証の完了をブロックするアダプタが公開されています。

出典: 「完了しました」を信じるな。AIエージェントに実結果の再取得を強制する検証ゲート

Claude Codeフックの動作制御の非対称性

Claude Codeのフック機能において、終了コード2を返した際の「拒否」の挙動は、イベントの種類によって完全にブロックされるか無視されるか非対称に分かれます。バージョン 2.1.218 での実測によると、ユーザー発言直後に走る「UserPromptSubmit」で終了コード2を返すと、モデル呼び出し前に処理が完全ブロックされ、課金も発生しません。一方で、セッション開始時に走る「SessionStart」で同じ終了コード2を返しても、拒否は無視されてセッションが通常通り進行します。

一方で、フックからAIへ追加のコンテキストを渡す「additionalContext」機能は、SessionStartとUserPromptSubmitの双方で正常に動作し、任意の検証用文字列を応答に反映させることができます。また、claude -pをパイプ無しで呼ぶと3秒の待ちが発生する警告は、標準入力を明示的に閉じる「< /dev/null」を付けることで回避可能です。フックを設計する際は、イベントごとの特性を本物のセッションで確認することが推奨されます。

出典: Claude Codeのフックにexit 2を返したら、片方は完全ブロック・もう片方は黙って無視されていた

3つのAIとAWSを連携したゲーム自動生成

Gemini、Codex、Claudeの3つのAIをコンペティション形式で連携させ、Playwrightによる実プレイテストを含むパイプラインを構築することで、ブラウザゲームの完全自動生成が可能です。このシステムでは、毎日13時に手元のMacでcronが起動し、TASK.mdに記載された10段階のフェーズをClaude Codeが非対話モードで実行します。3つのAIがゲーム案を提案して相互投票を行い、採用された案をPhaser.jsで実装し、Playwrightで60秒間の実プレイテストを行って品質を担保します。

開発コストを抑えるため、重い処理を行う「生成側（手元のMac）」と、配信や課金を行う「配信側（AWSサーバーレス）」を完全に分離する設計が採用されています。配信側はnpm依存ゼロのLambda 1本とCloudFront、DynamoDBで構成され、ゲーム本体は署名Cookieで保護されています。また、UA判定とJavaScript実行ベースの2層でbotと人間を分離計測することで、正確なアクセス解析とインフラコストの最適化を両立しています。

出典: Claude・Gemini・Codexを毎日コンペさせてPhaser.jsゲームを39日間・92本自動生成しているパイプラインの全構成

Dockerコンテナ内での設定永続化手順

Dockerコンテナ内でClaude Codeを実行する際、設定ファイルとセッションが保存されるディレクトリをホスト側とマウントすることで、コンテナ削除後も設定を維持できます。具体的には、ホームディレクトリ配下の「/.claude.json」と「/.claude」の2つのパスを、docker-compose.ymlのvolume設定でホスト側とバインドマウントします。これにより、セキュリティなどの理由でプライベートPCに直接インストールせず、コンテナ内で実行する場合でも利便性を損ないません。

ただし、コンテナ起動前に「~/.claude.json」が存在しない状態でマウントすると、ファイルではなくディレクトリとして解釈される問題が発生します。これを防ぐため、初回はマウント設定をコメントアウトしてコンテナを起動し、コンテナ内に自動生成された「.claude.json」をホスト側にコピーします。その後にコメントアウトを解除して再起動するという手順を踏むことで、設定やセッションを維持したままコンテナ内のターミナルでclaudeコマンドが使用可能になります。

出典: Dockerコンテナ内でClaude Codeを動かす方法（コンテナを削除しても設定は維持）

この日の動きをどう見るか

AIエージェントを用いた開発・運用においては、AIの自律的な判断に任せきりにするのではなく、CLAUDE.mdや完了契約、フック機能などの「規律」を仕組みとして強制する流れが強まっています。テキスト出力の検証にとどまらず、実行後の世界の状態を再取得して突き合わせるなど、実態に基づいた検証ゲートを設けることが、ハルシネーションを防ぐ鍵となります。

また、手元のローカル環境で重い生成処理やテストを実行し、クラウド側は軽量なサーバーレス構成で配信と計測に徹するという、コスト効率を重視したアーキテクチャ設計も有効です。複数のAIモデルの特性を活かしたコンペティションや、厳格なフック制御を組み合わせることで、一人での開発・運用であっても高い品質と安全性を維持した自動化パイプラインが実現可能になります。