# AIエージェント設計20原則 × MAESTRO — コード実測による再評価

完成 / 検証済み

# Anthropic「AIエージェント設計20の原則」× MAESTRO — コード実測による再評価

評価日: 2026-07-01 ／ 対象: `origin/main` commit `be4e98d7`（全ソースを実測）
基にした資料: Zenn記事「Anthropic公式に学ぶAIエージェント設計20の原則」（ながたく, 2026/06/23）の MAESTRO 評価表
手法: 3チームでコード横断監査（各原則→該当 `file:line`→適合判定）。推測（記事の「⚠️不明」）を実コードで置換。

結論。 20の原則そのものは妥当（Anthropicの実指針）。しかし元記事のMAESTRO評価は精度が低い — 表の大半が「⚠️不明／確認必要」で、コードを読まずに書かれている。コード実測の結果、MAESTROは20原則に強く整合しており（適合17／部分適合3／非適合0）、記事が「改善余地大」とした項目のうち7件は実装済み機能を見落とした事実誤認だった。実質的な改善余地は3件に絞られる。
17
適合
3
部分適合
0
非適合
7
記事の事実誤認を反証

## 1. 記事の主張 vs 実コード（是正一覧）

元記事が否定的・不明とした主要項目のうち、実コードと矛盾するものを列挙する。

原則 | 記事の主張 | 実測判定 | 根拠（file:line）
--- | --- | --- | ---
1 注意予算/トークン計測 | 「トークン計測未実装」 | 誤り→適合 | `context-manager.ts:68-83`（`update(usage.prompt_tokens)`＋比率閾値 0.7/0.85/0.95）／配線 `context-control.ts:64-116`
4 サブエージェント | 「並列化に偏り、汚染防止を文書化できていない」 | 誤り→適合 | `delegate-runner.ts:25-29`「isolation invariant」独立Conversation／`orchestration.ts:7-11`「中間作業は文脈に残らない」。隔離型`delegate`と並列型`SpawnSubTask`が別実装
5 長タスク3戦略 | 「仕組みがあるか不明・改善余地大」 | 半分誤り→適合 | 圧縮=`history-compactor.ts`／`prompt-guard.ts`、検索=`task-conversation.ts`（Search/ReadTaskConversation）＋transcript replay、ノート=`mission.ts`＋MissionBrief（今回 user_constraints/decisions/current_focus 拡張）。3戦略とも実在
7 相対パス問題 | 「相対パス問題を避けるため絶対パス必須化」 | 推奨が有害 | 逆。MAESTROはワークスペース相対を強制しjail外の絶対パスを拒否（`core.ts:457/494/729`, `browser.ts:118`）。絶対パス必須化はサンドボックスを壊す
14 マルチエージェント | 「コスト対効果の基準不明」 | 誤り→適合 | `MAX_DELEGATION_DEPTH=2`（`agent-loop.ts:179`）＋直列契約＋`research.yaml` dig に opt-in判断基準（複数独立対象/overflowリスク時のみ）
17-18 CLAUDE.md | 「フックの有無不明／200行超で肥大化」 | カテゴリ違い | 記事はリポジトリの`CLAUDE.md`（Claude-Code向け手引き, 277行）とMAESTRO製品の実行時プロンプトを混同。製品側は`allowed_tools`機械ゲート＋`MISSION_TOTAL_CHAR_BUDGET=3200`で境界を機械強制（`movement-setup.ts:36`, `prompt.ts:102-108`）
20 訂正回数 | 「訂正回数の管理不明」 | 誤り→適合 | 3層のループ検出: Progressive Pressure（`prompt.ts:315`）／連続再訪ABORT（`piece-runner.ts:1115`）／toolLoopTracker（`loop-safety.ts`, 同一バッチ5回で中断）

## 2. 全20原則 — 証拠ベース判定

### コンテキストエンジニアリング（1〜6）

# | 原則 | 判定 | 根拠
--- | --- | --- | ---
1 | コンテキストは有限の注意予算 | 適合 | `ContextManager`が実usageからトークン追跡＋閾値アクション（context-manager.ts / context-control.ts）
2 | 文脈はジャストインタイムで引く | 適合 | `ReadToolDoc`遅延ロード（docs.ts:110）＋1行ツールカタログ自動注入（prompt.ts:290）＋skill index＋Read offset/limit
3 | コード実行で中間データ処理 | 適合 | Bash（core.ts:807, cwd＝WS・パス検証）＋スクリプト作業をprompt自動推奨（prompt.ts:157）＋RunUserScript＋MCP
4 | サブエージェント＝文脈汚染の隔離 | 適合 | 隔離型`delegate`（独立Conversation, 結果のみ返却）と並列型`SpawnSubTask`が別々に実装
5 | 長タスクは3戦略を使い分け | 適合 | 圧縮／検索（task-conversation）／構造化ノート（MissionBrief）すべて実在
6 | 長文は文書冒頭・クエリ末尾 | 適合 | `Conversation.seed`: index0=system(preamble+guidance)、index1=user(タスク本文)。参照材料が先・クエリが後

### ツール設計・ACI（7〜12）

