AIワークフローとエージェント用ハーネス

なぜハーネスが必要か

大きなリポジトリに放り込まれたエージェントは推測で動きます。規約も、ファイルの場所も、変更がビルドできるかどうかも。ハーネスは、その推測を「読めるもの」と「実行できるもの」に置き換えます。結果として差分は小さくなり、レビューの往復が減り、エージェントは定型コードだけでなく、エンジンやゲームプレイの実際の作業をこなせるようになります。

構成要素（Hydroの例）

プロジェクトの指示書

短いCLAUDE.mdで、ものの探し方を伝えます（まず1ファイル1行のコードマップ、次に必要なドキュメントの該当箇所だけ）。加えて、最も破られやすいルール、新しいシステムを必ず組み込むテストシーン、クラウドセッションからのチェック・ビルド・パッケージ・CI結果の確認方法も書いています。

設計スキル

hydro-engine-architectureスキルには、サブシステムのライフサイクルと命名、リソースの作り方、ECSとシステム、レンダラーのルール、ゲームスクリプトの構成、そして作業完了前のチェックリストがまとまっています。同じ内容をClaudeとQwenで共有しています。

エージェントが自分で実行するチェック

• エンジン独自のルール（名前空間、!演算子の禁止、波括弧、メンバー名、ゲームスクリプトの領域をまたぐincludeの禁止）を検査するPython製の規約チェッカー
• シーン、プレハブ、データファイルをコードと照合するプロジェクト検証ツール
• g++の構文チェック、シェーダーのglslang、規約チェッカー、検証ツールをまとめて実行するcheck.sh
• データ定義とシリアライザーのヘッドレステスト
• プッシュごとにWindowsでDebugとReleaseをビルドし、エージェントが取得できるエラー要約を出すGitHub Actions

ガードレール

• 明示的な許可なしにコミットやプッシュをしない。複数ステップの作業はCIで確認できるよう作業用ブランチへ
• 編集はクラウドのクローンだけでなく、更新日時を確認したうえで手元の作業コピーに反映
• ドキュメントを正とし、変更と一緒に更新。スクリプトでWikiに同期

ローカルモデル

すべての作業に最先端のモデルが必要なわけではありません。ローカルのOllamaモデルで動くQwen Code向けに、小さなコンテキストに収まる軽量版のハーネスを作りました。C++ファイルを開いたときだけ読み込まれる短い規約ファイルと、「小さな変更」の範囲を明確に定義し、それを超える作業はフル版のスキルかClaudeに任せるhydro-quick-editスキルです。

スタジオでの取り組み

Gamebasicsでも同じ考え方を、チームのUnityコードベースに持ち込んでいます。共通フレームワークや運営中のゲームでエージェントが作業できるよう、必要なコンテキスト、規約、チェックを備えたAIハーネスを構築しています。コードは非公開のため、内容の説明のみとなります。

エージェントとの働き方

• 指示は一度読んで終わりの長文ではなく、調べられるもの・実行できるものとして書く
• すべてのルールをスクリプトで検査できるようにし、CIで強制する。スタジオでJenkinsとTeamCityのパイプラインが全タイトルを守っているのと同じように
• エージェントの作業は一度でレビューできる大きさに保つ
• 機能は変更専用のデモではなく、実際のシーンやゲームで証明する

HydroのCLAUDE.mdをGitHubで見る