129 lines
15 KiB
HTML
129 lines
15 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="ja">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>AIエージェント設計20原則 × MAESTRO — コード実測による再評価</title>
|
||
<style>
|
||
:root { --green:#16a34a; --blue:#2563eb; --amber:#d97706; --red:#dc2626; --ink:#1f2937; --muted:#6b7280; --line:#e5e7eb; --bg:#f9fafb; }
|
||
* { box-sizing: border-box; }
|
||
body { font-family: -apple-system, "Hiragino Kaku Gothic ProN", "Noto Sans JP", sans-serif; color: var(--ink); line-height: 1.7; max-width: 1000px; margin: 0 auto; padding: 24px; background: #fff; }
|
||
h1 { font-size: 1.6rem; margin: .2em 0; }
|
||
h2 { font-size: 1.25rem; margin-top: 2em; border-bottom: 2px solid var(--line); padding-bottom: .3em; }
|
||
h3 { font-size: 1.05rem; margin-top: 1.4em; }
|
||
.badge { display: inline-block; padding: 3px 12px; border-radius: 999px; font-size: .8rem; font-weight: 700; color: #fff; background: var(--green); }
|
||
.meta { color: var(--muted); font-size: .85rem; margin: .5em 0 1.5em; }
|
||
table { border-collapse: collapse; width: 100%; margin: 1em 0; font-size: .9rem; }
|
||
th, td { border: 1px solid var(--line); padding: 7px 10px; text-align: left; vertical-align: top; }
|
||
th { background: var(--bg); font-weight: 700; }
|
||
code { background: var(--bg); padding: 1px 5px; border-radius: 4px; font-size: .85em; font-family: ui-monospace, "SF Mono", Menlo, monospace; }
|
||
.ok { color: var(--green); font-weight: 700; }
|
||
.part { color: var(--amber); font-weight: 700; }
|
||
.no { color: var(--red); font-weight: 700; }
|
||
.wrong { background: #fef2f2; }
|
||
.summary-box { background: var(--bg); border-left: 4px solid var(--blue); padding: 12px 18px; border-radius: 0 8px 8px 0; margin: 1em 0; }
|
||
.tally { display: flex; gap: 16px; flex-wrap: wrap; margin: 1em 0; }
|
||
.tally div { flex: 1; min-width: 120px; text-align: center; border: 1px solid var(--line); border-radius: 8px; padding: 12px; }
|
||
.tally .num { font-size: 1.8rem; font-weight: 800; }
|
||
.note { color: var(--muted); font-size: .85rem; }
|
||
.pri { font-weight: 700; padding: 2px 8px; border-radius: 4px; color:#fff; }
|
||
.p1 { background: var(--red); } .p2 { background: var(--amber); } .p3 { background: var(--muted); }
|
||
</style>
|
||
</head>
|
||
<body>
|
||
|
||
<span class="badge">完成 / 検証済み</span>
|
||
<h1>Anthropic「AIエージェント設計20の原則」× MAESTRO — コード実測による再評価</h1>
|
||
<p class="meta">
|
||
評価日: 2026-07-01 ／ 対象: <code>origin/main</code> commit <code>be4e98d7</code>（全ソースを実測）<br>
|
||
基にした資料: Zenn記事「Anthropic公式に学ぶAIエージェント設計20の原則」（ながたく, 2026/06/23）の MAESTRO 評価表<br>
|
||
手法: 3チームでコード横断監査（各原則→該当 <code>file:line</code>→適合判定）。推測（記事の「⚠️不明」）を実コードで置換。
|
||
</p>
|
||
|
||
<div class="summary-box">
|
||
<strong>結論。</strong> 20の原則そのものは妥当（Anthropicの実指針）。しかし元記事の<strong>MAESTRO評価は精度が低い</strong> — 表の大半が「⚠️不明／確認必要」で、コードを読まずに書かれている。コード実測の結果、MAESTROは20原則に<strong>強く整合</strong>しており（適合17／部分適合3／非適合0）、記事が「改善余地大」とした項目のうち<strong>7件は実装済み機能を見落とした事実誤認</strong>だった。実質的な改善余地は<strong>3件</strong>に絞られる。
|
||
</div>
|
||
|
||
<div class="tally">
|
||
<div><div class="num ok">17</div>適合</div>
|
||
<div><div class="num part">3</div>部分適合</div>
|
||
<div><div class="num no">0</div>非適合</div>
|
||
<div><div class="num">7</div>記事の事実誤認を反証</div>
|
||
</div>
|
||
|
||
<h2>1. 記事の主張 vs 実コード（是正一覧）</h2>
|
||
<p>元記事が否定的・不明とした主要項目のうち、実コードと矛盾するものを列挙する。</p>
|
||
<table>
|
||
<tr><th>原則</th><th>記事の主張</th><th>実測判定</th><th>根拠（file:line）</th></tr>
|
||
<tr class="wrong"><td>1 注意予算/トークン計測</td><td>「トークン計測<strong>未実装</strong>」</td><td class="ok">誤り→適合</td><td><code>context-manager.ts:68-83</code>（<code>update(usage.prompt_tokens)</code>＋比率閾値 0.7/0.85/0.95）／配線 <code>context-control.ts:64-116</code></td></tr>
|
||
<tr class="wrong"><td>4 サブエージェント</td><td>「<strong>並列化に偏り</strong>、汚染防止を文書化できていない」</td><td class="ok">誤り→適合</td><td><code>delegate-runner.ts:25-29</code>「isolation invariant」独立Conversation／<code>orchestration.ts:7-11</code>「中間作業は文脈に残らない」。隔離型<code>delegate</code>と並列型<code>SpawnSubTask</code>が別実装</td></tr>
|
||
<tr class="wrong"><td>5 長タスク3戦略</td><td>「仕組みがあるか<strong>不明</strong>・改善余地大」</td><td class="ok">半分誤り→適合</td><td>圧縮=<code>history-compactor.ts</code>／<code>prompt-guard.ts</code>、検索=<code>task-conversation.ts</code>（Search/ReadTaskConversation）＋transcript replay、ノート=<code>mission.ts</code>＋MissionBrief（今回 user_constraints/decisions/current_focus 拡張）。3戦略とも実在</td></tr>
|
||
<tr class="wrong"><td>7 相対パス問題</td><td>「相対パス問題を避けるため<strong>絶対パス必須化</strong>」</td><td class="no">推奨が有害</td><td>逆。MAESTROは<strong>ワークスペース相対</strong>を強制しjail外の絶対パスを拒否（<code>core.ts:457/494/729</code>, <code>browser.ts:118</code>）。絶対パス必須化はサンドボックスを壊す</td></tr>
|
||
<tr class="wrong"><td>14 マルチエージェント</td><td>「コスト対効果の<strong>基準不明</strong>」</td><td class="ok">誤り→適合</td><td><code>MAX_DELEGATION_DEPTH=2</code>（<code>agent-loop.ts:179</code>）＋直列契約＋<code>research.yaml</code> dig に opt-in判断基準（複数独立対象/overflowリスク時のみ）</td></tr>
|
||
<tr class="wrong"><td>17-18 CLAUDE.md</td><td>「フックの有無不明／200行超で肥大化」</td><td class="part">カテゴリ違い</td><td>記事はリポジトリの<code>CLAUDE.md</code>（Claude-Code向け手引き, 277行）とMAESTRO製品の実行時プロンプトを混同。製品側は<code>allowed_tools</code>機械ゲート＋<code>MISSION_TOTAL_CHAR_BUDGET=3200</code>で境界を機械強制（<code>movement-setup.ts:36</code>, <code>prompt.ts:102-108</code>）</td></tr>
|
||
<tr class="wrong"><td>20 訂正回数</td><td>「訂正回数の<strong>管理不明</strong>」</td><td class="ok">誤り→適合</td><td>3層のループ検出: Progressive Pressure（<code>prompt.ts:315</code>）／連続再訪ABORT（<code>piece-runner.ts:1115</code>）／toolLoopTracker（<code>loop-safety.ts</code>, 同一バッチ5回で中断）</td></tr>
|
||
</table>
|
||
|
||
<h2>2. 全20原則 — 証拠ベース判定</h2>
|
||
|
||
<h3>コンテキストエンジニアリング（1〜6）</h3>
|
||
<table>
|
||
<tr><th>#</th><th>原則</th><th>判定</th><th>根拠</th></tr>
|
||
<tr><td>1</td><td>コンテキストは有限の注意予算</td><td class="ok">適合</td><td><code>ContextManager</code>が実usageからトークン追跡＋閾値アクション（context-manager.ts / context-control.ts）</td></tr>
|
||
<tr><td>2</td><td>文脈はジャストインタイムで引く</td><td class="ok">適合</td><td><code>ReadToolDoc</code>遅延ロード（docs.ts:110）＋1行ツールカタログ自動注入（prompt.ts:290）＋skill index＋Read offset/limit</td></tr>
|
||
<tr><td>3</td><td>コード実行で中間データ処理</td><td class="ok">適合</td><td>Bash（core.ts:807, cwd＝WS・パス検証）＋スクリプト作業をprompt自動推奨（prompt.ts:157）＋RunUserScript＋MCP</td></tr>
|
||
<tr><td>4</td><td>サブエージェント＝文脈汚染の隔離</td><td class="ok">適合</td><td>隔離型<code>delegate</code>（独立Conversation, 結果のみ返却）と並列型<code>SpawnSubTask</code>が別々に実装</td></tr>
|
||
<tr><td>5</td><td>長タスクは3戦略を使い分け</td><td class="ok">適合</td><td>圧縮／検索（task-conversation）／構造化ノート（MissionBrief）すべて実在</td></tr>
|
||
<tr><td>6</td><td>長文は文書冒頭・クエリ末尾</td><td class="ok">適合</td><td><code>Conversation.seed</code>: index0=system(preamble+guidance)、index1=user(タスク本文)。参照材料が先・クエリが後</td></tr>
|
||
</table>
|
||
|
||
<h3>ツール設計・ACI（7〜12）</h3>
|
||
<table>
|
||
<tr><th>#</th><th>原則</th><th>判定</th><th>根拠</th></tr>
|
||
<tr><td>7</td><td>ツール設計は一次作業</td><td class="ok">適合</td><td>1文description＋<code>docs/tools/*.md</code>39本の二層設計。CLAUDE.md/maintenance-checklistに明文規律。※記事の絶対パス推奨は不採用（有害）</td></tr>
|
||
<tr><td>8</td><td>タスクの自然な単位</td><td class="ok">適合</td><td>SplitExcelSheets/delegate/BrowseWeb(batched actions)/CreateChecklist 等、薄いラッパーでなくワークフロー単位。今回tool-dispatcher分割で内部の関心分離も改善(#702)</td></tr>
|
||
<tr><td>9</td><td>人間が即答できる粒度</td><td class="part">部分適合<br>（記事が正しい）</td><td><strong>89ツール</strong>と多い。重複クラスタ: delegate/SpawnSubTask/WaitSubTask、WebFetch/BrowseWeb/InteractiveBrowse/BrowseWithSession、ssh/ssh-console、Read系。allowed_tools/META_TOOLSで提示は絞るが棚卸し価値あり</td></tr>
|
||
<tr><td>10</td><td>応答識別子は自然言語名</td><td class="ok">適合</td><td>WS相対パス（savedRelPath等）、サブタスク#N、checklist item_id、browser ref(e1/f1.e3)、comment:<id>/transcript:<index>。不透明UUIDをLLMに晒さない</td></tr>
|
||
<tr><td>11</td><td>エラー応答は改善指示</td><td class="ok">適合</td><td>invalid transition→有効な遷移先列挙、Read binary→Bashでの確認手順、大出力→Grep/offset提案 等。弱点: Edit old_string not found／SSH command rejected は原因のみ</td></tr>
|
||
<tr><td>12</td><td>現実的複雑度で評価</td><td class="part">部分適合</td><td>bench 5軸100点＋LLM-judge、composite-mini-reportは3ソース融合・現実的。<strong>だがbenchタスクが2本のみ</strong>。89ツールの大半は未網羅（unitテスト46本で部分補完）</td></tr>
|
||
</table>
|
||
|
||
<h3>ワークフロー選択・プロンプト・運用（13〜20）</h3>
|
||
<table>
|
||
<tr><th>#</th><th>原則</th><th>判定</th><th>根拠</th></tr>
|
||
<tr><td>13</td><td>事前特定でWF/Agentを選ぶ</td><td class="ok">適合</td><td>ハイブリッド: movementグラフは静的（rules[].next、終端値はlint拒否 piece-runner.ts:92）、movement内はReActエージェント（最大200反復）</td></tr>
|
||
<tr><td>14</td><td>並列価値がコストを上回る時だけ</td><td class="ok">適合</td><td>depth=2上限＋直列delegate＋research.ymlのopt-in判断基準</td></tr>
|
||
<tr><td>15</td><td>ルール列挙より3〜5例</td><td class="part">部分適合</td><td>chat/research/ssh-opsに具体テンプレ・few-shotあり。ただし一部はまだルール列挙。例示ファーストに寄せる余地</td></tr>
|
||
<tr><td>16</td><td>指示に理由を添える</td><td class="ok">適合</td><td>ssh-ops「ローカルで回避してはいけない」「MITM疑い→自動リトライしない」等の理由付き。<code>why_no_default</code>必須フィールドで構造的にも強制</td></tr>
|
||
<tr><td>17</td><td>重要境界は機械的ブロック</td><td class="ok">適合</td><td><code>getToolDefs</code>がallowed_tools外を提示しない＝フィルタで強制。editフラグ、rules終端値lint、SSH allowlist。（記事はCLAUDE.md混同のカテゴリ違い）</td></tr>
|
||
<tr><td>18</td><td>CLAUDE.mdは200行未満</td><td class="ok">適合(runtime)</td><td>製品ランタイムは<code>MISSION_TOTAL_CHAR_BUDGET=3200</code>で切詰め。リポジトリCLAUDE.md 277行はClaude-Code向けの軽微なnitで製品所見ではない</td></tr>
|
||
<tr><td>19</td><td>検証コマンドで完了定義</td><td class="ok">適合</td><td><code>vitest run</code>／<code>npm run bench</code>／<code>validate-help-docs.mjs</code>／Stopフック（changelog警告）</td></tr>
|
||
<tr><td>20</td><td>同じ修正2回でリセット</td><td class="ok">適合</td><td>Progressive Pressure＋連続再訪ABORT(loop_detected)＋toolLoopTracker＋context force_transition＋text-only上限。カウントは管理されている</td></tr>
|
||
</table>
|
||
|
||
<h2>3. 実質的な改善余地（コード実測で残った3件）</h2>
|
||
<p>記事の「優先改善トップ5」のP0（CLAUDE.md肥大化・トークン予算未実装）は前提が誤りのため除外。実測で残る改善余地は次の通り。</p>
|
||
<table>
|
||
<tr><th>優先</th><th>改善点</th><th>原則</th><th>根拠</th></tr>
|
||
<tr><td><span class="pri p1">P1</span></td><td><strong>ツール棚卸し・統合</strong>。89ツールを「人間が1秒で使い分けを言えるか」で監査し、重複クラスタ（サブエージェント3種／ブラウザ4種／SSH2系統）を整理・description明確化。CLAUDE.mdのツール表も実態と乖離（棚卸し漏れの症状）</td><td>8,9</td><td>実測89ツール、重複4クラスタ特定</td></tr>
|
||
<tr><td><span class="pri p2">P2</span></td><td><strong>bench網羅の拡充</strong>。現在2タスクのみ。主要ツール群を現実的タスクで評価する bench を追加</td><td>12</td><td>bench/tasks/ に2本のみ</td></tr>
|
||
<tr><td><span class="pri p3">P3</span></td><td>細部: (a) pieceの一部ルール列挙を例示に寄せる（15）、(b) Edit/SSHの一部エラーに次の一手を追記（11）</td><td>11,15</td><td>該当箇所を特定済み</td></tr>
|
||
</table>
|
||
|
||
<h2>4. 総評</h2>
|
||
<p>
|
||
MAESTROは、記事が「基礎はある」とした以上に、20原則の<strong>大部分を既に実装済み</strong>である — トークン予算管理、JITコンテキスト、隔離型サブエージェント、3層ループ検出、機械的ツールゲート、char-budget化された実行時プロンプトは、いずれもコードに実在する。記事の否定的評価の多くは、コードを読まずアーキテクチャ要約から推測したことによる事実誤認だった。
|
||
</p>
|
||
<p>
|
||
唯一、記事が正しく指摘し実測でも残るのは<strong>ツールカタログの肥大（原則9）と評価網羅（原則12）</strong>である。特に89ツールという規模は「人間が使い分けを即答できる」水準を超えており、重複クラスタの統合が最も費用対効果の高い改善となる。
|
||
</p>
|
||
|
||
<hr style="margin:2em 0; border:none; border-top:1px solid var(--line);">
|
||
<p class="note">
|
||
トレーサビリティ: 本評価は 2026-07-01 に <code>origin/main</code>(be4e98d7) の全ソースを3チームで横断監査した結果。各判定は該当 <code>file:line</code> を根拠とする。元記事の評価は本番コードへのアクセスなしに書かれており、本書はそれを実測で全面的に置換したもの。<br>
|
||
設計と実装の差分: 元記事の「⚠️不明」20項目中17項目が「実装済み・適合」と判明。すなわち<strong>設計意図（原則）と実装は大きく乖離しておらず、乖離していたのは記事の推測と実コードの間</strong>だった。
|
||
</p>
|
||
|
||
</body>
|
||
</html>
|