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へ渡した指示は、かなりシンプルです。

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がまず整理したのは、既存のエージェントチームです。

今回の環境では、主に次の系統が対象になりました。

対象となったSkill群

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ブロックに固定した

人間向けの最終報告は、原則として次の順番にしました。

最終報告の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も同じ考え方です。

以前は、

Before

レビューが完了しました。

という通知から始まっていました。

しかし、これでは本文を読まなければ、

問題があったのか
修正したのか
ビルドできたのか
Blockingがあるのか

が分かりません。

そこで、

After

#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なら、

Reviewerの返却例

RESULT:
指摘3件
🔴0 🟠1 🟡2 🟢0
未確認1観点

Crash RCAの反証Agentなら、

反証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駆動開発で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層が重要になっていくのではないかと思います。

きっかけは「i-have-adhd」だった

全エージェントに「短く答えて」は危ない

Fable 5への依頼は、あえて短くした

まず「エージェント一覧」ではなく「情報経路」を棚卸しする

出力をC1〜C4の4経路に分ける

C1：Orchestrator → Human

最終報告も6ブロックに固定した

C2：Slack / Redmineも「1行目で判定」

C3：成果物は逆に削らない

C4：SubAgent → OrchestratorにもHuman Interfaceの思想を応用する

共通ルールを「Output Contract」として正本化した

全チームを完全に同じフォーマットにはしない

「次の一手」は1つにする

「未実施・未確認」は絶対に消さない

Human Interfaceだけでなく、成果物の冒頭も変える

Before / Afterで見ると分かりやすい

Before

After

実装してみて見えた改善点もある

1. 時間見積もりは「具体的なら良い」とは限らない

2. Output Contractの配置はポータビリティも考える

今回の「棚卸し手法」は他のAgent Teamにも使える

AI駆動開発では「棚卸し」そのものもAIに任せられる

Model → Harness → Agent Team → Human Interface

「AIの能力」と「人間が扱える能力」は別

まとめ

参考リンク