AI エージェントチームでソフトウェアを作る — Core-Adapter のアプローチ
AI コーディングエージェントを真剣に使い始めると — 補完ではなく、タスクを取って成果物を作るアクターとして — 問いは「モデルがどれくらい良いか」から「モデルが役に立てるよう仕事をどう組織するか」へ移ります。私たちはこのための小さなフレームワークを作っており、何度も書き直す中で安定して残った構造が Core-Adapter の分離です。本稿はその記述です。
Core は小さく、滅多に変わりません。プロジェクトとは何か、ブループリントはどんな形か、「タスク」「記憶」「スキル」とは何か、エージェントがそれらの成果物をどう読み書きするか — それを定義する部分です。Core は機能の表面ではありません — 語彙と一連の規約です。Core が正しければ、Core を知っているエージェントは Core を使うどのプロジェクトでも動けます。
Adapter はそれ以外すべてで、変更が許されます。エディタとの統合、ファイルビューア、チームチャット、デプロイシステムとの統合。可視化やダッシュボード。チームが実際に作業している環境に Core を繋ぐ任意のプロトコル。Adapter は複数あってよく、Core はちょうど一つです。
Figure 01
Core と Adapter ── ふたつのリポジトリ、ひとつのチーム
Core リポジトリは言語・フレームワーク非依存のロジックを保持し、Adapter クローンは同じブランチの上にプラットフォーム固有の接着層を重ねる。
Core リポジトリ
agnosticAgent 定義
Skill ライブラリ
ブループリント仕様
メモリ層
Adapter クローン
Obsidian アダプター
vault パス · ノート IO
Adapter クローン
TeamUI アダプター
デスクトップ実行系 · IPC
Adapter クローン
CLI アダプター
シェル接着層 · パイプ
principle新しいプラットフォームが必要なら新しい Adapter を作る。Core を書き換える必要はない。エディタを差し替え、チャットツールを変え、デプロイ先を変えても、Core は動かない。
この分離が実務上なぜ重要か:Adapter の寿命は、それが適応するツールの寿命です。エディタは入れ替わる、ファイルブラウザは作り直される、チームチャットツールは買収される。そのどれも Core の変更を要求してはなりません。Core は Adapter より長生きでなければならず、それを現実的に可能にする唯一の方法は、Core を小さく、Core と Adapter の境界面をきれいに保つことです。
もう一つの軸 — フレームワーク自体に対する三層の視点 — でこの作業を律しています。第一層はメタ設計 — フレームワーク自体の設計。第二層はランタイム上のフレームワーク — フレームワークを使うプロジェクトが実際に持つファイルと規約。第三層は実プロジェクト — フレームワークで作られた具体的なアプリケーション、それ自身のブループリントとコードを持つもの。会話でこの層を混ぜるのが、議論を混乱させる最も信頼できる方法です。決定を下す前に、その決定がどの層のものかを必ずラベル付けします。
効いてくる小さなこと:成果物はプロジェクトローカルなファイルでなければならず、エージェントやサービスの内部状態であってはいけません。ブループリント、タスク、記憶、スキル定義 — すべてプロジェクトのリポジトリに置きます。バージョン管理され、差分が見え、レビューでき、個々のエージェントセッションを超えて生き残る。エージェントの仕事はそれらのファイルを読み、作業し、それ自身もファイルである変更を書き戻すこと。何かを覚えるために外部サービスが必要なら、脆いシステムを作ってしまっています。
Figure 02
TEAM OS v7 ── 九つの役割、三つの面
9 つの専門 AI 役が、計画 ─ 実装 ─ レビューの標準プロセス上で協働する。各役は独自のスキル、独自のメモリ層、明示的なハンドオフ契約を持つ。
PLAN
作業を整える
PM
プロジェクト管理
プロダクト
プロダクトオーナー
デザイン
ビジュアル + 対話
BUILD
実行する
フロントエンド
UI 実装
バックエンド
API + データ
DevOps
配備 + 監視
REVIEW
検証する
QA
挙動検証
レビュアー
コード + 計画レビュー
品質責任者
最終受け入れ
contracts各役は階層化メモリ(L1 タスク · L2 プロジェクト · L3 フレームワーク)から読む。ある役の出力は、次の役の入力契約になる。
出てきたパターン:プロジェクト管理の役割を一つ、専門の役割を複数。ただし全員が同じブループリントを読み、同じタスクトラッカーに書く。我々はオーケストレーター一人と、固定/オンデマンドの小さな役割集合(デザイナ、フロントエンド、バックエンド、レビュアー、セキュリティ、デバッガなど)を使います。別々のモデルではなく、同じ基盤モデルを異なるプロンプトと異なるツール権限で動かしているだけ。一貫性を与えるのはプロンプトではなく構造です。
スキルについて:それぞれのスキルを小さな契約として扱います。特定の条件で発火し、狭く定義された指示を持ち、他のスキルを呼べ、監査可能な出力を生む。スキルは人格よりも関数に近い。フレームワークに新しい能力を追加するときは、新しいエージェントでも巨大なプロンプトの新しい分岐でもなく、スキルを足します。これがフレームワークを保守しやすく推論しやすくしています。
検証について:エージェントの仕事はチェックできるときだけ有用です。前進させるループと同じくらい、間違いを捕まえるループに投資します。エージェントの各ステップは、人または他のエージェントがレビューできる成果物を生むか、さもなくば起きないかのどちらかです。沈黙のうちの状態変更は信用しないよう学びました — それらは数日かけて巻き戻すような問題に積み上がる癖があります。
Figure 03
D0 / D1 / D2 ── ドキュメントの三層
違う仕事は違う層を読む。D0 は原則(書く頻度は低く、読む頻度は高い)。D1 は設計(何かが決まった時に書く)。D2 は現状(常に書き直される)。
D0
原則
めったに変わらない
なぜそもそもこうやって作るのか。
e.g.ミッション、価値観、アーキテクチャ思想、命名規則
readers新規タスクに入る全てのエージェント
D1
設計
判断ごとに更新
特定の対象がどう動くべきか。
e.g.機能仕様、API 契約、スキーマ決定、ブループリント
readers実装者と監査者
D2
現状
常時書き直される
今この瞬間に現実に成り立っていること。
e.g.TODO、未解決バグ、エージェント受信箱、実行ログ
readers次のタスクを拾う者
エージェントが層を横断して読む手順
D0(タスク開始時に一度)→ 関連 D1 モジュール → D2(行動直前の最新スナップショット)
この構造から具体的に何を得るか:エージェントが進行中のプロジェクトに入って、わずかなターン数で役に立てるようになる(Core がすべての場所を定義しているから)。チームが Adapter を入れ替えられる — エディタ、チャットツール、デプロイ基盤を変えても Core もプロジェクト成果物も書き直さなくて済む。スキルは単独でテストできる。ブループリントは人間がプレーンテキストでレビューできる。フレームワークが巨大な一枚プロンプトだったら、これらの性質は一つも現れません。
まだ整理中のこと:エージェント間の不一致を、すべての決定を委員会化せずに扱う方法。プロジェクトが成熟するなかで記憶を正直に保つ方法。エージェントに自己組織化を許す場面と、レールに乗せておく場面の見分け方。どれもまだきれいな答えはありません。フレームワークは完成品ではなく動いている道具であり、本稿のノートもその精神で書かれています。