AIエージェント構築基盤をつくった — AIがチームで動き、自律で回る土台のテンプレート

書き直しの何が問題だったか

効率ではない。改善が1プロジェクトに閉じることだ。

「この禁止ルールは要る」「この書き方だと伝わらない」と学んでも、次のプロジェクトには載らない。学びが蓄積せず、毎回同じ失敗を踏み直す。プロジェクトが増えるほど、同じ改善を人数分・案件数分やり直すことになる。

基盤にすると、この関係が逆になる。1つのプロジェクトで得た学びが、次に立てるプロジェクトの初期状態になる。これが、基盤を作るいちばんの意義だと思っている。立ち上げが速くなるのは副産物。

もう1つの狙い ── 議論しなくてよいことを増やす

「指示ファイルは何行までにするか」「危険操作はどこで止めるか」「いつ人に確認を取るか」。

これらは本来、プロジェクトごとに考え直す話ではない。一度決めて、基盤に置いて、以後は議論しない。議論しなくてよいことを増やすほど、本題に使える時間が増える。

基盤とは、判断の置き場所でもある。

全体像

基盤は、共通の骨格とドメインごとの役割の2段になっている。

拡大

ドメインは、開発・ビジネス・PM・アイディエーションの4つ。それぞれに個人版とチーム版がある。新しいプロジェクトを立てるときは、骨格と、選んだドメインの役割を重ねて展開するだけ。

変わるのは役割、変わらないのは骨格。 ここを分けなかった時期があって、骨格を直すたびに全ドメインに手を入れることになった。

骨格が持っている3つのもの

1. 記憶の置き場所

日次ログ・意思決定記録・学び・タスクの4つ。役割は「セッションが切れても仕事が続く」ようにすること。

大事なのは、これを人が指示しなくても書かせること。「区切りでログを書いて」と毎回頼むなら、頼むコストのほうが高い。いつ書くかをあらかじめ決めて、基盤側に持たせる。さらにセッション開始時に現況を自動で読み込ませ、「読んでから始めてください」ではなく読んだ状態で始まるようにした。

2. できることと、できないことの固定

動く前に止めるもの（危険なコマンドのブロック）と、動いた後に気づかせるもの（指示ファイルが太りすぎていないか）。

役割は、判断をモデルに委ねない領域を決めること。「本番環境を消してよいか」は、その場の判断に任せる種類の問いではない。心がけではなく仕組みで止める。

3. 終わりの条件を、先に契約にする

複数セッションにまたがる仕事のために、対話でゴールを検証可能な契約に落としてから回す。契約には「何が満たされたら完了か」を、実行して合否が出る形で書く。

役割は、「終わったかどうか」を人が毎回見張らなくてよくすること。判断材料は自己申告ではなく実行結果になる。

AI人格を配る、という考え方

チーム版のテンプレートには、役割ごとのAI人格が入っている。開発なら、まとめ役・フロント担当・バックエンド担当・テスト担当。ビジネスなら、戦略・市場調査・財務モデル・GTM。

これらはプロジェクトに展開されたあと、その現場の文脈を吸ってそれぞれ育つ。骨格は同じでも、育ち方はプロジェクトごとに違う。基盤が配るのは初期人格であって、完成品ではない。

なぜ1体ではなく、チームなのか

この基盤でいちばん考えたところ。理由が4つある。

1. コンテキストは有限で、しかも汚れる。1体に全部やらせると、設計の議論も実装の試行錯誤も失敗ログも同じ場所に積み上がり、後半になるほど最初に決めたことが埋もれる。役割を分けると、それぞれが独立したコンテキストを持つので、この汚染が起きない。

2. 生成した本人は、自分の成果物を正しく評価できない。同じセッションで「レビューして」と頼むと、自分が書いた理由をそのまま正当化する方向に働く。だから検証役は別に立てて、成果物と満たすべき条件だけを渡すようにした。生成の経緯は渡さない。何をどう頑張ったかを知らない相手に見せたときに残るものが、実際に残っているもの。

3. 並列にできる仕事とできない仕事があり、線引きは事前にしか引けない。読み取り中心の調査は並列にできる。書き込みは、担当を分けられる場合だけ。この判断を毎回その場でやると事故る。誰に何を渡すかの基準を先に決めておくのがワークフローの役割。自分でやるか、別の役に渡すか、別モデルに渡すかの基準も基盤側に置いている。

4. チームを組むこと自体にコストがある。ここも正直に書いておく。役割を分ければ分けるほどよいわけではない。全員への一斉連絡はコストが人数分だけ増えるし、独立したコンテキストを持つということは共有されていない前提が増えるということでもある。分ける粒度は、並列にできる単位と一致させるのが結局いちばん素直だった。

自律で回るとは、どういう状態か

「AIが勝手に働く」という絵ではない。実際に動いているのは、決めておいた条件のあいだだけ、人の確認を挟まずに進むという状態。

