コードを書かないSE日誌

SE歴26年。コードを書かずにClaude Codeで8体のAIエージェントチームを動かしています。AIエージェント・自動化・GTDの実験日誌。

自己改善するマルチエージェント組織の作り方 — Claude Code で構築した9エージェント体制のハーネス設計

Claude Code の上に 9 エージェント体制を構築し、ガバナンスインシデント 19 件・trigger リスト 7 項目・Playbook 87 本を運用中。

ここでいう「自己改善」とは「失敗が起きたら修正する(自己修正)」ではなく、「失敗していなくてもより良い構造を取り入れる(事前提案を含む)」を指す。事後対応だけでは「自己修正」止まりで、事前提案の経路が加わって初めて「自己改善」になる。

この組織が「自己改善できる」と言えるのは、フィードバックの入口がエージェント側から自発的に上がってくる設計になっているからだ。失敗が起きれば事故記録ファイルとして構造化され、その型が trigger リストへ変換される。改善案に気づけば proposals: フィールドで COO へ伝達し、ユーザー承認を経てルールが更新される。ネガティブ(事故記録)とポジティブ(proposals)、両方の入口がエージェント発火で設計されている点が、「ルールを人間が一方向的に書き下ろす組織」との本質的な違いだ。


1. Claude Code ハーネスのコア — 前提・入口・器で見る自己改善ループ

このハーネス設計のキモは、エージェントの数でも専門化の細かさでもなく、エージェント側から組織ルールへのフィードバックが上がってくる構造にある。組織全体図のあとガバナンス層を「前提・入口・器」の 3 カテゴリで説明する。

組織全体像: このガバナンスはどんな組織の上に乗っているか

組織構成は次のとおり。

エージェント 役割
COO ユーザー指示の受け取り・委任・進捗管理(オーケストレーター)
architect 要件を設計書に変換する。実装ツールは持たない
devops 権限管理・MCP 設定・インフラ整備
researcher 調査・分析・外部知識アーカイブ検索
reviewer ファクトチェック・コードレビュー
secretary GTD・GitHub Issue 管理・クロスポスト管理
writer 記事執筆・はてな / Zenn / Qiita 投稿
skill-dev カスタムスキル(/todo 等)とスクリプト開発
reader 想定読者ペルソナで感情評価。修正権なし

委任は COO 起点で放射状に伸び、記事公開フローなら COO → researcher → writer → reviewer/reader → writer → secretary の連鎖になる。COO を除く 8 体がサブエージェント(Claude Code の公式用語)として動作し、tools 制限と Playbook で役割が区切られている。

ガバナンス層の 3 カテゴリ対応表

カテゴリ 構成要素 役割
前提 4 つの権利(憲法・上申経路を含む) 入口と器が成立するための制度的前提。何を提案してよいか、誰が承認するかを定義する
入口(ネガティブ FB) 事故記録(logs/governance-incidents/) 違反・事故をファイルとして構造化する。ここから器への変換が起きる
入口(ポジティブ FB) proposals: フィールド エージェントの気づきを成果物 YAML に構造化する。ここから器への変換が起きる
器 trigger リスト / Playbook / global-rules.md 両 FB から集約され、ルール化された結果が溜まる場所。ネガティブ(事故)とポジティブ(気づき)どちらの入口からも更新を受け取る

両方の入口ともエージェント側が発火する。ルールを使う側が「使ってみたうえでの不具合・改善案」を構造化して上申し、それが次のルールになる設計だ。

前提: 4 つの権利 — 経路の制度的根拠

CLAUDE.md の「価値観ガバナンス」節に定義された 4 条が、入口と器を成立させる制度的前提だ。

権利 内容
提案権 全エージェントは、ユーザーや組織への不利益を発見した場合、改善案を COO に提案できる
整合性チェック Claude は提案前に既存ルール・価値観との矛盾を確認する(矛盾があっても提案は行う)
承認権 価値観・ルールの変更が正しいかを判断するのはユーザー。承認なしに Claude は変更しない
上申経路 サブエージェントの改善提案は COO → ユーザーの順で上申する

この 4 条は意図的に抽象化されている。「いつ提案を上げるか」の具体的発火条件は別レイヤーの trigger リストに委ねる。憲法をそのまま運用すると、auto mode(無人で連続作業させるモード)で発火条件が判定できず機能しなくなるからだ(整備の経緯は『Claude Code の憲法を書いたら、1日で法律になった話』参照)。

入口(ネガティブ FB): 事故記録(governance-incidents)— 違反・事故を構造化する

logs/governance-incidents/ ディレクトリには、ルール違反・スクリプト事故・独断判断の事例がファイルとして蓄積されている。このディレクトリの肝は記録フォーマットの標準化だ。フォーマットには「事故概要 / 被害範囲 / 原因(独断判断 or トリガー見落とし or ルール不備)/ 再発防止策 / ルール更新箇所」に加えて、「trigger リストへの追記候補」セクションが定められており、近年の事故記録ではこのセクションを使って trigger 変換候補を明示している。

