AI エージェントチームでソフトウェアを作る — Core-Adapter のアプローチ

AI コーディングエージェントを真剣に使い始めると — 補完ではなく、タスクを取って成果物を作るアクターとして — 問いは「モデルがどれくらい良いか」から「モデルが役に立てるよう仕事をどう組織するか」へ移ります。私たちはこのための小さなフレームワークを作っており、何度も書き直す中で安定して残った構造が Core-Adapter の分離です。本稿はその記述です。

Core は小さく、滅多に変わりません。プロジェクトとは何か、ブループリントはどんな形か、「タスク」「記憶」「スキル」とは何か、エージェントがそれらの成果物をどう読み書きするか — それを定義する部分です。Core は機能の表面ではありません — 語彙と一連の規約です。Core が正しければ、Core を知っているエージェントは Core を使うどのプロジェクトでも動けます。

Adapter はそれ以外すべてで、変更が許されます。エディタとの統合、ファイルビューア、チームチャット、デプロイシステムとの統合。可視化やダッシュボード。チームが実際に作業している環境に Core を繋ぐ任意のプロトコル。Adapter は複数あってよく、Core はちょうど一つです。

この分離が実務上なぜ重要か：Adapter の寿命は、それが適応するツールの寿命です。エディタは入れ替わる、ファイルブラウザは作り直される、チームチャットツールは買収される。そのどれも Core の変更を要求してはなりません。Core は Adapter より長生きでなければならず、それを現実的に可能にする唯一の方法は、Core を小さく、Core と Adapter の境界面をきれいに保つことです。

もう一つの軸 — フレームワーク自体に対する三層の視点 — でこの作業を律しています。第一層はメタ設計 — フレームワーク自体の設計。第二層はランタイム上のフレームワーク — フレームワークを使うプロジェクトが実際に持つファイルと規約。第三層は実プロジェクト — フレームワークで作られた具体的なアプリケーション、それ自身のブループリントとコードを持つもの。会話でこの層を混ぜるのが、議論を混乱させる最も信頼できる方法です。決定を下す前に、その決定がどの層のものかを必ずラベル付けします。

効いてくる小さなこと：成果物はプロジェクトローカルなファイルでなければならず、エージェントやサービスの内部状態であってはいけません。ブループリント、タスク、記憶、スキル定義 — すべてプロジェクトのリポジトリに置きます。バージョン管理され、差分が見え、レビューでき、個々のエージェントセッションを超えて生き残る。エージェントの仕事はそれらのファイルを読み、作業し、それ自身もファイルである変更を書き戻すこと。何かを覚えるために外部サービスが必要なら、脆いシステムを作ってしまっています。

出てきたパターン：プロジェクト管理の役割を一つ、専門の役割を複数。ただし全員が同じブループリントを読み、同じタスクトラッカーに書く。我々はオーケストレーター一人と、固定/オンデマンドの小さな役割集合（デザイナ、フロントエンド、バックエンド、レビュアー、セキュリティ、デバッガなど）を使います。別々のモデルではなく、同じ基盤モデルを異なるプロンプトと異なるツール権限で動かしているだけ。一貫性を与えるのはプロンプトではなく構造です。

スキルについて：それぞれのスキルを小さな契約として扱います。特定の条件で発火し、狭く定義された指示を持ち、他のスキルを呼べ、監査可能な出力を生む。スキルは人格よりも関数に近い。フレームワークに新しい能力を追加するときは、新しいエージェントでも巨大なプロンプトの新しい分岐でもなく、スキルを足します。これがフレームワークを保守しやすく推論しやすくしています。

検証について：エージェントの仕事はチェックできるときだけ有用です。前進させるループと同じくらい、間違いを捕まえるループに投資します。エージェントの各ステップは、人または他のエージェントがレビューできる成果物を生むか、さもなくば起きないかのどちらかです。沈黙のうちの状態変更は信用しないよう学びました — それらは数日かけて巻き戻すような問題に積み上がる癖があります。

この構造から具体的に何を得るか：エージェントが進行中のプロジェクトに入って、わずかなターン数で役に立てるようになる（Core がすべての場所を定義しているから）。チームが Adapter を入れ替えられる — エディタ、チャットツール、デプロイ基盤を変えても Core もプロジェクト成果物も書き直さなくて済む。スキルは単独でテストできる。ブループリントは人間がプレーンテキストでレビューできる。フレームワークが巨大な一枚プロンプトだったら、これらの性質は一つも現れません。

まだ整理中のこと：エージェント間の不一致を、すべての決定を委員会化せずに扱う方法。プロジェクトが成熟するなかで記憶を正直に保つ方法。エージェントに自己組織化を許す場面と、レールに乗せておく場面の見分け方。どれもまだきれいな答えはありません。フレームワークは完成品ではなく動いている道具であり、本稿のノートもその精神で書かれています。