Claude CodeでAI駆動開発を続けていると、AIエージェントはだんだん増えていきます。
- 開発者エージェント
- レビューワー
- QA
- 敵対的レビュー
- クラッシュ原因調査
- 企画レビュー
- 分析・監査
それぞれ専門性を持たせ、役割分担させることで、AI駆動開発の自動化範囲はかなり広がりました。
ところが、エージェントチームを高度化していくうちに、別の問題が見えてきました。
AIエージェントが増えるほど、人間が読むものも増える。
今回は、この問題に対して既存のエージェント資産をFable 5に棚卸しさせ、全体を横断する 「Human ↔ Agent 出力契約（Output Contract）」 を導入した話です。
最終的にたどり着いた原則は、かなりシンプルでした。
網羅性は成果物に、要約は会話に。
AI側の分析・レビュー・QAの情報量は削らず、人間がその瞬間に読む情報量だけを減らす設計です。
きっかけは「i-have-adhd」だった
今回の発端になったのが、GitHubで公開されている ayghri/i-have-adhd ― coding assistantの出力をaction-firstに整えるSkill でした。
このSkillには、
- 最初に次の行動を示す
- 複数工程を番号付きにする
- 現在の状態を毎回明示する
- 余談を抑える
- 完了したことを見えるようにする
- エラーを感情的にせず事実ベースで伝える
- 長い一覧は優先順位を付けて整理する
といった、「人間が次の行動へ移りやすい出力」にするための考え方が含まれています。
最初に思ったのは、
これをClaude Codeのエージェントチームにも入れたら良いのでは？
ということでした。
しかし、そのまま全エージェントへ適用すると別の問題が起きます。
全エージェントに「短く答えて」は危ない
たとえば、私のレビュー系エージェントチームは概念的には次のような構成になっています。
ここで、すべてのエージェントに
短くしてください
重要なものだけ出してください
一覧は5件以内にしてください
と適用したらどうなるでしょうか。
QAが本来30件作るべきテストケースを5件に減らすかもしれません。
Reviewerが10件見つけた指摘のうち、5件しか後段へ渡さなくなるかもしれません。
認知負荷を下げるための指示が、Agent側の網羅性まで落としてしまう可能性があります。
これは避けたい。
必要なのは Agentの思考・分析量を減らすこと ではありません。
必要なのは Humanが今読む量を減らすこと です。
この2つを分離して設計する必要がありました。
Fable 5への依頼は、あえて短くした
そこでFable 5へ渡した指示は、かなりシンプルです。
https://github.com/ayghri/i-have-adhd の設計思想を参考に、
既存の全エージェントチームへHuman ↔ Agent間の認知負荷を下げる
出力設計を横断適用してください。
各エージェントの専門性・網羅性・成果物は維持してください。
「このファイルを変更する」
「このMarkdownを共通化する」
「RESULTというフィールドを追加する」
といった実装方法までは指定していません。
今回やりたかったのは、単純な実装ではなく、
既存システムを調査し、どこを共通化すべきかをAI自身に判断させること
だったからです。
Anthropic公式のPrompting best practicesでも、現在のClaudeでは長時間のAgentic workflowやSubagent orchestrationを前提とした設計が扱われています。
今回Fable 5に任せたのも、まさに
調査
↓
構造把握
↓
共通概念の抽出
↓
横断的な適用
という仕事です。
まず「エージェント一覧」ではなく「情報経路」を棚卸しする
Fable 5がまず整理したのは、既存のエージェントチームです。
今回の環境では、主に次の系統が対象になりました。
review系
├─ review-smart
├─ review-and-fix
├─ review-team-and-fix
└─ review-adversarial
plan-review
ga-audit
dev-loop
crash-rca
work-intake
ただし重要なのは、Skill名の一覧を作ることではありません。
各チームについて、
誰がOrchestratorなのか
誰がSubAgentなのか
どこで人間へ回答するのか
何を成果物として残すのか
Slack / Redmineへ何を通知するのか
Agent間では何を受け渡しているのか
を調べていきます。
すると、各Agentの専門分野は異なっていても、出力の経路には共通構造があることが見えてきました。
出力をC1〜C4の4経路に分ける
棚卸しの結果、出力を4種類に分類しました。
| 経路 | 送り手 → 受け手 | 目的 |
|---|---|---|
| C1 | Orchestrator → Human | チャットで判定と次の一手を伝える |
| C2 | Orchestrator → Human | Slack / Redmineへ通知する |
| C3 | Agent Team → Human / 外部読者 | レポート・QA項目・HTMLなどを残す |
| C4 | SubAgent → Orchestrator | Agent間で結果を統合する |
ここが今回の設計で一番重要なポイントです。
一口に「AIの出力」と言っても、誰が読むのかによって必要な情報密度が違います。
C1：Orchestrator → Human
チャットの目的は、
人間が「今どうなっているか」と「次に何をすればよいか」を判断すること
です。
そのため、チャットでは情報を圧縮します。
たとえば処理途中なら、
review-team-and-fix #431806
— Step 4/10 Aggregator
| 🔴0 🟠0 🟡1 🟢1
次: Self-Critique
のようにします。
これなら、過去のメッセージを読み返さなくても、
- 何を実行しているのか
- どこまで進んだのか
- 現在問題があるのか
- 次に何をするのか
が分かります。
最終報告も6ブロックに固定した
人間向けの最終報告は、原則として次の順番にしました。
判定
↓
次の一手
↓
要点
↓
成果物
↓
未実施・未確認
↓
記録
たとえばレビューなら、
判定:
修正1件適用・ビルド✅
残課題 🟡1 🟢1
Blockingなし
次の一手:
受け入れ基準Q1へ回答する
要点:
- Blocking 0
- Major 0
- Minor 2
- Build成功
- QA作成済み
成果物:
- review-report.md
- qa-test-cases.md
- acceptance-criteria.md
未実施・未確認:
- 実機確認は未実施
記録:
STATE.md更新済み
となります。
ポイントは、
「レビューを実施しました。以下に結果を報告します」
のような前置きをなくしたことです。
人間が最初に知りたいのは、レビューをやった事実ではなく、レビューの結果です。
C2：Slack / Redmineも「1行目で判定」
SlackやRedmineも同じ考え方です。
以前は、
レビューが完了しました。
という通知から始まっていました。
しかし、これでは本文を読まなければ、
- 問題があったのか
- 修正したのか
- ビルドできたのか
- Blockingがあるのか
が分かりません。
そこで、
#431806 レビュー完了:
修正1件・ビルド✅・残課題🟡1・Blockingなし
のように、
1行目だけで結果が分かる
構造へ変更しました。
Slackのように大量の情報が流れる場所では、この違いはかなり大きいと思います。
C3：成果物は逆に削らない
ここが今回もっとも重要な設計判断です。
チャットでは5件程度に整理して見せても、成果物には5件制限を適用しません。
Human向けチャット
↓
重要な3〜5件
件数
詳細の所在
成果物
↓
全レビュー指摘
全QA項目
全検証結果
全証拠
という分離です。
たとえばReviewerが20件の指摘を見つけたなら、レビュー成果物には20件すべてを残します。
QAが50件の試験項目を作ったなら、50件すべて残します。
人間向けチャットだけ、
重要3件
ほか17件 → review-report.md
のように圧縮します。
この設計を一文にまとめたのが、
網羅性は成果物に、要約は会話に。
です。
削るのは情報ではありません。
人間がその瞬間に読む量と、読む順番の迷いだけです。
C4：SubAgent → OrchestratorにもHuman Interfaceの思想を応用する
棚卸ししていて面白かったのが、Agent間通信です。
情報を読むのは人間だけではありません。
複数のSubAgentから返ってくる大量の結果を、Orchestratorも読み取って統合しています。
そこでSubAgentの出力にも、RESULT: という即読可能な情報を追加しました。
たとえばReviewerなら、
RESULT:
指摘3件
🔴0 🟠1 🟡2 🟢0
未確認1観点
Crash RCAの反証Agentなら、
RESULT:
REFUTED 1
SURVIVES 1
NEEDS_EVIDENCE 0
という形です。
しかし重要なのは、RESULTだけを返して終わりにはしないことです。
RESULT
↓
Orchestratorが即座に読める要約
詳細
↓
従来どおり全件
としています。
つまり今回の設計思想は、Human Interface だけでなく Agent Interface にも応用できました。
Claude Code公式「カスタムサブエージェントの作成」でも、専門化したSubAgentへタスクを委譲する仕組みが提供されています。
SubAgentが増えるほど、Agent同士のインターフェース設計も重要になってくると思います。
共通ルールを「Output Contract」として正本化した
ここまでのルールを各Skillへコピペすると、今度は保守が大変になります。
そこで今回の環境では、~/.claude/context/output-contract.md を正本として作成しました。
概念的には、次の構造です。
各Orchestratorは開始時にOutput Contractを読みます。
SubAgent側には、必要なルールだけを埋め込みます。
これによって、
Human Interfaceの原則は共通化するが、各Agentの専門性・成果物フォーマットは維持する
構造になりました。
Claude Code公式「スキルでClaudeを拡張する」にあるように、Claude CodeではSkillとして反復可能なワークフローをパッケージ化できます。
その上に、複数のSkillをまたぐ横断的な契約を置く、という考え方です。
全チームを完全に同じフォーマットにはしない
ここも重要です。
Output Contractを作ったからといって、全Agent Teamに同じ6ブロックを強制したわけではありません。
たとえば work-intake は、Slackスレッドなどを読み、
対象
分類
推奨
次の一手
を示す受付処理です。
この場合は、
判定
次の一手
要点
成果物
未確認
記録
へ無理に変換するより、
対象
分類
推奨コマンド
次の一手
を受付票の先頭に置いたほうが自然です。
Output Contractは、見た目を統一するためのフォーマット規約ではなく、認知負荷を下げるための設計原則として扱いました。
共通化することと、画一化することは別です。
「次の一手」は1つにする
今回取り入れた中で効果が大きそうなのが、
Next Actionを1つにする
ことです。
AIはよく最後に、
次の候補として、
- Aを確認する
- Bを修正する
- Cについて相談する
- Dも検証する
- Eも検討するとよいでしょう
のように返します。
情報としては正しい。
しかし、人間から見ると、
「で、最初にどれをやればいいの？」
という仕事が残っています。
これは、タスク分解をAIへ任せたのに、最後だけ人間へ戻している状態とも言えます。
そこで、
次の一手:
受け入れ基準Q1へ回答する
まで絞ります。
必要であれば、
その後:
再レビューを実行する
を1件だけ追加します。
Human Interfaceの役割は、情報を見せることではなく、次の判断を容易にすることだと考えました。
「未実施・未確認」は絶対に消さない
一方、短くする設計で一番怖いのは、未確認事項まで要約で消えてしまうことです。
たとえば、
Build: ✅
と、
Build: 未実施
は全く違います。
未実施なのに「たぶん問題ない」から ✅ へ要約されてしまえば、Human Interfaceはむしろ危険になります。
そのため、記号の意味も固定しました。
✅ 実施して成功
❌ 実施して失敗
⏭ 未実施
⏳ 実行中
さらに最終報告には、未実施・未確認 を独立ブロックとして残します。
認知負荷を下げることと、情報を都合よく丸めることは別問題です。
Human Interfaceだけでなく、成果物の冒頭も変える
今回の棚卸しでは、チャットだけではなく成果物も見直しました。
ただし、本文を短くするわけではありません。
たとえば、
review-report.md
qa-test-cases.md
意見書.html
といった成果物の冒頭に、
判定
件数
最重要事項
次の一手
詳細の所在
を置きます。
その後には従来どおり、全件を掲載します。
長いレポートを開いた人が、最初から最後まで読まなくても、
「この資料は結局どういう状態なのか」
を理解できるようにしたわけです。
Before / Afterで見ると分かりやすい
今回の変更をかなり単純化すると、以前はこんな状態でした。
Before
レビューを実施しました。
6名のレビューワーが以下の観点で確認しています。
Reviewer A:
...
Reviewer B:
...
Reviewer C:
...
ビルド結果:
...
QA:
...
成果物:
...
以上です。
情報はあります。
しかし、人間は読みながら、
結局OKなのか？
↓
Blockingはある？
↓
修正された？
↓
Buildは通った？
↓
私は何をすればいい？
を自分で組み立てる必要があります。
After
判定:
修正1件適用・ビルド✅
Blockingなし・残課題🟡1
次の一手:
受け入れ基準Q1へ回答する
要点:
- Blocking 0
- 修正1件
- Build成功
- QA 32項目作成
- 未確認1件
成果物:
- review-report.md
- qa-test-cases.md
- acceptance-criteria.md
未実施・未確認:
- 実機確認未実施
記録:
STATE.md更新済み
そして詳細が必要なら成果物を見る。
人間側の仕事が、大量の情報から状態を再構築することから、次の判断をすることへ変わります。
実装してみて見えた改善点もある
今回のOutput Contractは完成形ではありません。
実装後の差分をレビューして、少なくとも2点は今後改善したいと考えています。
1. 時間見積もりは「具体的なら良い」とは限らない
元の考え方には、
少し
しばらく
もう少し
ではなく、
約3〜5分
のように具体化する考え方があります。
確かにHuman Interfaceとしては分かりやすい。
ただし、実測値も過去実績もないのに3〜5分と書くのであれば、それは具体的ではあっても正確ではありません。
そこで、今後は次の優先順位が良いと考えています。
当ランの実測
↓
過去のRUNLOG
↓
Timing Notes
↓
データなし
↓
時間を表示しない
具体性よりも、まず報告の誠実性を優先します。
2. Output Contractの配置はポータビリティも考える
今回の環境では ~/.claude/context/output-contract.md を正本にしました。
個人環境だけで利用するならシンプルです。
一方、プロジェクトの共有資産として運用するなら、
Project
↓
User Homeのファイル
への依存は、他の開発環境へ持っていく際の問題になります。
共有するのであれば、
AgentAssets
↓
共有Output Contract
のようにプロジェクト側へ配置することも検討すべきでしょう。
また、
Output Contractを読めない
↓
全エージェントチーム停止
ではなく、
Output Contractを読めない
↓
Skill内に埋め込まれた最低限のルールで継続
というフォールバックも考えられます。
共通化するときは、Single Source of TruthとSingle Point of Failureを混同しないことも重要です。
今回の「棚卸し手法」は他のAgent Teamにも使える
今回、一番汎用性が高いと感じたのはOutput Contractそのものより、その前に行った棚卸し方法です。
Agentが増えてきたら、まず「Agent一覧を作る」だけではなく、次のように整理します。
- Orchestratorを特定する
- SubAgentを特定する
- Humanへ出る出力を特定する
- Agent間の出力を特定する
- 成果物を特定する
- Slack / Issue Tracker等への外部通知を特定する
- 共通化してよいもの・してはいけないものを分ける
その上で、
Human-facing
Agent-facing
Deliverable
External Notification
という境界単位で共通ルールを抽出する。
これなら、Agentが20体、30体へ増えても、1体ずつ場当たり的にプロンプトを直す必要がありません。
AI駆動開発では「棚卸し」そのものもAIに任せられる
今回もう1つ印象的だったのは、Fable 5へ具体的な変更箇所をほとんど指定しなかったことです。
人間が、
ここを変更
ここにRESULTを追加
ここに6ブロックを書く
と全部設計したわけではありません。
AI自身に、
既存資産を読む
↓
構造を把握する
↓
共通点を探す
↓
境界を整理する
↓
共通契約へ抽象化する
↓
各チームへ横断適用する
ところまで任せました。
これは、AI駆動開発でAIへ任せる仕事が「コードを書く」だけではなくなってきたことを意味します。
既存システムを棚卸しする
アーキテクチャを理解する
共通概念を発見する
横断的にリファクタリングする
ところまで任せられる。
個人的には、今回はこちらのほうが大きな発見でした。
Model → Harness → Agent Team → Human Interface
これまでAI駆動開発では、
Model
↓
Harness
↓
Agent Team
をどう強くするかを考えることが多くありました。
しかしAgent Teamが高度になるほど、その下流にいるHuman側へ流れてくる情報量も増えていきます。
結果として、
Model
↓
Harness
↓
Agent Team
↓
大量の出力
↓
Human ← ここがボトルネック
になる可能性があります。
そこで今回、次の1層を明示的に設計しました。
AIをもっと賢くするレイヤーではありません。
賢くなったAIを、人間が扱える形に変換するレイヤーです。
「AIの能力」と「人間が扱える能力」は別
AIエージェントが、
100件調査できる
50件テストできる
20件レビューできる
10種類の観点を統合できる
としても、人間へそのまま「180件の情報」を渡せば良いわけではありません。
AI側では、
大量
詳細
網羅的
でよい。
Human Interfaceでは、
結論
現在地
重要事項
成果物
未確認
次の一手
へ変換する。
今回の実装を最も単純化すると、
Agent Side
大量・詳細・網羅的
↓
Output Contract
↓
Human Side
圧縮・優先順位付け・次の一手
という構造です。
まとめ
今回やったことを整理すると、
i-have-adhdを発見
↓
そのまま全Agentへ適用するのは危険
↓
Fable 5へ既存Agent Teamsの棚卸しを依頼
↓
情報経路をC1〜C4へ分類
↓
Human ↔ Agent Output Contractを作成
↓
各Agent Teamへ横断適用
↓
Agent側の網羅性は維持
↓
Human側の認知負荷だけを下げる
という流れでした。
最も重要な原則を、最後にもう一度書きます。
網羅性は成果物に、要約は会話に。
AIエージェントが増えてくると、
どうすればもっと賢いAgentを作れるか？
だけではなく、
そのAgent Teamの能力を、人間がどう受け取るか？
まで設計する必要が出てきます。
モデル性能。
Harness。
Agent Team。
そして、Human Interface。
AI駆動開発が高度になるほど、最後のこの1層が重要になっていくのではないかと思います。