このセクションが要諦だ。自由記述のまま放置すると「再発防止策を書いて終わり」になりやすい。専用セクションと「トリガー / なぜ承認が必要か / 確認形式」の三列テーブル形式を用意することで、「この事故から引き出せる if 文は何か」という変換作業をファイルフォーマットレベルで促す。事故を記録する行為がそのまま trigger 化の検討を内包する設計だ。

事故型が記録されると、COO がルール更新箇所を確認してユーザーへ上申し、承認を経て trigger リストや Playbook が書き換わる。ネガティブ FB 経路の実体は「事故 → ファイル記録 → trigger 変換候補の明示 → ユーザー承認 → ルール更新」という連鎖だ。

入口(ポジティブ FB): proposals: フィールド — エージェントの気づきを構造化する

事故が起きる前の気づきを共有する入口を担うのが proposals: フィールドだ。気づきがあれば成果物の YAML ヘッダーに次の形式で記述する。

proposals:
  - what: "Playbook X の手順 3 が実態と乖離している"
    why: "コマンド `foo --bar` が deprecated でエラーになった"
    suggestion: "`foo --baz` に書き換える"

COO はこれを受け取って整合性チェックを行い、ユーザーへ上申する。フォーマットがなければ気づきは口頭で埋もれかねないが、proposals: があると「構造化された改善信号」として必ず COO の目に入る。

global-rules.md では、Playbook と実態の乖離・スクリプトのエラー・前提の不一致を「必須記録」と定めている。「気づいたら記録する」ではなく「該当事象が起きたら必須記録する」と書かれているのが要点だ。客観的観測事象でトリガーする設計にすることで、改善信号がエージェントの主観的判断に依存しなくなる。

器: trigger リスト・Playbook・global-rules.md — ルール化された結果が溜まる場所

trigger リストは「いつ憲法を発火させるか」を列挙したテーブルだ。現在 7 項目。

トリガー なぜ承認が必要か
デフォルト値変更で挙動 on/off を切り替える 副作用が記事・課金・外部 API に波及
不特定多数を触る一括操作(migrate / bootstrap / cleanup 系、書き込み系スクリプトの本実行を含む) 一度走らせたら多数ファイルを変更、部分失敗で復旧困難
自動実行の登録(Task Scheduler / cron / Remote Trigger) 無人実行開始は不可逆性が高い
安全装置バイパス(--dangerously-skip-permissions, --force, --no-verify) バグやプロンプト注入で破壊的動作に直結
連続 5 コミット超え 変更量が大きいと憲法チェックが発火しなくなる
既存スクリプトを経由しない外部 CLI 直接実行 スクリプトが持つガード・パラメータ検証をバイパスする
blogsync 直接実行(pull/push 問わず) 設定値の相対パス依存で二重パス事故が起きる

これら 7 項目は実際に起きた事故から後ろ向きに導出されている。設計時から網羅されたわけではなく、事故型を再発させないために 1 行ずつ追加した結果が今の形だ(設計思想と他事例との比較は『CLAUDE.mdに「憲法」と「trigger リスト」を書いた理由』参照)。

trigger リストの運用核は確認形式の原則に集約される。

「何を・なぜ・副作用は」を明示する。ユーザーが 1 / OK / 具体的承認語 を返すまで実行しない。沈黙 ≠ 承認。

「沈黙 ≠ 承認」の一文は、「明示的な拒否がない=進めてよい」という解釈を塞ぐ if 文だ。trigger リストおよび Playbook・global-rules.md は、事故記録(ネガティブ FB)と proposals(ポジティブ FB)どちらの入口からも更新を受け取る。


2. 3 層の分業設計 — ガバナンスを支える分業構造

3 層の構造は次のとおり。

┌─ ガバナンス層(前提: 4つの権利 / 入口: 事故記録・proposals / 器: triggerリスト・Playbook)─ 全層を貫く規律
├─ オーケストレーション層(COO: 指示・委任・調整)
└─ 専門化層(8エージェント: architect / devops / researcher /
              reviewer / secretary / writer / skill-dev / reader)

レイヤー 1: オーケストレーション層(COO)

COO はユーザー指示を直接受け取り、専門エージェントへ委任する。coo-rules.md で「直接やってよい作業」と「委任すべき作業」が明確に分けられている。軽微なファイル修正・git 操作は COO 直接実行、設計・実装・章単位の執筆は各エージェントへ委任する。委任にはオーバーヘッド(起動コスト・往復のトークン消費)があり、軽作業の委任は逆効果になる。COO は proposals: を受け取って整合性チェックを行い、ユーザーへ上申する「中継点」でもある。

レイヤー 2: 専門化層(8 つのサブエージェント)

