ゼロから新しいプロジェクトを始めるとき、AIコーディングは純粋な魔法のように感じられます。プロンプトを入力すれば、モデルはためらうことなくクリーンなコンポーネントや動作するバックエンドのエンドポイントを生成します。
しかし、コードベースが大きくなるにつれ、厳しい現実が訪れます。
およそ10万行のコードあたりで、一般的なAIははっきりと息切れし始めます。推測を試み、リポジトリを手探りで検索し、存在しない関数をハルシネーションで作り出します。およそ30万行あたりでは、モデルの自律的な判断はほぼ崩壊します。コンテキストウィンドウでは足りず、プロジェクト全体への従来のgrepは数千トークンを消費し、開発は壊れたコードの修正を延々と繰り返す循環に変わります。
まさにここで、システムのコントラクトが主導権を握ります。
AITMにおけるコントラクトとは?
コントラクトは、通常のインラインコメントでも、2スプリント後には成り立たなくなる忘れられたREADME.mdの一行でもありません。
それは機械で照会できるシステムの動作です。
アプリケーションの特定の部分が何をすべきかを正確に記述し、該当するソースファイル、テスト、UI要素を指し示します。エージェントは手探りで何十ものファイルを読む代わりに、システムに直接こう尋ねます。「この動作はどこで、どのように実装されていますか?」 すると、すぐに正確な答えが返ってきます。
AITMのすべてのコントラクトは、3つの重要な柱の上に成り立っています。
- behavior: コードが何をするかを一行で表した本質。すべてのフィールドの中で最も重要です。エージェントはこのルールをファイル内の実際の実装と照合します。矛盾があれば、システムはそれがバグか古くなったコントラクトのどちらかだとすぐに分かります。
- confidence: 情報の信頼性を示す指標。その記述が、システム内の他のデータと比べてどれだけ信頼できるかを示します(たとえば、動作が実際のテストで検証済みかどうか)。
- variables: システム共通のコミュニケーション言語(例:
BL.PIPELINE)への接続。フロントエンドとバックエンドのビジネスロジックをつなぐ橋として機能し、UIやデータ層の特定の部分でコントラクトを瞬時に絞り込めます。
本番環境からの実例
AITMでは、コントラクトは構造化されており、GraphQL APIからすぐに取得できます。
contractsForFile(path: "src/pipeline/MergeQueueService.ts", projectId: "ctm-dashboard") {
id # "GM-057"
module # "Git/Merge"
behavior # "セルフマージ後の再起動は手動です。マージ後、ユーザーがメニューでRestartをクリックするか、Settings.selfMergeRestartModeが'auto'になるまで、dev-watchはマージ前のコードを配信し続けます。"
confidence # "tested"
}
これが静的なドキュメントとの決定的な違いです。エージェントは、コードを1行も開いたり書いたりする前に、コントラクトを要求します。手探りで動くことなく、コンテキストを無駄にせず、そのルールにどれだけの重みを置くべきかを正確に把握しています。
トークンと計算時間を節約: Low〜MediumのeffortのClaude Sonnet
コントラクトによる的確な誘導の最大の利点の一つは、AIモデル自体の効率です。
AITMでは、エージェントはLowからMediumのeffort(thinking)設定のClaude Sonnetで動作します。モデルが正確なコントラクトを手にしていれば、何分も「考える」必要も、リポジトリ全体のアーキテクチャについて推測する必要も、ささいな調査に巨大なreasoning予算を費やす必要もありません。
コントラクトのおかげで、モデルは完成した地図を手にします。
- どのファイルに行くべきかを正確に把握している。
- 期待される動作(
behavior)を知っている。 - 情報をどれだけ信頼できるか(
confidence)を知っている。
そのため、effortが低くても、Claude Sonnetは完全に決定的でクリーンな仕事をこなします。自分の「推測」に頼る必要がなく、与えられた仕様に厳密に従うからです。
50万行のコードでの結果
このアプローチの真価は、プロジェクトの最初の数日ではなく、コードベースがエンタープライズ規模に成長したときに現れます。
50万行を超える私たち自身のシステムでは、現在約3,500件のコントラクトが安定して稼働しています。
- 手探りのgrepは終わり: エージェントは何百ものファイルを検索せず、確実な場所へ直行します。
- トークンとハルシネーションの大幅な削減: コンテキストウィンドウはクリーンなままで、モデルは情報過多に悩まされません。
- 一貫した結果: 50万行のプロジェクトでも、AIは空のリポジトリでの最初のプロンプトと同じ速度と精度を実現します。