AIエージェントが読めるエンジンにする

コーディングエージェントはコードを書くのは得意でも、あなたのコードを知ることは苦手です。独自ルールのある500以上のC++ファイルのリポジトリに放り込まれると、規約も、ファイルの場所も、変更がコンパイルできるかどうかも推測で動きます。その推測の一つひとつがレビューのコメントになります。

そこで私は、リポジトリそのものをエージェントのオンボーディング資料として扱っています。エージェントに必要なものはすべて、推測するものではなく調べられるもの、実行できるものにしています。

1. 短い入口

CLAUDE.mdはあえて短くしています。エンジンの説明はせず、ものを効率よく探す方法だけを書いています。

• まずdocs/CodeMap.mdを読む。全ファイルを1行ずつ、変更の種類ごとに触るファイルを記載。
• 次に、必要なドキュメントの該当箇所だけを開く。最初から最後まで読まない。
• 推測せずに検索する。未完成の作業にはTODO(assets)のタグ、各ドキュメントの最後には「既知の課題」。

加えて、エージェントが最も破りやすいルール、新しいシステムを必ず組み込むテストシーン、クラウドセッションからのチェック・ビルド・CI結果の確認方法も書いています。

2. ルールをスキルに、チェックリスト付きで

アーキテクチャ全体はhydro-engine-architectureスキルにまとめています。サブシステムのライフサイクルと命名、リソースの作り方、純粋なデータとしてのコンポーネント、レンダラーのルール、ゲームスクリプトの構成。最後に、作業を返す前に実行するチェックリストがあります。正はあくまでdocsフォルダで、食い違いがあればdocsが優先です。

3. すべてのルールをスクリプトで検査する

文章にしかないルールは、いずれ破られます。Hydroのルールは、エージェントが自分で実行するツールで強制しています。

• lint_conventions.py：独自スタイルの検査。すべてnamespace Hydroの中、!演算子の禁止、すべての本体に波括弧、m_PascalCaseのメンバー名、ゲームスクリプトの領域をまたぐincludeの禁止。
• validate_project.py：シーン、プレハブ、データファイルをコードと照合し、フィールド名の変更でシーンが黙って壊れないようにする。
• check.sh：g++の構文チェック、シェーダーのglslang、規約チェッカー、検証ツールを一度に実行。
• GitHub Actions：プッシュごとにWindowsでDebugとReleaseをビルドし、エージェントがgh run view --log-failedで取得できるエラー要約を出力。

4. ガードレール

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

5. 大きなモデルと小さなモデル

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

一番気に入っているのはこの分け方です。小さく閉じた修正はローカルで無料で実行し、設計に関わる作業はフルのコンテキストを持つ強いモデルに任せます。

何が変わったか

差分は小さくなり、自分が書くコードに近くなりました。レビューはスタイルではなく設計についての話になりました。どのチームにも当てはまる一番の学びは、エージェントにとって扱いやすいコードベースは、新しく入った人にとっても扱いやすいということです。コードマップ、検査できるルール、速いフィードバックは、誰にとっても役に立ちます。

HydroのCLAUDE.mdをGitHubで見る