専門化層の 8 体のサブエージェントは、tools: フィールドで使えるツールが明示的に制限されている。例えば architect エージェントは tools: Read, Grep, Glob, Write のみで、Edit も Bash も含まれていない。つまり設計書しか書けない。コード編集もシェルコマンド実行もできない。これは仕様であり、設計と実装を分離するためには設計担当が実装ツールを「持たない」ことが構造的に必要だ。reader(感情レビュー担当)も同様に Read/Grep/Glob/Write のみで、本文を直接書き換えられない。

権限制限が専門化を強制するこの設計は、「役割の逸脱」を構造的に防ぐ。プロンプトで「設計のみ行ってください」と指示しただけだと、エージェントは作業途中で「ついでに実装しちゃおう」と判断することがある。tools 制限はその判断自体を不可能にする。

設計課題と解決の対応関係

設計課題 解決方法
エージェントが役割を逸脱する tools: フィールドでツール権限を物理的に制限する
委任オーバーヘッドが直接実行コストを上回る COO 直接実行と委任を明示的に分ける
ルール違反を auto mode で検出できない 抽象ルールと具体 trigger を分離(憲法と trigger リスト)
エージェントの気づきが COO に伝わらない YAML フィールドで「構造化された改善信号」を強制する
役割が曖昧で上申の判断ができない tools 制限と Playbook で役割を明文化し、ガバナンス層の前提を整備する

下 3 行が、分業組織を「自己改善できる」へと押し上げる設計だ。


3. なぜこの形に収束したか — 自己改善が成立している証拠

本節では自己改善が機能している証拠を、ネガティブ FB とポジティブ FB の両方の指標で示す。

証拠 1: ネガティブ FB が機能している証拠

logs/governance-incidents/ ディレクトリには、発生した事故型が記録されている。

  • ガバナンスインシデント記録: 19 件
  • trigger リスト項目数: 7 項目

19 件から 7 型を trigger リストへ導出している。trigger リストの 7 項目は最初から 7 項目あったわけではない。初期は 5 項目で運用が始まり、新しい事故型が出るたびに追加されてきた「インクリメンタルな構築」の結果だ。事故記録フォーマットが「trigger リストへの追記候補」セクションを内包することで、この変換作業をファイルレベルで促している。

証拠 2: ポジティブ FB が機能している証拠

proposals: フィールドを通じた改善提案も、ルール更新につながっている。

  • global-rules.md に「Playbook 乖離・エラー回避の必須記録」セクションが追加されたこと自体がポジティブ FB の結果だ。事故ではなく「Playbook が不便」という気づきがルール化された。
  • devops の settings.local.json 編集権限が「事前承認不要・事後報告必須」に運用化されたこと。devops 自身の提案で運用ルールが書き換わった例だ。

どちらも「事故が起きたから」ではなく「使ってみてこうしたほうがよい」という気づきがエージェント側から上がってルールが更新された例だ。


補足: 移植性と「収束した」という表現

移植性は部分的だ。移植可能なのは枠組み(4 つの権利・事故記録フォーマット・proposals: フォーマット・trigger リストの形式・tools 制限・委任の二列表)。プロジェクト固有なのは中身(trigger の具体項目・Playbook の手順・専門エージェントの分担)。trigger の中身はそのプロジェクトが踏んだ失敗の歴史で決まるため移植できないが、「前提・入口・器」の枠組み自体はどこでも使える。

このハーネスは設計図から逆算したものではない。憲法を書いただけでは auto mode で機能しなかった実観測から、事故記録の構造化と proposals: が必要になった。運用中の事故と気づきを 1 つずつ吸い上げて現在の形に「収束した」と表現するのが正確だ。なお、エージェント群を包む制度設計全体を「ハーネスエンジニアリング」と呼ぶ語が 2026 年ごろから定着しつつある。本記事の設計もその文脈に入る。


結論: ハーネスは今もこのループの中にある

ネガティブ(事故記録)とポジティブ(proposals)、両方の入口がエージェント発火で設計されている — これが「ルールを人間が一方向的に書き下ろす組織」と「自己改善できる組織」の分岐点だ。

このハーネスは「完成した組織」ではない。明日のセッションで新しい事故型が見つかるかもしれないし、新しい proposals: が上がってくるかもしれない。trigger リストはまた 1 行増え、Playbook がまた書き換わるだろう。

このハーネスは今もこのループの中にある。


関連書籍

本記事で扱った「専門化層」「ガバナンス層」という分業概念は、人間のソフトウェア開発チームを対象とした書籍『チームトポロジー』が提示する Stream-aligned team(成果に直結する専門チーム)/ Enabling team(専門知識を他チームに提供するサポートチーム)と類似する。本書は AI エージェント組織を直接扱うものではないが、「責務分割と相互作用の設計」という抽象レベルでは類比が成立する。人間チーム設計の議論をエージェント組織にどう移植するかという観点で読むと示唆がある。Amazon


自己改善ループを持つAIエージェント組織を作るまでの試行錯誤と設計原則を、電子書籍にまとめています。

コードを書けない私が、AIに「チーム」を持たせるまで(序章・第1部無料)