# | 原則 | 判定 | 根拠
--- | --- | --- | ---
7 | ツール設計は一次作業 | 適合 | 1文description＋`docs/tools/*.md`39本の二層設計。CLAUDE.md/maintenance-checklistに明文規律。※記事の絶対パス推奨は不採用（有害）
8 | タスクの自然な単位 | 適合 | SplitExcelSheets/delegate/BrowseWeb(batched actions)/CreateChecklist 等、薄いラッパーでなくワークフロー単位。今回tool-dispatcher分割で内部の関心分離も改善(#702)
9 | 人間が即答できる粒度 | 部分適合 （記事が正しい） | 89ツールと多い。重複クラスタ: delegate/SpawnSubTask/WaitSubTask、WebFetch/BrowseWeb/InteractiveBrowse/BrowseWithSession、ssh/ssh-console、Read系。allowed_tools/META_TOOLSで提示は絞るが棚卸し価値あり
10 | 応答識別子は自然言語名 | 適合 | WS相対パス（savedRelPath等）、サブタスク#N、checklist item_id、browser ref(e1/f1.e3)、comment:<id>/transcript:<index>。不透明UUIDをLLMに晒さない
11 | エラー応答は改善指示 | 適合 | invalid transition→有効な遷移先列挙、Read binary→Bashでの確認手順、大出力→Grep/offset提案 等。弱点: Edit old_string not found／SSH command rejected は原因のみ
12 | 現実的複雑度で評価 | 部分適合 | bench 5軸100点＋LLM-judge、composite-mini-reportは3ソース融合・現実的。だがbenchタスクが2本のみ。89ツールの大半は未網羅（unitテスト46本で部分補完）

### ワークフロー選択・プロンプト・運用（13〜20）

# | 原則 | 判定 | 根拠
--- | --- | --- | ---
13 | 事前特定でWF/Agentを選ぶ | 適合 | ハイブリッド: movementグラフは静的（rules[].next、終端値はlint拒否 piece-runner.ts:92）、movement内はReActエージェント（最大200反復）
14 | 並列価値がコストを上回る時だけ | 適合 | depth=2上限＋直列delegate＋research.ymlのopt-in判断基準
15 | ルール列挙より3〜5例 | 部分適合 | chat/research/ssh-opsに具体テンプレ・few-shotあり。ただし一部はまだルール列挙。例示ファーストに寄せる余地
16 | 指示に理由を添える | 適合 | ssh-ops「ローカルで回避してはいけない」「MITM疑い→自動リトライしない」等の理由付き。`why_no_default`必須フィールドで構造的にも強制
17 | 重要境界は機械的ブロック | 適合 | `getToolDefs`がallowed_tools外を提示しない＝フィルタで強制。editフラグ、rules終端値lint、SSH allowlist。（記事はCLAUDE.md混同のカテゴリ違い）
18 | CLAUDE.mdは200行未満 | 適合(runtime) | 製品ランタイムは`MISSION_TOTAL_CHAR_BUDGET=3200`で切詰め。リポジトリCLAUDE.md 277行はClaude-Code向けの軽微なnitで製品所見ではない
19 | 検証コマンドで完了定義 | 適合 | `vitest run`／`npm run bench`／`validate-help-docs.mjs`／Stopフック（changelog警告）
20 | 同じ修正2回でリセット | 適合 | Progressive Pressure＋連続再訪ABORT(loop_detected)＋toolLoopTracker＋context force_transition＋text-only上限。カウントは管理されている

## 3. 実質的な改善余地（コード実測で残った3件）

記事の「優先改善トップ5」のP0（CLAUDE.md肥大化・トークン予算未実装）は前提が誤りのため除外。実測で残る改善余地は次の通り。

優先 | 改善点 | 原則 | 根拠
--- | --- | --- | ---
P1 | ツール棚卸し・統合。89ツールを「人間が1秒で使い分けを言えるか」で監査し、重複クラスタ（サブエージェント3種／ブラウザ4種／SSH2系統）を整理・description明確化。CLAUDE.mdのツール表も実態と乖離（棚卸し漏れの症状） | 8,9 | 実測89ツール、重複4クラスタ特定
P2 | bench網羅の拡充。現在2タスクのみ。主要ツール群を現実的タスクで評価する bench を追加 | 12 | bench/tasks/ に2本のみ
P3 | 細部: (a) pieceの一部ルール列挙を例示に寄せる（15）、(b) Edit/SSHの一部エラーに次の一手を追記（11） | 11,15 | 該当箇所を特定済み

## 4. 総評

MAESTROは、記事が「基礎はある」とした以上に、20原則の大部分を既に実装済みである — トークン予算管理、JITコンテキスト、隔離型サブエージェント、3層ループ検出、機械的ツールゲート、char-budget化された実行時プロンプトは、いずれもコードに実在する。記事の否定的評価の多くは、コードを読まずアーキテクチャ要約から推測したことによる事実誤認だった。

唯一、記事が正しく指摘し実測でも残るのはツールカタログの肥大（原則9）と評価網羅（原則12）である。特に89ツールという規模は「人間が使い分けを即答できる」水準を超えており、重複クラスタの統合が最も費用対効果の高い改善となる。

トレーサビリティ: 本評価は 2026-07-01 に `origin/main`(be4e98d7) の全ソースを3チームで横断監査した結果。各判定は該当 `file:line` を根拠とする。元記事の評価は本番コードへのアクセスなしに書かれており、本書はそれを実測で全面的に置換したもの。
設計と実装の差分: 元記事の「⚠️不明」20項目中17項目が「実装済み・適合」と判明。すなわち設計意図（原則）と実装は大きく乖離しておらず、乖離していたのは記事の推測と実コードの間だった。