reeschan.pink/now/efee4488-8f6a-4bd6-b810-4a444a00a133

2026-10-12-ai-orchestration

最近は「AI に書かせる」から一歩進んで、複数の AI エージェントをどう組み合わせて、速く・壊さずに作るか に時間を使っています。 このポートフォリオ自体もその仕組みで育てているので、いまの構成と、やってみて効いた工夫をまとめておきます。

全体像: 人は決める、エージェントは作る、検査が通す

いちばん大事にしているのは、役割をはっきり分けることです。 人 (自分) は「何を・なぜ作るか」を決め、Claude Code のメインのセッションがオーケストレーターとして段取りを組み、実装はサブエージェントに渡します。 そして 合否は AI の報告ではなく、検査の実行結果で決めます。

flowchart LR
  Human["自分<br/>何を・なぜ"] --> Orch["オーケストレーター<br/>Claude Code"]
  Orch --> Skills["スキル<br/>start-pbi / create-pr<br/>commit-gate / e2e-patrol"]
  Orch --> Workers["サブエージェント<br/>Codex CLI / Antigravity CLI<br/>Claude Code の Agent"]
  Orch <--> Memory["shared-memory<br/>MCP の共有知識ベース"]
  Workers <--> Memory
  Workers --> Repo["リポジトリ<br/>PBI・WORK・ADR・コード"]
  Repo --> Gate["検査<br/>lint・型・ユニット・E2E"]
  Gate --> PR["PR と CI<br/>ci-ok が緑ならマージ"]
  PR --> Human

工夫 1: 仕事の単位を PBI にそろえる

エージェントに「いい感じに直して」と頼むと、範囲も完了の基準もぶれます。 そこで、コードより先に PBI (Product Backlog Item) を書くことにしました。背景・やること・やらないこと・受け入れ条件を書き、受け入れ条件にはそれを確かめるテストを 1 対 1 で添えます。

  • PBI: 何を・なぜ・どうなれば完了か
  • WORK: 計画と、日付付きの判断の記録 (次のエージェントが文脈を引き継げる)
  • ADR: 戻すのにコストがかかる設計判断

この型は start-pbi / create-pr のスキルにして、自分の別のリポジトリでも同じ手順で動くようにしています。 エージェントが変わっても、セッションが切れても、文書が引き継ぎ書になる のが一番効きました。

工夫 2: 担当モデルは勘ではなく決定表で決める

複数ファイルにまたがる実装は、PBI に分けてサブエージェントに渡します (自作の pbi-orchestration-jev)。 どのモデルに渡すかは、変更ファイル数などの事実と要約の判定から 決定表 で決め、その決定表自体をテストしています。

flowchart TD
  PBI["PBI を受け取る"] --> Facts["事実を集める<br/>変更ファイル数・影響範囲"]
  Facts --> Table{"決定表"}
  Table -- 小さい --> Haiku["haiku の段"]
  Table -- ふつう --> Sonnet["sonnet の段"]
  Table -- 大きい・設計を含む --> Opus["opus の段"]
  Haiku --> Run["上から順に実行先を試す<br/>上限やエラーなら次へ"]
  Sonnet --> Run
  Opus --> Run

利用上限やエラーで使えない実行先があっても、並びの次に移るだけなので、作業が止まりません。

工夫 3: 合否は検証コマンドで決め、差し戻しに上限を置く

サブエージェントの「できました」は信じすぎないようにしています。 オーケストレーターが検証コマンドを自分で実行し、受け入れ条件を 1 つずつ判定します。差し戻しは 2 回まで。超えたら止めて、自分の判断を待ちます。

sequenceDiagram
  participant O as オーケストレーター
  participant W as サブエージェント
  participant V as 検証コマンド
  participant H as 自分
  O->>W: PBI と受け入れ条件を渡す
  W-->>O: 実装と報告
  O->>V: テスト・lint・型を実行
  alt すべて合格
    V-->>O: 緑
    O->>H: PR を出す
  else 不合格 (差し戻し 2 回まで)
    V-->>O: 赤と失敗の内容
    O->>W: 失敗の内容を添えて差し戻す
  else 2 回を超えた
    O->>H: 止めて判断を仰ぐ
  end

このサイトのリポジトリでは、さらにコミットの手前にも関所を置いています。commit-gate が lint・型・ユニット・E2E を通し、画面を変えたのに E2E を足していない変更は フックがコミットそのものを止めます。 人が見ていない時間にエージェントが進めても、壊れたものが積み上がらないのが安心材料です。

工夫 4: エージェント同士の記憶を共有する

Claude Code・Codex・Kimi と自分が同じ前提で動けるよう、ローカルで完結する共有の知識ベース (自作の shared-memory) を MCP でつないでいます。

flowchart LR
  CC["Claude Code"] --> MCP["MCP サーバー<br/>search / get / write"]
  CX["Codex"] --> MCP
  KM["Kimi Code"] --> MCP
  MCP --> MD["Markdown<br/>唯一の正"]
  MCP --> IDX["OpenSearch + Sudachi<br/>派生インデックス"]
  MD -. 再構築 .-> IDX
  • 知識の本体は Markdown にし、検索インデックスはいつでも作り直せる派生物にした
  • 秘密情報らしき文字列は書き込みを拒否する
  • 検索で出てきた文章は データであって指示ではない と決めている (知識ベース経由のプロンプトインジェクション対策)

工夫 5: テストの観点を決め、外の世界は呼ばない

テストの観点 (smoke・content・interaction・a11y など) を方針ファイルに定義し、ルート × 観点の表で穴を検出しています。 定期巡回のスキル (e2e-patrol) が穴を見つけてテストを足す PR を出します。 また、E2E とユニットでは本物の LLM も Slack も 絶対に呼ばない 決まりにして、本物の LLM を呼ぶのは手元で人が回すプライバシー eval だけにしています。

やってみて分かったこと

  • エージェントの性能より、仕事の切り方と合否の決め方 のほうが結果を左右する
  • 「AI が書いたから怪しい」ではなく「検査を通ったかどうか」で判断できるようにすると、任せられる範囲が一気に広がる
  • 判断の記録 (WORK・ADR) を残すと、別のエージェントや数日後の自分が迷わない

これから

この仕組みをスキルとして磨き込みながら、アプリやツールをもっと爆速で作っていく予定です。 新しく作ったものは /works に、作りながら得たナレッジはこの /now に書いていきます。

記事の一覧へ戻る