境界は1つに決めてある。計画は承認、実行は自律。 何をやるかは人が承認し、そのあとの手順は任せる。ただし破壊的な操作と外部への公開だけは、実行の途中でも確認を取る。

この境界があるおかげで、「勝手にやられて元に戻せなくなる」という一番怖い形にはならない。自律の範囲を広げるより、境界をはっきりさせるほうが先だった。

実際にこの基盤で回っているプロジェクト

ソフトウェア開発ではない例を1つ出す。能登の風景を映像で記録して公開する事業でも、同じ骨格が動いている。

こちらに立っているAI人格は 9体。ソフトウェア開発とは似ても似つかない役割ばかり。

拡大

共通しているのは骨格のほう。ゴールを検証可能な契約にしてから回す仕組み、敵対的に反証する役、停止判定を自己申告に委ねない仕組み — このあたりは、テンプレートが配る開発向けの構成でも、映像制作の現場でも同じもの。

役割は全部違う。骨格は全部同じ。ここまで領域が離れていても骨格が持つというのが、基盤という形にした一番の手応えだった。

そして、この構成には明示的な禁止事項が書いてある。専門の9体はプロジェクト側に置き、基盤側にコピーを作らない。二重管理になり、実行環境によって挙動が食い違うから。

「変わるのは役割、変わらないのは骨格」は、標語ではなく運用ルールとして書かれていないと守られない。

何が変わったか

数字で測ってはいないので、感触として書く。

• 翌日の立ち上がりが変わった。 前回何をしていたか思い出す時間がなくなった
• 同じ議論を繰り返さなくなった。 一度決めたことが基盤にあるので、次のプロジェクトで蒸し返さない
• レビューが機能するようになった。 別の役に、経緯抜きで渡すようにしてから
• 危ない操作で肝が冷える回数が減った。 止められるほうが、止められずに実行されるよりよい

1. 「参照はあるのに実体がない」という壊れ方をした

各プロジェクトの指示ファイルが参照しているコマンドやAI人格の実体が、基盤ではなく手元のグローバル設定にしかなかった時期があった。自分の環境では動くのに、展開した先では参照が空を指す。

基盤自体を検証するスクリプトが失敗を返し続けていたので気づけたが、無ければ配った先で静かに壊れていたはず。（余談として、グローバルの .gitignore が基盤側の設定ディレクトリまで無視していて、ファイルがコミット漏れしていたのも同じ調査で見つかった。）

→ 手元で動くことは、配布物が動くことの証拠にならない。基盤を作るなら、基盤自体を検証する仕組みがセットで要る。

2. 骨格と役割を分けていなかった

いまは「変わるのは役割、変わらないのは骨格」と書いたが、最初からそうだったわけではない。ドメインごとに骨格まで持たせていた時期があり、ガードレールを1つ直すたびに全ドメインに同じ変更を入れていた。

入れ忘れが1つ出れば、あるドメインだけ古いルールで動いている状態が生まれる。しかも、そうなったことに気づく手段がなかった。

→ 共通のものを共通の場所に置くのは、効率のためではなく整合性のため。分散すると、ズレたことに気づけない。

3. 配ったあとの更新は、まだ手作業が残っている

進行中の課題。基盤から展開したプロジェクトは、展開時点のコピーを持つ。

再配布の仕組み自体はある。プロジェクトを指定して配布物を組み直すスクリプトがあり、事前検証もかけられる。問題はその先。実行環境によっては、一度取り込んだものが静的にキャッシュされ、元を直しても反映されない。更新には組み直しと取り込み直しの両方が要る。

つまり「配る仕組み」はあるのに、「配ったものが古くなったことに気づく仕組み」がない。いまは人が覚えているだけ。

→ 配って終わりではない。テンプレートを配る仕組みを作ると、次に「配ったものを更新する仕組み」が要るようになり、その次に「古いまま動いていることを検知する仕組み」が要るようになる。

基盤を丸ごと真似する必要はない。いちばん小さく始められるのはコンテキスト層だ。

日次ログと意思決定記録の2つを置いて、「作業の区切りで前者、判断したら後者」とだけ決める。ファイル2つとルール1行で、次のセッションの立ち上がりが変わる。

役割を分けるのは、1体で回らなくなってからで十分。ただし例外が1つあって、検証役だけは早めに分けたほうがいいと思っている。生成した本人に自分の成果物を評価させないのは、規模に関係なく効く。1人で作業していても、役割は分けられる。

基盤という形にするかどうかの分かれ目は、プロジェクトが2つ目に入るとき。1つしかないうちは、そのプロジェクトの中に書けばいい。2つ目を立てるときに「前と同じことを書いている」と感じたら、そこが切り出しどき。

そして、どの層でも共通して効いた原則を1つだけ挙げるなら、これになる。

守らせたいことは、指示ではなく仕組みにする。 「150行以内に保つこと」と書いておくのと、超えたら警告が出るようにするのとでは、結果が違った。基盤とは、その仕組みを置いておく場所のことだ。