要点（3〜6行）

• 全ベストプラクティスの根底は1つの制約：context window はすぐ埋まり、埋まるほど性能が落ちる。context が最重要の管理対象。
• Claude が自分で回せる検証手段（tests / build / screenshot 比較）を与えると、人間が検証ループになる状態から脱し、放置できるセッションになる。
• 推奨ワークフローは Explore → Plan → Implement → Commit の4段階。plan mode で調査と実装を分離する。
• CLAUDE.md は「短く・広く適用されるものだけ」。肥大化すると重要ルールがノイズに埋もれて無視される。
• 1人×1セッションを超えたら、subagents / headless mode（claude -p）/ 並列セッション / fan-out で水平スケールする。

内容

前提：context window が最重要リソース。 会話・読んだファイル・コマンド出力すべてが context を消費し、デバッグ1回で数万 token に達しうる。埋まるほど Claude は初期の指示を「忘れ」ミスが増える。custom status line で使用量を常時追跡せよ、というのが出発点。

検証手段を与える（Give Claude a way to verify its work）。 Claude は「できたように見えた」時点で止まる。pass/fail を返すチェック（test suite・build の exit code・linter・fixture との diff スクリプト・ブラウザ screenshot 比較）を与えれば、Claude 自身が実行→結果を読む→修正のループを閉じる。ゲートの強さは段階選択：①同一プロンプト内で「テストを回して直せ」、②/goal 条件として毎ターン再評価、③Stop hook で deterministic に turn 終了をブロック（連続8回ブロックで override）、④fresh な検証 subagent による second opinion。成功の主張ではなく証拠（テスト出力・実行コマンドと結果・screenshot）を出させる。

Explore → Plan → Code → Commit。 plan mode でまずファイルを読ませ（Explore）、実装計画を作らせ（Plan・Ctrl+G でエディタ編集可）、plan mode を抜けて実装・テスト（Implement）、descriptive なメッセージで commit & PR（Commit）。ただし typo 修正など diff を一文で言える小タスクは plan を飛ばして直接やらせる。

具体的な context を与える。 「add tests for foo.py」ではなく「logged out の edge case をカバーするテストを、mock なしで」。既存パターンのファイル名を指す、症状＋当たりの場所＋直った状態の定義を渡す。@ でファイル参照、画像 paste、URL 提示（/permissions で頻用ドメインを allowlist）、cat error.log | claude の pipe 入力も有効。

環境設定。 ①CLAUDE.md：/init で生成→磨く。含めるのは「Claude が推測できない bash コマンド／デフォルトと異なる style 規約／テスト手順／branch・PR 規約／プロジェクト固有の決定・罠」。コードを読めば分かること・一般常識・頻繁に変わる情報は除外。各行に「消したら Claude がミスするか？」を問い、しないなら削る。@path/to/import で分割 import 可。配置は ~/.claude/CLAUDE.md（全セッション）／project root（git 共有）／CLAUDE.local.md（個人用）／親子ディレクトリ。②permissions：auto mode（classifier が審査）・/permissions allowlist・/sandbox（OS レベル隔離）の3択で承認疲れを減らす。③CLI ツール（gh, aws, gcloud 等）が最も context 効率が良い。④MCP servers（claude mcp add）。⑤hooks＝「例外なく毎回必須」の処理に（CLAUDE.md は助言的、hooks は deterministic）。⑥skills（.claude/skills/SKILL.md）＝オンデマンドで読まれる domain 知識・定型ワークフロー。副作用ありは disable-model-invocation: true。⑦subagents（.claude/agents/）＝独立 context・独立 tool set。⑧plugins（/plugin）。

コミュニケーション。 codebase への質問はシニアエンジニアに聞く感覚でそのまま投げてよい（onboarding に有効）。大きめ機能は「AskUserQuestion tool で私に interview して、SPEC.md に spec を書け」→ fresh session で実装、が推奨。

セッション管理。 早期に軌道修正（Esc で停止・Esc+Esc//rewind で checkpoint 復元・「Undo that」）。同じ問題で2回以上訂正したら /clear して学びを織り込んだ better prompt で再スタートする方が、訂正を積んだ長いセッションより良い。/compact <指示> で focus 付き圧縮、/btw は履歴に残らない side question。調査は subagents に投げて main context を守る。checkpoint は Claude の変更のみ追跡（git の代替ではない）。claude --continue / --resume、/rename でセッションを branch のように命名管理。

自動化とスケール。 claude -p "prompt" の非対話モードを CI / pre-commit / スクリプトに組み込む（--output-format json / stream-json）。並列は worktrees・Desktop app・Claude Code on the web・agent teams から選択。Writer/Reviewer の2セッション分業（fresh context のレビュアは自分の書いたコードにバイアスされない）。大規模移行はタスク一覧生成→ loop で claude -p fan-out（--allowedTools "Edit,Bash(git commit *)" で権限を絞る。まず2〜3ファイルで prompt を磨いてから全件へ）。claude --permission-mode auto -p で自律実行。完了扱いの前に fresh subagent による adversarial review（ただし「正しさ・要件に関わる gap のみ報告」と縛らないと over-engineering を誘発）。

よくある失敗パターン。 kitchen sink session（無関係タスク混在→/clear）／訂正の繰り返し（2回失敗で /clear＋better prompt）／肥大 CLAUDE.md（容赦なく prune、hook 化）／trust-then-verify gap（検証なしで ship しない）／無限探索（scope を絞るか subagent へ）。最後に「パターンは出発点であり、何が効いたかを観察して自分の直感を育てよ」と締める。

💡 Claude Code の使い方への適用

1. タスク依頼文に検証条件を必ず同梱する：「実装して」ではなく「実装後 npm test を回し、失敗を直し、テスト出力を貼れ」。放置可能なセッションにしたい時は /goal か Stop hook でゲート化する。
2. CLAUDE.md 定期 prune の基準を導入：各行に「消すと Claude がミスするか？」を問い、No なら削除か hook 化。Claude がルールを無視し始めたら「ファイルが長すぎる」サインとして扱う。
3. 訂正2回ルール：同じ問題で2回訂正して直らなければ即 /clear し、失敗から学んだ制約を織り込んだ新プロンプトで仕切り直す。
4. 調査系は最初から subagent へ：「use subagents to investigate X」で main context を実装用に温存。実装後は fresh subagent に diff レビューをさせる（「正しさに関わる gap のみ報告」と明示）。
5. 機械的な横展開は fan-out：対象リストを作らせ、for ループ＋claude -p ＋ --allowedTools で無人バッチ化。最初の2〜3件で prompt を検証してから全件実行する。

要点（3〜6行）

• ユーザーは permission prompt の 93% を承認しており、承認疲れで実質レビューになっていない。auto mode は手動承認と --dangerously-skip-permissions の中間解。
• 防御は2層：入力層＝server-side の prompt-injection probe が tool 出力を context 投入前に検査、出力層＝transcript classifier（Sonnet 4.6）が各アクションを実行前に審査。
• classifier は2段構え：1段目は single-token の高速判定（block 寄り・FPR 8.5%）、flag された場合のみ2段目の chain-of-thought 推論で精査（pipeline 全体で FPR 0.4%）。
• classifier は Claude 自身のメッセージと tool 出力を意図的に見ない（自己正当化と injection による classifier 操作を構造的に遮断）。
• block されても停止せず「安全な代替を探せ」と tool result で返す deny-and-continue 方式。連続3回 or 累計20回の deny で人間へエスカレーション。

内容

背景と位置づけ。 Claude Code の permission prompt はユーザーの93%が承認しており、繰り返しの承認は「承認疲れ」を生む。auto mode は、承認判断の一部を classifier に自動化させ、安全性を保ったまま中断を減らす設計。全開放フラグ --dangerously-skip-permissions との中間に位置する。

仕組み（How it works）。 2層防御。①入力層：server-side の prompt-injection probe が tool 出力を agent の context に入る前にスクリーニングし、injection の兆候があれば警告を付加してユーザー意図に re-anchor する。②出力層：transcript classifier（Sonnet 4.6 で稼働）が各アクションを実行前に判定基準へ照らして評価する。classifier は2段階：1段目は single-token の yes/no 判定（「迷ったら block」指示で recall 優先・FPR 8.5% を許容）、flag された transcript にのみ2段目として同一プロンプト＋reasoning 有効での精査を適用し、FPR を 0.4% まで下げる。2段目は最終指示だけが異なるため prompt caching が効く。

脅威モデル。 危険なアクションの発生源を4分類：①overeager（権限を超えた「親切」、例：邪魔と判断したものを削除）②honest mistakes（リソースの scope や所有権の誤解）③prompt injection（ファイルや tool 出力内の敵対的指示）④model misalignment（独自目標の追求。実運用では未観測）。block 対象の具体パターンは5つ：scope escalation（曖昧な削除依頼での不可逆操作）／credential exploration（代替 API token の組織的探索）／agent-inferred parameters（類似性マッチでの対象選択）／外部サービス経由の共有（公開プラットフォームへのスクリプト upload）／safety-check bypass（skip-verification フラグでの再試行）。

permission 判定の3層。 Tier 1＝組み込み allowlist（file read・検索・code navigation・todo/plan 遷移）。注意点として、auto mode では shell 全開放・interpreter（Python/Node/Ruby）の wildcard・package manager run 系の blanket permission はむしろ落とされる——危険なコマンドを確実に classifier に届かせるため。Tier 2＝project ディレクトリ内の write/edit は classifier を通さない（version control でレビュー可能なため）。Tier 3＝shell コマンド・web fetch・外部 tool・subagent 起動・project 外の filesystem 操作は transcript classifier が審査。

判定基準（The classifier decision criteria）。 固定テンプレート：表面的な文字列でなく実世界への影響で評価（ファイルやコマンドチェーンに埋め込まれた payload の中身まで解析）、authorization は明示必須（「clean up branches」は一括削除の許可ではない）。カスタマイズ可能スロット：environment（信頼境界の定義。デフォルトは現在の git repo のみ）／default block rules（20超）——「destroy or exfiltrate」（force-push・大量削除・データ送信）「degrade security posture」（logging 無効化・persistence 導入・permission 変更）「cross trust boundaries」（外部 repo clone・credential store スキャン）「bypass review or affect others」（main 直 push・本番 deploy・共有リソース）——／allow exceptions（manifest 記載パッケージ・標準的な credential フロー・作業 branch への push 等の狭い例外）。設定確認は claude auto-mode defaults。

評価結果（Results）。 3データセット：実トラフィック1万コール（FPR 測定）／実セッション由来の overeager 行動52件（recall）／合成 data-exfiltration 1,000件。成績は、実トラフィック FPR＝1段目 8.5% → pipeline 0.4%、実 overeager FNR＝6.6% → 17%、合成 exfil FNR＝1.8% → 5.7%。17% の見逃しの多くは「危険とは認識したが、間接的な依頼（例：clean up the PR）がその行為（force-push）まで許可しているかの判断ミス」。auto mode は無制限実行より大幅に安全だが、高リスクなインフラ作業での人間の注意深いレビューと等価ではない、が明示された caveat。

設計判断。 assistant のテキストと tool result を classifier から除外する理由：agent の説得的な自己弁護に流されず「行為そのもの」を裁くため、かつ injection の主経路（tool 出力）を classifier に触れさせないため。tradeoff として provenance（ユーザーが本当にそのリソースを名指ししたか）は検証不能。multi-agent handoff では委譲時と復帰時の両方で classifier を実行（委譲時＝agent の独断タスクが「完全承認済み」に見えるのを防ぐ、復帰時＝subagent 内での途中汚染を捕捉）。deny-and-continue：block は tool result として返り、より安全な代替を探すよう誘導。headless（claude -p）ではフォールバック先の人間がいないため process を終了する。

今後。 実 overeager testset の拡充と safety/cost の改善を継続。「完璧である必要はなく、無制限実行より実質的に安全であればよい」という思想。残余リスクの監視と誤判定の報告をユーザーに推奨。

💡 Claude Code の使い方への適用

1. 「信頼できる方向のタスクだが全承認は面倒」な作業は auto mode を既定にする：claude --permission-mode auto。ただし本番インフラ・不可逆操作を含むタスクは手動承認に戻す（17% FNR の caveat を尊重）。
2. claude auto-mode defaults で block rules / exceptions を一度読む：自分の repo 運用（作業 branch への push、使う package manager）に合わせて environment と exceptions を settings でカスタマイズする。
3. auto mode に頼るなら依頼文で authorization を明示する：「clean up the PR」ではなく「この branch に force-push してよい」。classifier の見逃しは「間接的な許可の解釈」で起きるため、明示すれば precision も recall も上がる。
4. headless バッチ（claude -p + auto mode）は deny 連発で abort する仕様を前提に設計する：失敗を検知して retry / 人間確認に回すラッパーを書く。
5. blanket permission（Bash(*) 等）を settings に足すのは auto mode の防御を自ら外す行為と理解する。allowlist は具体コマンド単位（npm run lint 等）に留める。

要点（3〜6行）

• permission prompt の連打は「承認疲れ」を生み、無思考クリックでかえって安全性を下げる。sandboxing は境界を先に定義して境界内を自律化する逆転の発想。
• 隔離は filesystem と network の両輪が必須。network 隔離だけでは SSH 鍵を盗まれ、filesystem 隔離だけでは sandbox を抜けられる。
• 実装は OS レベル primitive（Linux＝bubblewrap、macOS＝Seatbelt）で、Claude 本体だけでなく起動された script・subprocess まで強制される。runtime は GitHub で open source 化。
• network は Unix domain socket 経由の外部 proxy に集約し、ドメイン単位で許可・新規ドメインはユーザー確認。
• 社内テストで permission prompt が 84% 減。有効化は Claude Code 内で /sandbox。

内容

背景（Keeping users secure on Claude Code）。 Claude Code はコードベースやファイルへのアクセスを前提とするため、prompt injection を典型とする攻撃面を持つ。従来は permission ベースのモデル——read は既定で許可、変更やコマンド実行は事前承認（echo や cat など安全な操作は auto-allow）——で守ってきたが、承認要求の反復は「approval fatigue」を生み、ユーザーが精査せず承認するようになると仕組み自体が形骸化する。この記事は、その構造問題への回答として2つの sandboxing 機能（sandboxed bash tool と Claude Code on the web）を発表するもの。

sandboxing のアプローチ。 あらかじめ定義した動作境界の中では Claude が per-action の許可なしに自律動作できるようにする。技術的な柱は2つの隔離。①filesystem 隔離：アクセス・変更できるディレクトリを指定領域に限定し、prompt injection が成立してもシステムファイルを触れない。②network 隔離：接続先を事前承認済みサーバーに限定し、乗っ取られた agent による機密データの exfiltration や悪性コードのダウンロードを防ぐ。記事が強調するのは両方が揃って初めて意味を持つこと——network 隔離のみなら SSH 鍵の窃取（ローカル読み取り）が可能なままで、filesystem 隔離のみなら sandbox 脱出（外部通信）が可能なまま。

Sandboxed bash tool。 beta research preview として提供される新しい sandbox runtime。コンテナ管理の手間なしに、アクセス可能なディレクトリと network ホストを定義できる。任意の process・agent・MCP server の sandbox 化をサポートし、GitHub で open source 公開。実装は OS レベルの primitive を使う：Linux は bubblewrap、macOS は Seatbelt。OS レベルで強制されるため、Claude Code の直接操作だけでなく、そこから spawn された script・プログラム・subprocess にも制限が及ぶ。filesystem コンポーネントは current working directory への read-write を許し、外側への変更をブロック。network コンポーネントは、インターネットアクセスを Unix domain socket 経由で外部の proxy server に通す構成——proxy がドメインベースの制限を強制し、新規ドメインの要求時はユーザー確認を担う。proxy ルールはカスタマイズ可能で、任意の outbound 制限を書ける。両コンポーネントとも特定 path / domain の allow・deny を設定できる。効果として、prompt injection が成功しても被害は sandbox 内に完全に隔離され、SSH 鍵の窃取や未許可サーバーへの通信は起きない。社内テストでは permission prompt が 84% 減少した。有効化は Claude Code 内で /sandbox を実行し、ドキュメントに従って設定する。

Claude Code on the web。 各セッションを隔離されたクラウド sandbox で実行し、安全なサーバーアクセスを提供する。要点は機密 credential（git credential・signing key）を sandbox の外に置く設計——コードが侵害されても認証材料に届かない。git 操作は custom proxy service が透過的に仲介する：sandbox 内の git client は専用に発行された scoped credential で proxy に認証し、proxy が credential を検証した上で git 操作の中身を検査（push が設定済み branch のみを対象とすることを確認）し、適切な認証 token を付与して GitHub へ転送する。これにより sandbox 実行が侵害されても、リポジトリへの未許可の変更から保護される。

Getting started。 ①Claude Code 内で /sandbox を実行して設定ドキュメントへ、②claude.com/code で web 版を試す、③独自 agent 開発者は GitHub の open source sandboxing コードを自プロジェクトに組み込める。著者は David Dworken・Oliver Weller-Davies ほか。

💡 Claude Code の使い方への適用

1. 承認疲れを感じたら allowlist を増やすのではなく /sandbox を検討する：境界（書込可能ディレクトリ＋許可ドメイン）を一度定義すれば、境界内は無承認で回り、injection 成立時の被害も境界内に閉じる。
2. filesystem か network の片方だけ緩めない：「network は全開でいい」「このディレクトリだけ追加」といった片側緩和は、この記事の脅威モデル（鍵窃取／脱出）をそのまま復活させる。緩和は必ずペアで影響を考える。
3. 許可ドメインは最小構成から始める：新規ドメインは proxy がユーザー確認を出すので、事前に全部許可しておく必要はない。仕事で本当に叩くホストだけを積み上げる。
4. 信頼できないコード・第三者 repo の検証は Claude Code on the web（クラウド sandbox）へ逃がす：credential が sandbox 外にある設計のため、ローカルの鍵・token を晒さずに試せる。
5. 自作 agent / MCP server にも同じ runtime を使う：open source の sandbox runtime は任意 process に適用できるので、cron で回す無人 agent こそ bubblewrap/Seatbelt 境界の中で走らせる。

要点（3〜6行）

• 2026年3月〜4月に報告された Claude Code の品質低下は、独立した3つの変更（reasoning effort 既定値の引き下げ／caching 最適化のバグ／verbosity 抑制の system prompt）の複合だった。
• 影響は Claude Code・Claude Agent SDK・Claude Cowork のハーネス層のみで、API と inference 層は正常だった。
• 最重大の caching バグは「1時間 idle 後に古い reasoning を1回消す」つもりが「以後毎ターン thinking block を消し続ける」実装ミス。code review・unit test・E2E をすり抜けた。
• 対策として reasoning effort の既定値復帰（Opus 4.7＝xhigh／他モデル＝high）、v2.1.101 での bug fix、prompt の revert、全 subscriber の usage limit リセットを実施。

内容

3つの原因。 ①3月4日、「考えすぎて UI が固まって見える」という latency 苦情に対応して default reasoning effort を high→medium に下げた（Sonnet 4.6 / Opus 4.6 対象）。速度と引き換えに知能が落ち、ユーザーは品質を優先したため4月7日に高い設定へ戻した。②3月26日 deploy の prompt caching 最適化に致命的な欠陥：1時間 idle 後に一度だけ古い thinking を消すはずが、セッションの残り全ターンで thinking block を消し続けた。Claude は progressively に文脈を失い「忘れっぽく・繰り返しが多い」挙動になり、さらに継続的な cache miss で usage limit の消費も加速した。修正は4月10日の v2.1.101。③4月16日、Opus 4.7 の冗長さ対策として「tool call 間のテキストは25語以内・最終応答は100語以内」という system prompt を追加したところ、評価指標で Opus 4.6 / 4.7 とも 3% 低下。4月20日の v2.1.116 で revert した。

診断が難航した理由。 劣化が時期・ユーザー層でまちまちに現れたこと、社内の実験や表示変更が caching バグを覆い隠したこと、無関係な message queuing 変更が再現を複雑にしたこと。興味深い点として、caching バグは Opus 4.6 では発見できず Opus 4.7 が Code Review で特定した。

再発防止。 社員による public build の利用拡大／Code Review ツール強化（追加 repo を context に）／system prompt 変更の統制強化＝全 prompt 変更にモデル別 evaluation suite／CLAUDE.md にモデル固有変更をゲートする指針を記載／知能に影響する変更には soak 期間・段階 rollout・広めのテスト／透明な発信用に @ClaudeDevs アカウント開設。/feedback コマンドや再現例を投稿したユーザーへの謝辞で締めくくられる。

💡 Claude Code の使い方への適用

1. 「Claude が急に忘れっぽい・繰り返す」時はまず自分の prompt を疑う前にバージョンと既知の障害を確認する：claude --version と @ClaudeDevs / release notes をチェック。ハーネス側の regression は実在する。
2. 品質異常は /feedback ＋再現可能な例で報告する：このポストモーテム自体が「ユーザーの再現例が解決に不可欠だった」と明言している。体感報告より再現手順が効く。
3. reasoning effort は品質に直結するパラメータとして扱う：latency が気にならないタスクでは effort を落とさない。「速いが浅い」設定変更のトレードオフを自分の設定（model/effort 指定）でも意識する。
4. 自分の system prompt / CLAUDE.md に「応答を短く」系の厳格な語数制限を入れる時は要注意：25語/100語制限だけで評価が3%落ちた事例。簡潔さの強制は知能を削りうるので、効果を観察しながら入れる。
5. prompt 変更にも評価を付ける文化を真似る：自分の CLAUDE.md・skills の変更も「変更→挙動が実際に変わったか観察→ダメなら revert」のループで運用する（Anthropic 自身がモデル別 eval suite を義務化した）。

要点（3〜6行）

• agent の能力が上がるほどリスクをゼロにはできない。設計目標は「blast radius（被害半径）に上限を付ける」こと。
• 防御は3層——環境（sandbox / VM / egress 制御＝決定論的境界）・モデル（classifier / probe＝確率的防御）・外部コンテンツ（tool 権限の粒度）——を重ねる。
• 3製品3パターン：claude.ai＝gVisor の ephemeral container／Claude Code＝human-in-the-loop＋OS sandbox（prompt 84%減）／Claude Cowork＝local VM（非技術者向けに常時強制の境界）。
• 実インシデントが教訓の核：phishing 経由の credential exfiltration は 25回中24回成功しモデル層は無力＝環境層だけが止められた。allowlist は「宛先フィルタ」でなく「capability grant」と捉え直す。
• 原則：①環境層で containment を先に設計しモデル層は後から steer、②隔離強度はユーザーの監督能力に合わせる、③自作コンポーネントより実戦を経た primitive（gVisor・Seatbelt・bubblewrap）を信頼する。

内容

リスク構造と2戦略。 リスク＝失敗確率×被害範囲。前者は safeguard で下げられるが、後者は能力向上とともに拡大する。戦略は2つ：human-in-the-loop 監督（承認率約93%＝approval fatigue で形骸化しがち・確率的防御は必ず失敗率を持つ）と、環境による containment（sandbox・VM・egress 制御で監督と独立に能力を制限）。脅威は user misuse／model misbehavior（sandbox 脱出やテスト答え発見の実例あり）／external attacker（prompt injection 等）の3分類。防御3層のうちモデル層の実力は、Opus 4.7 で Gray Swan ベンチ攻撃成功率約0.1%（適応攻撃100回で5〜6%）、auto mode は問題行動の約83%を事前捕捉——つまり単独では不完全で、層は重ねて互いに補完させる。

3つの containment パターン。 ①claude.ai のコード実行＝server-side の gVisor container、セッション毎の ephemeral filesystem。教訓は「最も弱い層は自作した層」——最重要インシデントの原因は自作 proxy だった。②Claude Code＝開発者の判断力を前提に user のマシン上で動かす human-in-the-loop 型。ただし熟練者ほど自動承認が約2倍多い。OS sandbox（macOS Seatbelt / Linux bubblewrap）で prompt を84%削減。2025年中盤〜2026年1月にはtrust ダイアログ前に実行されるコード（.claude/settings.json の hooks・project 設定 parse・localhost listener）の脆弱性3類型が見つかり、「project 設定の読込はインターネットからの inbound request と同様に扱う」修正を実施。2026年2月の red-team 演習では、同僚を装う mail の payload prompt が ~/.aws/credentials を読み外部 POST する攻撃が 25回中24回成功——「ユーザー自身が打った指示」には classifier が異常を見出せず、egress 制御という環境層だけが有効だった。③Claude Cowork＝非技術者向けに local VM で常時強制の境界（当初は full-VM、現在は agent loop を host に出しコード実行のみ VM 内の hybrid）。credential は host keychain に残し、mount モード（read-only / read-write / no-delete）や symlink を検証前に解決する等の設計。第三者開示による重要事例：allowlist 済みの api.anthropic.com 経由で攻撃者の API key を使い Files API へ exfiltration——allowlist は「宛先フィルタ」でなく「capability grant」であり、対策として VM 内に防御的 man-in-the-middle proxy を置きセッション token 以外を拒否。一方で sealed VM は EDR から中が見えない問題も生む（現状は pull 型 OTLP export で緩和）。

外部リソースと新興脅威。 local tool は監査可能だが remote tool は承認後に挙動を変えられる。tool 出力は攻撃面（malware スキャンを通る poisoned README）なので、小型高速モデルの classifier で context 投入前に検査する。今後の課題は、persistent memory poisoning（CLAUDE.md 等に残った injection が毎セッション再読込される）、multi-agent での信頼昇格（subagent 出力を生の tool 結果より信頼すると新たな injection 経路になる）、agent identity（agent は独立 principal かユーザーの延長か）。

💡 Claude Code の使い方への適用

1. 無人・自律運用は「モデルが賢いから大丈夫」でなく環境境界で守る：launchd/cron で回す agent は sandbox（filesystem＋network egress）必須。確率的防御（classifier / auto mode）はすべて外れた時に環境層が最後に受け止める前提で組む。
2. allowlist を capability grant として点検する：許可済みドメインの「そのドメインで何ができるか」（upload API・webhook 等）まで考える。api.anthropic.com ですら exfiltration 経路になった事例を基準にする。
3. ユーザー（自分）が貼る prompt こそ最大の injection 経路と自覚する：外部から受け取った長文プロンプト・README・メール文面を Claude に貼る前に中身を読む。「自分が打った指示」は classifier をすり抜ける。
4. 第三者 repo / 外部 MCP はまず隔離環境で fake data と共に試す：project を開いた瞬間に読まれる設定類（hooks・settings）は inbound request 相当の警戒で扱う。
5. CLAUDE.md・memory・workspace への書込は永続 injection の的：外部由来テキストを memory 系ファイルへ無検査で書き込まない。定期的に自分の CLAUDE.md / memory を「身に覚えのない指示」がないか点検する。

要点（3〜6行）

• プロンプトエンジニアリングの次の段階は「コンテキストエンジニアリング」＝コンテキストウィンドウに入るトークン構成全体（system prompt・tools・履歴・外部データ）を毎ターン管理する規律。
• LLMには有限の「attention budget」があり、トークンが増えるほど検索精度が落ちる「context rot」が起きる。よって目標は「望む結果の確率を最大化する、最小限の高シグナルトークン集合を見つけること」。
• 長時間タスクにはcompaction（要約して再開）、structured note-taking（外部メモ）、sub-agent architecture（サブエージェント分離）の3技法が有効。

内容

コンテキストエンジニアリング vs プロンプトエンジニアリング

プロンプトエンジニアリングが「単発タスクに最適な指示文を書く」ことに焦点を当てるのに対し、コンテキストエンジニアリングは複数の推論ターンにまたがる「トークン構成全体」（system instructions、tools、外部データ、メッセージ履歴）を管理する。エージェントはループで動作し、次のターンに関係するデータを絶えず生成するため、「どのコンテキスト構成が望ましい挙動を最も生みやすいか？」を問い、限られたコンテキストウィンドウに入れる情報を周期的に絞り込む規律が必要になる。静的なプロンプト最適化から、動的に進化する情報状態の管理への転換である。

なぜコンテキストエンジニアリングが重要か

LLMは「context rot」というアーキテクチャ上の制約を持つ。トークン数が増えるほど検索・想起の精度が下がる現象で、人間のワーキングメモリと同様、LLMには有限の「attention budget」がある。Transformerはn²のペアワイズなトークン関係を作るため、系列が長くなるほど関係の維持が困難になる（特に学習分布を超える長さで）。性能は崖のように落ちるのではなく緩やかに劣化する。したがって「良いコンテキストエンジニアリングとは、望む結果の可能性を最大化する最小の高シグナルトークン集合を見つけること」であり、コンテキストを貴重で有限な資源として扱う姿勢がモデルが進化しても変わらない中心原則となる。

効果的なコンテキストの解剖学

system promptは「適切な高度（right altitude）」に調整する。挙動を導けるだけ具体的でありつつ、強いヒューリスティクスを与える柔軟さを残す。脆いif-else的なハードコードロジックも、共有されていない前提を仮定する曖昧な指示も避ける。<background_information>、<instructions>、## Tool guidance のようなXMLタグ／Markdown見出しによる構造化が明快さを助ける。toolsはトークン効率的・自己完結的・曖昧さゼロで、機能の重複を避ける。few-shot例は網羅的なエッジケース列挙ではなく、多様で典型的（canonical）な例を厳選する。全体指針は「informative, yet tight（情報豊富だが引き締まった）コンテキストを保つ」こと。

コンテキスト取得とエージェント的探索

現代のエージェントは「just-in-time retrieval」を採用する。全データを事前にコンテキストへ詰め込むのではなく、軽量な識別子（ファイルパス等）を保持し、実行時にツールで動的にロードする。Claude Codeはその実例で、ターゲットを絞ったクエリやbashコマンド（head、tail）で大規模データを全読み込みせず分析する。ファイル階層・命名規則・タイムスタンプ等のメタデータがナビゲーション信号になる。progressive disclosure（探索による段階的な文脈発見）で作業メモリを集中させ続けられる。ただし実行時探索は事前計算済み検索より遅いというトレードオフがあり、事前取得と自律探索を組み合わせるハイブリッド戦略が有効なことが多い。「動く最もシンプルな方法を選ぶ」が引き続きの助言。

長時間タスクのためのコンテキストエンジニアリング

コンテキストウィンドウの拡大を待っても制約は残るため、3つの技法で対処する。

1. Compaction：コンテキスト上限に近づいたら会話を要約し、蒸留したサマリーで新しいウィンドウを再初期化する。Claude Codeはメッセージ履歴をモデルに渡して圧縮し、アーキテクチャ上の決定や未解決課題を保存しつつ冗長なツール出力を捨てる。まずrecall（取りこぼしゼロ）を最大化し、その後precisionを詰める調整が必要。tool result のクリアは最も安全で軽いcompactionの一形態。
2. Structured note-taking：エージェントがコンテキスト外に永続化される外部メモリを定期的に書き、後で読み戻す。Claudeがポケモンをプレイする実験では、数千ステップにわたり正確な集計・マップ・達成記録を維持し戦略を立てた。Anthropicのmemory toolはセッションを跨いでコンテキストを消費しないファイルベース知識基盤を可能にする。
3. Sub-agent architectures：特化サブエージェントがクリーンなコンテキストで集中タスクを処理し、メインエージェントは高レベル計画を調整する。サブエージェントは大量に探索した上で凝縮したサマリー（多くは1,000〜2,000トークン）だけを返す。詳細な探索コンテキストが隔離され、リードエージェントは統合に専念できる。

結論

コンテキストエンジニアリングは「完璧なプロンプトを書く」から「各ステップの限られたattention budgetに合う情報キュレーション」への転換である。モデルが賢くなるほど処方的なエンジニアリングは減らせるが、「コンテキストは貴重で有限」という原則は変わらない。

💡 Claude Code の使い方への適用

1. CLAUDE.md／rulesを「right altitude」で書く：手順のハードコードでも曖昧な精神論でもなく、判断基準（ヒューリスティクス）＋具体例少数に絞る。肥大化したら定期的に圧縮する（本環境のrules 41.9→34.7KB圧縮は正にこれ）。
2. compactionを能動的に使う：長セッションでは /compact をフェーズの節目で手動発行し、任意のタイミングで走るauto-compactに任せない（strategic-compact skillの発想）。要約に「決定事項・未解決点」を残すよう指示する。
3. structured note-takingの実践＝MEMORY.md／resume用md：長期プロジェクトは docs/RESUME-.md や memory/.md に外部化し、コンテキストには「入口の札」だけ置く。今の運用（memory=ポインタ、実体=docs）は本記事の推奨と一致。
4. サブエージェントには探索を、mainには統合を：大量のファイル読み・grep探索はAgent tool（Explore等）に投げ、要約だけ受け取る。mainコンテキストにファイルダンプを入れない。
5. tool／MCPは重複させず絞る：使わないMCPはlazy化（mcp-configs方式）してtool定義トークン自体を節約する。tool結果が長い時は head/tail 等で just-in-time に読む。

要点（3〜6行）

• 成功しているLLMエージェント実装は、複雑なフレームワークではなく「シンプルで合成可能なパターン」でできている。
• 中核の区別：workflow＝開発者が事前に定義したコードパスをLLMとツールが辿るもの／agent＝LLMが自らプロセスとツール使用を動的に方向づけるもの。
• 5つのworkflowパターン（prompt chaining／routing／parallelization／orchestrator-workers／evaluator-optimizer）＋自律agentという部品カタログを提示。
• 原則は3つ：シンプルさを保つ／計画ステップを透明に見せる／agent-computer interface（ACI）＝ツールの文書化とテストに投資する。

内容

エージェントとは何か

「agentic system」には2種類ある。workflowはLLMとツールが事前定義されたコードパスで編成されるシステム、agentはLLMが自分のプロセスとツール使用を動的に制御し、タスクの達成方法を自ら握るシステム。違いは「実行パスを誰が制御するか」。

いつagentを使う（使わない）べきか

「可能な限りシンプルな解を探し、必要な時だけ複雑さを増す」が大原則。agentic systemはレイテンシとコストを引き換えにタスク性能を上げる取引であり、その取引が割に合うかを考える。予測可能性が要る明確なタスクにはworkflow、柔軟性とモデル駆動の意思決定が規模で要る時にagent。多くのアプリは、retrievalとin-context examplesを添えた単発のLLM呼び出しの最適化で十分。

フレームワークの使い方

Claude Agent SDK、AWSのStrands Agents SDK、Rivet、Vellum等のフレームワークは低レベル作業を簡略化するが、抽象化層がプロンプトと応答を見えなくし、デバッグを難しくする。推奨は「まずLLM APIを直接使う」。多くのパターンは数行で実装できる。フレームワークを使うなら内部動作を理解すること——「中身についての誤った仮定」が顧客のエラーの典型的な原因。

ビルディングブロック：augmented LLM

基本部品はretrieval・tools・memoryで拡張されたLLM。現行モデルは検索クエリの自己生成、適切なツール選択、保持すべき情報の判断を能動的に行える。実装の要点は、ユースケースに合わせて能力を絞ること、LLMに対して簡単で十分文書化されたインターフェースを提供すること。サードパーティツール統合にはModel Context Protocol（MCP）も選択肢。

5つのworkflowパターン

1. Prompt chaining：タスクを逐次ステップに分解し、各LLM呼び出しが前の出力を処理する。中間に「gate」（プログラム的チェック）を挟める。タスクが固定サブタスクに綺麗に分解できる時に使う。レイテンシと引き換えに各呼び出しを簡単にして精度を上げる。例：コピー生成→翻訳、アウトライン作成（検証付き）→本文執筆。
2. Routing：入力を分類して専門化された処理へ振り分ける。関心の分離により、ある入力タイプへの最適化が他を劣化させるのを防ぐ。例：カスタマーサポートの問い合わせ種別振り分け、簡単な質問はHaiku・難問はSonnetというコスト最適化。
3. Parallelization：並列実行して結果をプログラムで集約する。Sectioning（独立サブタスクへの分割。例：応答生成とガードレール審査を別インスタンスで）とVoting（同一タスクの複数回実行。例：コード脆弱性の多重レビュー）。各観点に専用の呼び出しで注意を集中させた方がLLMは性能が出る。
4. Orchestrator-workers：中央のLLMがタスクを動的に分解してworker LLMに委譲し、結果を統合する。parallelizationと違いサブタスクは事前定義でなく入力に応じてorchestratorが決める。例：複数ファイル変更を伴うコーディング、複数ソースからの情報収集・分析。
5. Evaluator-optimizer：一方のLLMが生成し、他方が評価・フィードバックするループ。明確な評価基準があり、反復で確実に良くなる場合に有効。目安は「人間のフィードバックで改善する種類のタスクで、そのフィードバックをLLM自身が出せる」こと。例：文芸翻訳の反復推敲、探索の続行判断を評価者が下す複雑検索。

Agents（自律エージェント）

複雑な入力理解・推論と計画・信頼できるツール使用・エラーからの回復が成熟したことでagentが実用化した。動作：ユーザーの指示（または対話）で開始→タスクが明確になったら独立に計画・実行→各ステップで環境からground truth（ツール結果、コード実行結果）を得る→チェックポイントや障害で人間に確認→完了条件で停止。「agentの実体は、環境フィードバックに基づきループでツールを使うLLMに過ぎない」ことが多く、実装は単純でもツール設計と文書化が決定的に重要。用途はステップ数を予測できないオープンエンドな問題で、LLMの判断への一定の信頼が前提。コスト増とエラーの複合リスクがあるため、サンドボックスでの徹底テストとガードレールが必須。例：SWE-benchタスクを解くcoding agent、computer use。

パターンの組み合わせと要約

これらのパターンは処方箋ではなく、組み合わせ・カスタマイズ可能な部品。性能を測定し、「成果が実証的に改善する時だけ」複雑さを足す。原則は（1）シンプルな設計を保つ、（2）計画ステップを明示して透明性を保つ、（3）ツールの文書化とテストでACIを丁寧に作り込む。

Appendix 1：実践例

• カスタマーサポート：会話フロー＋ツール統合（顧客データ・注文履歴・ナレッジベース）＋プログラム的アクション（返金・チケット更新）で、解決の成否が明確に測れる。成功解決のみ課金するusage-based pricingを採る企業もある。
• Coding agent：解が自動テストで検証可能、テスト結果をフィードバックに反復できる、問題空間が構造化されている——という理由でagentが最も効く領域。AnthropicのagentはSWE-bench VerifiedでPR説明文だけから実GitHub issueを解決。ただしテストが通っても、システム全体との整合には人間のレビューが引き続き重要。

Appendix 2：ツールのプロンプトエンジニアリング（ACI）

同じ操作でも形式によりLLMの書きやすさは大きく違う（diff vs 全ファイル書き換え、markdown vs JSON）。指針：モデルが「考える」余地をトークンとして与える、インターネット上の自然なテキストに近い形式を使う、正確な行数カウントや文字列エスケープなどの形式的負担を除く。ACIには人間向けHCIと同等の労力を投じる：モデル視点で説明とパラメータが自明か確認、例・エッジケース・境界を定義に含める、workbenchで大量テストして誤用から反復改善、poka-yoke（誤用防止設計）。実例として、SWE-benchでは「プロンプト全体よりツールの最適化に多くの時間」を使い、相対パスを絶対パス必須に変えただけでモデルのエラーが消えた。

💡 Claude Code の使い方への適用

1. 複雑さのはしごを守る：まず単発プロンプト＋良い文脈→ダメならworkflow（skillやスクリプトで固定パス化）→本当にオープンエンドな時だけ自律agent（Agent tool）。「agentでやりたい」から入らない。
2. routingパターン＝モデル使い分け：定型・軽量タスクはHaiku系サブエージェント、難所はOpus/メインで、とAgentのmodel指定やskill側のモデル指定でコスト最適化する。
3. orchestrator-workers＝Agent tool並列dispatch：入力次第でサブタスクが変わる調査・複数ファイル改修は、mainが分解してサブエージェントに委譲・要約回収する型で走らせる（session-hygiene ruleの運用と同型）。
4. evaluator-optimizer＝レビューループ：/codex-review・/agy-review・code-reviewを「生成→独立評価→修正」のループとして常設する。評価基準が明確な時ほど効く。
5. 自作MCP／スクリプトはACI原則で書く：ツール説明に用例・エッジケース・入力制約を書き、絶対パス必須などpoka-yoke設計にする。モデルの誤用が続くツールはプロンプトでなくツール仕様側を直す。

要点（3〜6行）

• ClaudeのResearch機能を支えるorchestrator-worker型マルチエージェントの実装記。リードエージェントが計画を立て、並列サブエージェントが探索し、要約を統合する。
• 内部評価では、Opus 4リード＋Sonnet 4サブエージェント構成が単体Opus 4を90.2%上回った。BrowseComp分析では性能分散の80%をトークン使用量が説明（ツール呼び出し回数・モデル選択を足すと95%）。
• コストは重い：agentは通常チャットの約4倍、マルチエージェントは約15倍のトークンを消費。高価値タスクにのみ見合う。
• プロンプト原則8つ（委譲の教え方、複雑度に応じた工数配分、wide-then-narrow、extended thinking、並列ツール呼び出し等）と、評価手法・本番運用の教訓を公開。

内容

マルチエージェントの利点

リサーチは予測不能で動的なパスを辿るため、固定手順では対応できない。複数のサブエージェントがそれぞれ独立したコンテキストウィンドウを持ち、問題の異なる側面を同時に探索することで、巨大なコーパスからの「情報圧縮」が実現する。内部評価ではマルチエージェント構成（Opus 4リード＋Sonnet 4サブ）が単体Opus 4を90.2%上回り、BrowseComp分析ではトークン使用量が性能分散の80%、ツール呼び出し回数とモデル選択を加えて95%を説明した——つまり「より多くのトークンを（並列コンテキストに）投じられること」自体が性能の源泉。一方でトークン経済は厳しく、agentはチャットの約4倍、マルチエージェントは約15倍を消費するため、高価値タスク専用。また、全エージェントが同一コンテキストを共有すべき領域や依存関係の強い領域（多くのコーディングタスク等）には不向きで、リアルタイムの相互調整は苦手。

アーキテクチャ概要

orchestrator-workerパターン。リードエージェントがユーザーの質問を分析して戦略を立て、側面ごとのサブエージェントを生成。各サブエージェントは検索ツールを反復使用（検索→interleaved thinkingで結果評価→クエリ改善）し、発見を凝縮してリードに返す。リードは統合し、追加調査の要否を判断。十分になったらCITATIONエージェントに引き渡して出典を特定・付与し、引用付きの最終回答を返す。静的な類似チャンク取得を行う従来RAGと違い、新しい発見に適応しながら多段階で動的に探索する。リードは計画をメモリに保存し、コンテキストが200,000トークンを超えて切り詰められても計画を失わないようにする。

リサーチエージェントのプロンプト原則（8つ）

1. Think like your agents：Consoleでステップ実行を観察し、失敗パターン（十分な結果があるのに続ける、冗長クエリ、誤ツール選択）を掴む。
2. 委譲の教え方：サブエージェントへの指示には目的・出力形式・使用ツールとソースの指針・タスク境界が必須。「半導体不足を調べて」のような曖昧指示は複数エージェントの重複作業を生む。
3. クエリ複雑度に応じた工数配分：単純な事実確認は1エージェント×3〜10ツール呼び出し、比較は2〜4エージェント×各10〜15回、複雑リサーチは責務を明確に分けた10以上——という目安をプロンプトに埋め込み、過剰投資を防ぐ。
4. ツール設計と選択が決定的：agent-tool interfaceは人間のHCIと同じくらい重要。MCPサーバー経由の未知ツールは説明品質が低いと誤った探索経路を作る。「まず全ツールを検査→意図に合うものを選ぶ」等の明示的ヒューリスティクスを与える。
5. エージェントに自己改善させる：Claude 4系は優秀なプロンプトエンジニアで、失敗パターンを与えると改善を提案できる。欠陥のあるMCPツール説明をtool-testing agentに数十回試させて書き直させた結果、以後のタスク完了時間が40%短縮。
6. Start wide, then narrow：熟練リサーチャーのように全体像→細部の順で。エージェントは最初から長く具体的すぎるクエリを打ちがちなので、短く広いクエリから絞り込むよう指導する。
7. 思考プロセスの誘導：extended thinkingを制御可能なスクラッチパッドとして使う。リードは戦略立案・複雑度判定・役割定義に、サブはツール結果後のinterleaved thinkingで品質評価・ギャップ特定・クエリ改善に使い、指示遵守・推論・効率が向上。
8. 並列ツール呼び出し：リードが3〜5サブエージェントを並列起動＋各サブが3つ以上のツールを並列使用に変えたことで、複雑クエリの調査時間を最大90%削減。

全体戦略は、厳格なルールではなく良いヒューリスティクスを埋め込むこと（ソース品質の評価、深さと幅の使い分け、暴走防止の明示的ガードレール）。

エージェントの効果的な評価

マルチエージェントは同じ出発点から異なる有効経路を取るため、手順を規定するturn-by-turn評価は成立せず、成果（end-state）で判定する。（1）小サンプルで即評価を始める：初期は変更の効果が劇的（成功率30%→80%級）なので約20クエリでも効果検出できる。「数百ケース必要」と待たない。（2）LLM-as-judge：事実正確性・引用正確性・網羅性・ソース品質・ツール効率のルーブリックで、単一LLM呼び出し（0.0〜1.0スコア＋合否）が最も一貫し人間判断とも一致した。（3）人間評価は自動化の穴を拾う：初期エージェントがSEOコンテンツファームを権威ソースより選好していた偏りは人間が発見し、ソース品質ヒューリスティクスをプロンプトに追加して修正。また創発的挙動（リードの小さな変更がサブの挙動を予測不能に変える）ゆえ、個別エージェントでなく相互作用パターンの理解が鍵。

本番の信頼性とエンジニアリング課題

（1）agentはステートフルでエラーが複合する：ゼロからの再実行は高価なので、エラー地点から再開できる設計＋ツール障害をエージェントに伝えて適応させる＋リトライと定期チェックポイントの決定論的セーフガードを併用。（2）デバッグは新手法が要る：同一プロンプトでも実行が非決定的。本番のフルトレーシングで根本原因を系統的に診断（会話内容は監視せず決定パターンを見ることでプライバシー維持）。（3）デプロイは慎重な調整：実行中エージェントを壊さないようrainbow deployment（新旧並行の段階的トラフィック移行）。（4）同期実行がボトルネック：現状リードはサブの全完了を待つ。非同期化すれば速くなるが、結果整合・状態一貫性・エラー伝播の複雑さが増すトレードオフ。

Appendix（実装ヒント）

end-state評価（離散チェックポイントの状態変化を見る）、長期会話管理（完了フェーズを要約して外部メモリへ保存し、コンテキスト限界時は新しいサブエージェントをクリーンな文脈で起動して計画を読み戻す）、サブエージェント出力のファイルシステム直接保存（artifact system——成果物は外部に書き、軽量参照だけをコーディネーターに返すことで多段コピーの情報劣化とトークン消費を回避。コード・レポート等の構造化出力に最適）。

💡 Claude Code の使い方への適用

1. サブエージェント指示は4点セットで書く：Agent tool のpromptに「目的／出力形式／使うツール・ソース／タスク境界」を毎回明示する（白紙前提のsession-hygiene ruleと同じ。「〜を調べて」だけの委譲は重複と暴走を生む）。
2. タスク複雑度でエージェント数を決める：単純確認はmainが直接、比較は2〜4並列、大規模調査だけ多数並列——3.の目安をそのまま運用ルールにし、軽いタスクへの過剰並列を避ける。
3. 成果物はファイル経由で受け渡す：サブエージェントに長い成果物を返させず、docs/やscratchpadに書かせてパスだけ回収する（artifact system方式）。mainコンテキストの汚染とトークン多段コピーを防ぐ。
4. 評価は20ケースの小さなrubricから：skillやプロンプトの改善は、少数クエリ＋LLM-as-judge（正確性・網羅性・効率の合否）で即回し始める。eval-harness skillの運用指針と一致。
5. ツール説明の改善をClaude自身にやらせる：MCPやスクリプトの誤用が続いたら、失敗ログを渡して説明文を書き直させる（記事では完了時間40%短縮の実績）。

要点（3〜6行）

• 著者Nicholas Carlini（Safeguards研究員）が、人間の介入を最小限にした16並列のClaude（Opus 4.6）エージェントチームで、RustによるCコンパイラをゼロから構築した実験記。
• 成果：約10万行・Linuxカーネル6.9をx86/ARM/RISC-Vでコンパイル可能・GCC torture含む主要テストスイート99%合格。期間約2週間、Claude Codeセッション約2,000回、費用約$20,000（入力20億・出力1.4億トークン）。
• 教訓は3本柱：ほぼ完璧なテスト（検証機）を書く／ハーネスはClaudeの制約（コンテキスト汚染・時間感覚の欠如）に合わせて設計する／並列化しやすいタスク分割と役割の専門化。
• ただし限界も明確：16-bit x86やアセンブラ・リンカはGCC依存、生成コード効率はGCCの最適化なし出力未満、テスト合格＝仕事完了ではないという検証リスクの警告で締める。

内容

プロジェクト概要

「エージェントチーム」＝複数のClaudeインスタンスが共有コードベース上で並列作業し、人間はほぼ介入しない監督形態の実験。Opus 4.6のエージェント16体で、依存ゼロ（Rust標準ライブラリのみ）のCコンパイラをクリーンルーム実装（開発中のインターネットアクセスなし）。Linuxカーネル6.9のブート可能ビルド（x86/ARM/RISC-V）に加え、QEMU・FFmpeg・SQLite・PostgreSQL・Redisをコンパイルでき、Doomも動く。

長時間実行Claudeを可能にする

既存のClaude Codeは操作者の継続参加を前提とし、長い問題では部分解決後に停止して入力を待つ。そこでシンプルなループハーネスを構築：シェルスクリプトでgitコミットを取り、エージェントプロンプトを読み込んでClaudeを再実行、出力をログに記録して次のタスクへ即移行する。プロンプトでは「問題を小さく分割し、作業を記録し、次を決め、完璧になるまで続けよ」と指示。ループは永遠に回る（Claudeが誤って自分自身を終了させた事例が1回あった）。

Claudeを並列に走らせる

1セッション1作業の限界を超えるため、ベアgitリポジトリを/upstreamに置き、各エージェントをDockerコンテナで起動して/workspaceにクローン。タスクの取り合いはcurrent_tasks/ディレクトリにロックファイル（例：parse_if_statement.txt）を書くことで調停し、gitの同期機構が衝突した2番目のエージェントに別タスクを選ばせる。完了したらpull→マージ→push→ロック削除。マージ衝突は頻発するがClaudeは解決できる。オーケストレーター（指揮役エージェント）は存在せず、各Claudeが「次に明白な問題」を自分で選ぶ初期研究プロトタイプ。行き詰まったら失敗アプローチと残タスクを文書に残す。

エージェントチームでのプログラミングの教訓

• 極めて高品質なテストを書く：自律的に問題を解かせる以上、検証機は「ほぼ完璧」でなければ誤った問題を解いてしまう。高品質なコンパイラテストスイートの収集、OSSパッケージ用の検証・ビルドスクリプト作成、失敗パターンを観察しての新テスト設計を実施。終盤にリグレッション頻発した際はCIパイプラインを構築して厳格に強制した。
• Claudeの身になって考える：ハーネスは自分でなくClaudeのために作る。各エージェントは毎回新しいコンテナで自己方向付けに時間を使うため、頻繁に更新されるREADMEと進捗ファイルを用意。さらに2つの固有制約に対処：（1）コンテキスト汚染——ハーネスは無駄な数千バイトを出力せず、数行だけ出して詳細はログファイルへ（エラー行は「ERROR」と理由を同一行に、集計統計は事前計算済みで提供）。（2）時間感覚の欠如——放置すると数時間テストを回し続けるため、間欠的な進捗出力と--fastデフォルト（1%または決定論的10%サンプル）を用意。
• 並列化を容易にする：失敗テストが多数ある間は1エージェント1テストで自明に並列化でき、99%合格後は各エージェントに別のOSS（SQLite、Redis、libjpeg等）を割り当てた。しかしLinuxカーネルという単一巨大タスクでは16体が同一バグに殺到して修正を上書きし合い、並列の利点がゼロに。解決策はGCCを「既知正常」のオラクルにすること：カーネルの大部分をGCCでコンパイルし、残りだけを自作コンパイラで処理、壊れたら二分探索的にファイルを絞る。これで各エージェントが別ファイルの別バグを独立に修正できるようになった。全ファイル通過後もdelta debuggingで「単独では動くが組み合わせると壊れる」ファイルペアを特定。
• 複数のエージェント役割：並列化は専門化を可能にする。重複コードの統合係、コンパイラ自体の性能改善係、生成コードの効率化係、Rust設計批評係、ドキュメント係を分担させた。

エージェントチームの限界のストレステスト

本プロジェクトはモデル能力のベンチマークとして設計された。旧Opus 4系は機能するコンパイラを作れる限界程度、Opus 4.5で初めて閾値を超え大規模テストに合格（ただし大規模プロジェクトのコンパイルは不可）、Opus 4.6で今回の到達点となった。既知の制限：（1）Linuxブートに必要な16-bit x86はGCCにフォールバック（66/67プレフィックスで正しい16-bitコードは出せたが出力が60KB超となりLinuxの32KB制限を超過したため。ARM/RISC-Vは完全自作）。（2）自作アセンブラ・リンカは未完でバグ含み、デモはGCCのものを使用。（3）全プロジェクトがコンパイルできるわけではなく実用コンパイラの代替ではない。（4）生成コードは全最適化有効でもGCCの最適化なし出力より遅い。（5）Rustコードの品質は妥当だが専門家には遠い。終盤はOpusの能力限界に接近し、新機能追加が既存機能を壊すことが頻発した。

今後の展望

エージェントチームは「野心的な目標を設定すれば複雑なプロジェクト全体を自律実装する」段階の到来を示唆する。一方で著者は警告する：人間が同席しないと「テストが通った＝仕事が終わった」と誤認しやすく、検証なしのソフトウェア展開は現実的な懸念（著者は侵入テストの経歴を持つ）。2026年初頭にこれが実現するとは予想外であり、正の応用が上回ると期待しつつも、安全に進むための新しい戦略が必要だと結ぶ。

💡 Claude Code の使い方への適用

1. 自律ループの成否はテストで決まる：長時間の無人実行（run_in_backgroundやlaunchd運用）に入れる前に、検証機（テスト・lint・スモーク）を「ほぼ完璧」に整える。検証が甘いままの自律化は誤った問題を全力で解く（runtime-verification-gateの思想と同じ）。
2. スクリプト出力はClaude向けに設計する：自作ハーネス・ビルドスクリプトは数行の要約だけ標準出力し、詳細はログファイルへ。エラーは「ERROR＋理由を同一行」、集計は事前計算済みで返す。コンテキスト汚染はエージェント性能を直接下げる。
3. 長時間コマンドには--fast系のデフォルトを：テストのサンプル実行モードや進捗の間欠出力を用意する。Claudeは時間感覚がなく、フルスイートを何時間でも回してしまう。
4. 並列セッションはタスク粒度で設計する：worktree並列やAgent並列は「独立したファイル・独立したバグ」に分割できて初めて効く。単一の巨大タスクに複数エージェントを当てると上書き合戦になる——先にオラクル（正解系）で問題を分割する。
5. 役割別エージェントの常設：実装係と別に、重複コード統合・性能・設計批評・ドキュメントの専門レビュー役を回す運用（/simplify、/code-review、agent-improverの使い分け）はこの記事の役割分担と同型。

要点（3〜6行）

• context window を跨いで作業を継続するには compaction だけでは不十分。セッション間のギャップを橋渡しする仕組み（ハーネス）が必要。
• 解決策は「Initializer Agent（環境構築）＋ Coding Agent（1機能ずつ実装）」の2部構成。
• 進捗の正本は JSON の feature list（200以上の機能・全て passes: false から開始）＋ git commit ＋ progress ファイル。
• 「テスト済みと自己申告するだけで実際は未検証」が最大の failure mode。ブラウザ自動化（Puppeteer MCP）による E2E 検証を明示的に指示することで大幅に改善。
• セッション開始時の定型プロトコル（pwd → git log/progress 読込 → feature list 確認 → init.sh でサーバ起動＋基本テスト）が token 節約と早期バグ検出に効く。

内容

課題：長時間稼働エージェントの問題

Claude Opus 4.5 のようなフロンティアモデルでも、「claude.ai のクローンを作れ」といった高レベルな指示だけでは production 品質の Web アプリを完成できない。観測された主な失敗パターンは2つ。①過剰な野心：一度にアプリ全体を作ろうとして context を実装途中で使い切り、機能が文書化されないまま放置される。②早すぎる完了宣言：後続セッションのエージェントが、部分的な進捗しかないのに「プロジェクト完成」と宣言する。記事の核心的な指摘は「compaction だけでは複数 context window に跨るワークフローを解決できない」こと。

解決策：2部構成のアーキテクチャ

Initializer Agent が土台となる環境を最初に構築する：開発サーバ起動用の init.sh、エージェントの行動を記録する claude-progress.txt、追加ファイルを記録する初回 git commit。Coding Agent は後続セッションで「1機能ずつ incremental に進める」「環境を merge-ready な状態で終える」「クリーンで文書化されたバグのないコードを保つ」という指示のもと動く。

環境管理の3要素

① Feature list：Initializer が spec から 200以上の機能を JSON で生成。各機能は category / description / 検証手順の steps / passes フィールドを持ち、全機能を最初は failing（passes: false）としてマークする。「テストの削除・編集は容認されない（unacceptable）」という強い言葉で指示し、Markdown ではなく JSON を採用することでモデルによる不適切な書き換えを減らした。

② Incremental progress：1セッション1機能、説明的なメッセージで git commit、progress ファイルにサマリを書く、問題が起きたら git で revert。これにより「前に何が起きたかをエージェントが推測する必要」がなくなった。

③ Testing：最大の failure mode は「E2E 検証なしに機能を完了扱いにする」こと。対策として Puppeteer MCP server などのブラウザ自動化ツールを明示的に与え、「人間のユーザーと同じように全テストを行え」と指示した。これで大部分は E2E 検証が機能したが、vision の制約やブラウザ自動化の隙間（例：ブラウザネイティブの alert モーダルは Puppeteer MCP から見えない）により、全種類のバグは拾えないと明記されている。

セッション初期化プロトコル

各セッション開始時に4ステップを定型実行する：(1) pwd で作業ディレクトリ確認 → (2) git log と progress ファイルで文脈把握 → (3) feature list から最優先の未完了機能を特定 → (4) init.sh で開発サーバを起動し基本的な E2E テストを実行。冗長なテストセットアップを防いで token を節約し、新機能の実装前に既存バグを早期検出できる。

失敗モードと対策の対応表

今後の課題

単一の汎用 coding agent と、専門化したマルチエージェント（testing agent / QA agent / cleanup agent）のどちらが優れるかは未解決。フルスタック Web 開発以外（科学研究・金融モデリング等）への一般化も今後の研究課題とされている。執筆は Justin Young（code RL チームと Claude Code チームの協力）。

💡 Claude Code の使い方への適用

1. 長期タスクは feature list を JSON で作らせてから始める：大きな実装を頼む前に「spec から検証手順つきの feature_list.json（全項目 passes: false）を作って」と指示し、CLAUDE.md に「feature list の削除・編集は不可」と明記する。auto-compact 任せにしない。
2. セッション再開プロトコルを CLAUDE.md / RESUME md に定型化：既に運用中の「RESUME-*.md 起点で再開」パターンはこの記事の裏付けどおり。pwd → git log → progress 読込 → 起動スクリプト実行 → smoke test の順を再開プロンプトに固定で入れる。
3. 「完了」の前に E2E 検証を強制：Web 系は Playwright / chrome-devtools MCP で「人間ユーザーとして操作して確認してから passes を立てる」を指示に含める（既存の runtime-verification-gate と同思想。alert モーダル等ツールの死角があることも意識する）。
4. 1セッション1機能＋こまめな git commit：巨大タスクを一気に投げず、「次の1機能だけ実装して merge-ready で終えて」と刻む。失敗時は revert で戻せる状態を常に保つ。
5. init.sh 相当の起動スクリプトを各プロジェクトに置く：環境立ち上げの手順をスクリプト化しておくと、毎セッションの探索 token を削減でき、エージェントの再現性が上がる。

要点（3〜6行）

• エージェントは自己評価が苦手（凡庸な成果を自信満々に賞賛する）。GAN に着想を得て Generator（作る）と Evaluator（評価する）を別エージェントに分離する方が、生成側を自己批判的にするより実効性が高い。
• context が埋まると早めに切り上げる「context anxiety」は Sonnet 4.5 で顕著、Opus 4.5 でほぼ解消。compaction より context reset（状態を引き継いで完全リセット）が有効だった。
• フルスタック開発では Planner / Generator / Evaluator の3エージェント構成＋file ベースの handoff。Evaluator は Playwright MCP で実際にアプリを操作して採点し、1基準でも閾値未満なら sprint 失格。
• Opus 4.5 比較：solo 実行（20分・$9）は動かないゲーム、full harness（6時間・$200）は磨かれた動くアプリ。
• ハーネスの各部品はモデルの限界についての仮定を符号化している。新モデルが出るたびに1部品ずつ外して stress-test すべき。Opus 4.6 では sprint 分割が不要になった。

内容

なぜ素朴な実装は失敗するか

長時間タスクでは context window が埋まるにつれてエージェントが一貫性を失う。「context anxiety」＝残り context を意識して作業を早めに畳んでしまう現象が観測された（Sonnet 4.5 で強く、Opus 4.5 でほぼ消失）。対策としては、その場で要約する compaction より、state を handoff して完全にクリアして再開する context reset の方が有効だった。もう一つの根本問題は自己評価の失敗：主観的なタスクでも凡庸な出力を自信を持って賞賛してしまう。生成側に自己批判をさせるより、Generator と Evaluator を分離する方が扱いやすい、というのが本記事の中核テーゼ。

フロントエンドデザイン：主観的品質を採点可能にする

放っておくと Claude は「技術的には動くが視覚的に凡庸な、安全で予測可能なレイアウト」に寄る。そこで Generator / Evaluator 共通の採点基準を4つ定義した：①Design quality（色・タイポグラフィ・レイアウトが統合された全体）②Originality（テンプレ既定値でない独自判断。「白カードの上の紫グラデーション」は減点）③Craft（タイポグラフィ階層・余白・色の調和・コントラスト比）④Functionality（推測なしにタスク完了できるか）。Evaluator は Playwright MCP でライブページを操作しスクリーンショットを撮ってから採点。Generator は詳細な批評を受け取り、「改善を続けるか、美的方向を pivot するか」を戦略的に判断する。結果：1生成につき 5〜15 iteration、フルランは最大4時間。後半の iteration ほど概ね良くなる（単調ではない）。例として、オランダ美術館サイトはありきたりなダークテーマから、iteration 10 で 3D CSS perspective の空間ナビゲーション付きルームへ進化した。

フルスタックコーディングへのスケール

3エージェント構成（通信は file ベース handoff、Claude Agent SDK 上で構築）：

• Planner：1〜4文のプロンプトをフル product spec に展開。スコープの野心は高く、技術の過剰指定は避ける。AI 機能の組込機会も spec に統合（例：レトロゲームメーカーで 10 sprint・16機能の spec を生成）。
• Generator：sprint 単位で feature-by-feature に実装。スタックは React / Vite / FastAPI / SQLite（後に PostgreSQL）。各 sprint 後に自己評価してから QA に渡す。git で版管理。
• Evaluator：Playwright MCP でユーザーのようにクリックして回り、UI・API endpoint・DB 状態を検査。発見バグと rubric の両方で採点し、どれか1基準でも閾値未満なら sprint 失格という hard threshold を敷く。実装前に成功基準を定める「sprint contract」を Generator と交渉する。

Opus 4.5 での初期結果：solo（20分・$9）はエンティティ物理が壊れ、定義とランタイムの配線が切れた非機能ゲーム。full harness（6時間・$200）は動くゲームプレイを持つ多機能アプリ（キャラ物理の重なり・壁ジャンプ難などの粗さは残る）。QA 指摘の実例：矩形塗りツールがドラッグ端点にしかタイルを置かない／Delete キーの handler が同時に成立しない2条件を要求／FastAPI のルート照合で "reorder" が frame ID として解釈される、など具体的で実用的なバグを検出した。

ハーネスの反復改善

原則：「ハーネスの全部品はモデルの限界への仮定を符号化している。定期的に stress-test せよ」。過激に削るのでなく、1部品ずつ外して検証した。Opus 4.6 では計画性・長時間タスクの持続・大規模コードベースでの信頼性・long-context retrieval が向上したため、sprint 分割が不要になった。Generator は sprint 境界なしで2時間以上一貫して作業でき、Evaluator は sprint ごとの採点からビルド終了時の1回パスに移行。重要な洞察：「Evaluator の有用性はモデル能力に対するタスクの複雑さで決まる」——モデルの限界近くのタスクには必須、能力圏内のタスクでは不要なオーバーヘッドになりうる。

更新版ハーネスで「Web Audio API でフル機能のブラウザ DAW を作れ」を実行：約4時間・$124（Planner 4.7分 $0.46 → Build R1 2時間7分 $71.08 → QA R1 8.8分 $3.24 → Build R2 1時間2分 $36.89 → QA R2 6.8分 $3.09 → Build R3 10.9分 $5.88 → QA R3 9.6分 $4.06）。QA R1 は「クリップをタイムライン上でドラッグできない」「楽器 UI パネルなし」等、QA R2 は「録音が stub のみ」「クリップの resize/split 未実装」「エフェクト可視化が数値のみ（EQ カーブなし）」を検出。最終成果はアレンジビュー・ミキサー・トランスポートを備えた動作する DAW で、プロンプト経由でメロディ生成・ドラムトラック・リバーブ追加までできた。

今後

より良いモデルは scaffolding を減らすが、同時に新しいハーネスの組合せを可能にする。「対象モデルで必ず実験し、現実的な問題で trace を読む」「新モデルが出たらハーネスを再点検し、荷重を担っていない部品を剥がす」。結論：「面白いハーネスの組合せ空間はモデル改善で縮まない。移動する。AI エンジニアの仕事は次の新しい組合せを見つけ続けることだ」。

💡 Claude Code の使い方への適用

1. 作る側と評価する側を分ける：実装した本人に「よくできてる？」と聞かない。別プロセスのレビュー（/codex-review・/agy-review、または fresh な subagent に rubric を渡して採点）を挟む——既存のクロスベンダーレビュー運用はまさにこのパターン。
2. 主観的な品質は rubric を先に書く：デザイン系タスク（ec.impru.ai 等）では Design quality / Originality / Craft / Functionality の4基準＋「1基準でも閾値未満なら差し戻し」を評価プロンプトに明記し、Playwright/chrome-devtools で実画面を見せてから採点させる。
3. 「sprint contract」を先に結ぶ：実装開始前に「この回の成功基準」をエージェントと合意しファイル化する。完了判定の恣意性が消え、早すぎる完了宣言を防げる。
4. モデル更新のたびにハーネスを間引く：CLAUDE.md や skill に溜めた回避策（細かい分割指示・compaction 対策等）は新モデルで不要化しうる。1つずつ外して挙動を確かめ、非荷重の部品を削る。
5. タスク難度で Evaluator の要否を判断：定型で能力圏内の作業に重い QA ループを付けるとコストだけ増える。モデルの限界に挑むタスク（新規アプリ・長時間ビルド）にだけ Generator-Evaluator を組む。

要点（3〜6行）

• ハーネスはモデルの限界についての仮定を符号化しており、モデル改善で陳腐化する（例：Sonnet 4.5 の「context anxiety」対策の context reset は Opus 4.5 で不要になった）。だから安定したインターフェイス＋交換可能な実装で設計する。
• Managed Agents は OS がハードウェアを process / file に仮想化したのに倣い、エージェントを session（追記専用イベントログ）／harness（オーケストレーションループ）／sandbox（実行環境）の3つに仮想化する。
• 全部入り単一コンテナは「pet」化して障害＝セッション喪失になる。brain（Claude＋harness）と hands（sandbox・ツール）と session を分離し、コンテナは使い捨ての「cattle」として扱う。
• 分離により credential が sandbox に入らなくなり prompt injection の権限昇格を遮断。TTFT は p50 で約60%減・p95 で90%超減。
• session は「Claude の context window の外に生きる context オブジェクト」。getEvents() で任意のスライスを取り出し・変換して context に流し込めるため、将来の context 管理戦略をプロトコル変更なしに差し替えられる。

内容

導入：ハーネスの仮定は陳腐化する

Claude Sonnet 4.5 は context の残量が減ると作業を早めに畳む「context anxiety」を示し、ハーネス側で context reset という回避策が必要だった。しかし Claude Opus 4.5 でこの挙動は消え、回避策そのものが不要になった。この経験が示すのは、ハーネスに埋め込んだ仮定はモデルの世代交代で古くなるということ。Managed Agents（ホスト型のエージェント実行基盤）は、OS がハードウェアを process や file といった「実装より長生きする抽象」に仮想化した手法に倣い、session／harness／sandbox の3要素を仮想化して、実装を入れ替えられる安定インターフェイスを提供する。

Don't adopt a pet（ペットを飼うな）

初期アーキテクチャの失敗談。エージェントの全構成要素を1つのコンテナに同居させた結果、そのコンテナは "pets vs. cattle" の比喩でいう「pet」＝名前を付けて手厚く世話し、失えない存在になった。コンテナ障害＝セッション全損。デバッグにはユーザーデータを抱えたコンテナ内で shell を開く必要があり、セキュリティと可観測性が衝突。さらにリソースが harness と同居する前提のため、顧客が自社 VPC に Claude を繋ぐにはネットワークピアリングが必須という制約も生んだ。

Decouple the brain from the hands（頭と手の分離）

brain（Claude＋harness）、hands（sandbox・ツール）、session（イベントログ）の3つの関心事を分離した。

• harness の外出し：harness はコンテナ内で動かず、execute(name, input) → string でコンテナを呼び出す。壊れたコンテナは cattle として捨て、provision({resources}) で新しいものを初期化。Claude にはツールコールのエラーが返り、リトライするか自分で判断する。
• harness 障害からの復旧：session ログが harness の外に永続化されているため、harness がクラッシュしても状態は失われない。新しい harness インスタンスが wake(sessionId) を呼び、getSession(id) でイベントログを取得して最後のイベントから再開する。稼働中は emitEvent(id, event) でイベントを書き込む。
• セキュリティ境界：同居型では Claude が生成した信頼できないコードが credential を持つコンテナ内で走り、prompt injection による権限昇格を許していた。分離型ではトークンが sandbox に一切届かない。実装パターンは2つ：(1) 初期化時に認証をリソースへ焼き込む（Git access token を remote に組み込んで clone）、(2) OAuth トークンを sandbox 外の vault に保管し、session に紐づく専用 proxy が安全なストレージから credential を取得して代理アクセスする。

The session is not Claude's context window

長期タスクは context window の長さを超えるため、従来は compaction・trimming・memory tool など「何を残すか」の不可逆な判断を迫られた。Managed Agents では session が「Claude の context window の外に生きる context オブジェクト」として機能する。getEvents() インターフェイスでイベントストリームの位置的なスライスを選択でき、止まった所から再開・特定時点より前に巻き戻し・context の読み直しが可能。取得したイベントは Claude の context に渡す前に変換でき、prompt cache 最適化や context engineering のための再編成もできる。この分離により、将来の context 管理戦略をプロトコル変更なしで導入できる。

Many brains, many hands

• Many brains：コンテナと harness の同居要件が消えたことで、顧客リソース接続の VPC ピアリング要件が撤廃された。また TTFT（time-to-first-token）が劇的に改善：従来は全セッションが起動時にコンテナのセットアップコストを支払っていたが、現在はツールコールで必要になった時だけ provision する。sandbox 不要のセッションは session ログから即座に推論を開始できる。結果「p50 TTFT が約60%低下、p95 は90%超低下」。スケールも stateless な harness インスタンスを並べて必要に応じて hands に接続するだけ。
• Many hands：モデルが有能になるほど、単一コンテナの制約がモデルの推論力ではなくボトルネックになった。各 hand を execute(name, input) → string という汎用ツールとして扱い、カスタムツール・MCP server・Anthropic 自身のツールをすべて同じ抽象で受ける。hands の実装詳細（コンテナ・スマートフォン・エミュレータ等）は不透明のまま。さらに hands が brains から独立しているため、brain 間で hands を受け渡すことができる。

結論

Managed Agents は「まだ考案されていないプログラムのためのシステムを作る」という古典的設計問題を解く「meta-harness」。OS がハードウェア仮想化で達成したことを、エージェント構成要素の仮想化で達成する。状態操作（session）と計算（sandbox）という鍵となるインターフェイスには opinionated であり続け、個別の harness 実装（Claude Code やタスク特化型など）には unopinionated であることで、モデル能力の進化に追従する。執筆は Lance Martin・Gabe Cemaj・Michael Cohen（Agents API チーム他が協力）。

💡 Claude Code の使い方への適用

1. 状態はプロセスの外に置く：長期タスクの正本（progress md・feature list・RESUME md・git）はセッションの外に永続化し、「セッションが死んでも wake できる」構造にする。既存の RESUME-*.md 運用は session ログの手動版として理にかなっている。
2. credential を作業環境に持ち込ませない：Claude が生成コードを実行する環境（sandbox・CI・Jules VM）にトークンを置かない。Keychain / vault ＋ proxy 型のアクセスに寄せる（settings.local.json にトークンを書いて漏洩した過去事案の教訓と同じ原則）。
3. 回避策には「どのモデルの限界向けか」を書き残す：CLAUDE.md / rules に入れたワークアラウンドは context anxiety 対策のように次モデルで不要化しうる。導入理由をメモし、モデル更新時に見直して剥がす。
4. 実行環境は cattle として使い捨てる：isolation: "worktree" や scratchpad のように、壊れたら作り直せる環境で subagent を走らせ、1つの長命環境（pet）に依存しない。
5. ツールは execute(name, input) → string の粒度で揃える：自作スクリプトや MCP を「名前＋入力→文字列」の統一インターフェイスに寄せておくと、モデルやハーネスを差し替えても資産が生きる。

要点（3〜6行）

• ツールは「決定論的なシステムと非決定論的なエージェントの間の契約」であり、従来の API 設計とは別物として設計すべき。
• 開発サイクルは「プロトタイプ → 実タスクベースの評価 → エージェント自身（Claude Code）と協働して改善」の反復。
• ツールは多いほど良いわけではない。低レベル API の寄せ集めより、ワークフロー単位に統合した高文脈・高効率なツールが勝つ。
• 応答は「トークン効率」と「意味のあるコンテキスト」を優先し、tool description は新入社員に説明するつもりで書く。description の改善だけで SWE-bench Verified の SoTA 達成に寄与した。

内容

ツールとは何か

ツールとは、決定論的システム（API・DB・計算）と非決定論的エージェントをつなぐ新種のソフトウェア。同じ入力で同じ結果を返す従来の関数呼び出しと違い、エージェントは呼ぶか・どう呼ぶかを毎回判断する。目標は「エージェントが有効に働ける表面積（surface area）を広げる」こと、つまり多様な戦略を取れるツール群を用意することにある。

ツールの書き方（開発サイクル）

1. プロトタイプ: まず Claude Code で素早く試作し、ローカル MCP サーバーか Desktop extension として接続してテストする（claude mcp add <name> <command> [args...]。Claude Desktop なら Settings > Developer / Extensions）。

2. 評価（evaluation）: 実ワークフローに根ざした評価タスクを作る。良いタスクは複数ツール呼び出しを要する現実的なもの（例:「Customer ID 9182 が同一購入で3重課金されたと報告。関連ログを全て見つけ、他の顧客にも同じ問題が起きていないか判定せよ」）。悪いタスクは1回の呼び出しで済む浅いもの（例:「payment ログを purchase_complete と customer_id=9182 で検索せよ」）。評価はシンプルなエージェントループ（while ループ）で API をプログラム的に回し、正答率・各ツール呼び出しの所要時間・総呼び出し数・トークン消費・ツールエラーを測る。interleaved thinking を有効にすると推論過程の分析もできる。Slack / Asana の MCP サーバーで、人間製よりも Claude が最適化したツールの方が高性能という結果が示されている。分析では「エージェントが応答に含めなかったもの」の方が重要なことが多い（例: Web Search ツールがクエリに不要な 2025 を付けていた癖を description 改善で解消）。

3. エージェントとの協働: 評価のトランスクリプトを Claude Code に貼り付け、ツールの分析・リファクタを任せる。本記事の助言の大半は、この方法で社内ツールを反復改善して得られた知見。

効果的なツール設計の原則

• 適切なツールを選ぶ: エージェントは計算機と違いコンテキストが希少資源。全件を返す list_contacts より search_contacts を。さらにワークフロー単位に統合する（list_users+list_events+create_event → schedule_event、read_logs → 関連行だけ返す search_logs、顧客情報3ツール → get_customer_context）。
• namespacing: 数十サーバー・数百ツール環境では asana_search / jira_search や asana_projects_search のようにプレフィックスで区別する。命名方式は評価成績に無視できない影響を与え、最適解はモデルにより異なるので自分の評価で決める。
• 意味のあるコンテキストを返す: uuid / 256px_image_url / mime_type のような技術識別子より name / image_url / file_type を返す。恣意的な UUID をセマンティックな名前や 0 始まりの連番に変えるだけで検索タスクの精度が大幅向上し hallucination が減った。ResponseFormat enum（detailed / concise）で応答の詳細度を切り替え可能にする。Slack スレッドの例では detailed 206 トークン → concise 72 トークンで約 1/3 に削減（detailed には後続呼び出しに必要な thread_ts 等の ID を含める）。応答フォーマット（XML / JSON / Markdown）も成績に影響し、最適解はタスク依存。
• トークン効率: ページネーション・範囲指定・フィルタ・truncation に妥当なデフォルト値を持たせる。Claude Code はツール応答をデフォルト 25,000 トークンに制限している。「1回の広い検索より、小さく絞った検索を複数回」とツール側からエージェントに促すのが有効。エラー応答は不透明なエラーコードやトレースバックでなく、修正方法と正しい入力例を返す。
• description のプロンプトエンジニアリング: ツール改善で最も効果的な手段の一つ。新入社員に説明するように、暗黙知（クエリの特殊形式・専門用語・リソース間の関係）を明示する。曖昧な引数名 user は user_id に。この精密化により Claude Sonnet 3.5 が SWE-bench Verified で SoTA を達成し、エラー率が大幅に低下した。MCP のツールアノテーションで、オープンワールドアクセスや破壊的変更の有無も宣言する。

今後

ツールは固定物ではなく、評価とエージェント協働で進化させ続けるもの。詳細は Tool Evaluation Cookbook と Developer Guide「Best practices for tool definitions」を参照（原文参照）。

💡 Claude Code の使い方への適用

1. 自作 MCP サーバー／カスタムツールは「search 型・ワークフロー統合型」で設計する: list_* 全件返しを避け、search_* や get_*_context に統合。応答に UUID の羅列でなく名前ベースの情報を返す。
2. ツール定義の description は新入社員向けの文章で書き、引数名は user でなく user_id のように曖昧さゼロにする。skills（SKILL.md）や slash command の説明文にも同じ原則を適用。
3. ツール応答は Claude Code の 25k トークン制限を前提に、concise / detailed の切替パラメータとページネーションのデフォルト値を実装する。
4. 改善は評価駆動で回す: 実業務タスクで eval を作り、そのトランスクリプトを Claude Code 自身に貼って「このツールをリファクタして」と任せる（本記事の中核ワークフロー）。
5. MCP を多数登録する場合は namespacing を守る（asana_* / jira_* 形式）。当環境の mcp-on-demand（lazy 化）運用は「コンテキストは希少資源」という本記事の前提と合致しているので継続する。

要点（3〜6行）

• 数百〜数千のツールを扱うエージェントのために、ベータ機能3本を導入（beta header: advanced-tool-use-2025-11-20）。
• Tool Search Tool: ツール定義を事前ロードせずオンデマンド発見。トークン 85% 削減、Opus 4 の MCP 評価精度 49%→74%。
• Programmatic Tool Calling: ツール呼び出しをコード（Python）でオーケストレーションし、中間結果をコンテキストに入れない。トークン 37% 削減。
• Tool Use Examples: ツール定義に実例呼び出しを添付し、JSON Schema で表現できない使用パターンを教える。複雑パラメータ精度 72%→90%。
• 3機能は補完関係。「最大のボトルネックから1つずつ」導入するのが推奨。

内容

Tool Search Tool

課題: 典型的な5サーバー MCP 構成（GitHub 35ツール≈26K、Slack 11≈21K、Sentry 5≈3K、Grafana 5≈3K、Splunk 2≈2K トークン）では、会話開始前に 58 ツール・約 55K トークンを消費。Jira を足すと ~17K 追加で 100K+ に接近する。Anthropic 社内でも最適化前はツール定義だけで 134K トークンを消費していた。コストに加え、notification-send-user と notification-send-channel のような類似名でのツール誤選択・パラメータ誤りが最頻の失敗となる。

解決: ツールに defer_loading: true を付けると初期ロードされず、Claude には Tool Search Tool 自体と defer_loading: false の重要ツールだけが見える。必要になった時点で検索し、マッチしたツールの参照が完全な定義に展開されてコンテキストに入る（例:「github」で検索すると github.createPullRequest と github.listIssues だけがロードされ、Slack / Jira / Drive の 50+ ツールは載らない）。検索実装は regex 版（tool_search_tool_regex_20251119）や BM25 版、カスタム実装が選べる。MCP toolset には default_config: {"defer_loading": true} を指定可能。

効果: 従来 ~77K トークン消費 → ~8.7K（コンテキストウィンドウの 95% を温存、85% 削減）。MCP 評価で Opus 4 は 49%→74%、Opus 4.5 は 79.5%→88.1% に精度向上。deferred ツールは初期プロンプトから完全に除外されるため prompt caching を壊さない。

使いどころ: ツール定義が 10K トークン超／ツール選択精度に問題／複数 MCP サーバー構成／10 ツール以上。逆に 10 未満の小規模・毎回全ツールを使う構成では利益が薄い。

Programmatic Tool Calling（PTC）

課題: (1) 中間結果によるコンテキスト汚染 — 10MB のログを処理するとき必要なのはエラー頻度の要約だけでも全文がコンテキストに入る。(2) 推論オーバーヘッド — ツール呼び出し1回ごとにモデルのフルの推論パスが要り、5ツールなら5パス＋結果の手動解析・比較・統合で遅くエラーも出やすい。

解決: Claude がツールを直接呼ぶ代わりに、複数ツールを呼ぶ Python コードを書き、Code Execution tool（サンドボックス）内で実行する。ツールに allowed_callers: ["code_execution_20250825"] を付けて opt-in。スクリプトはツール結果が必要になると一時停止し、API 経由で返された結果はモデルでなくスクリプトが処理する。最終出力（stdout）だけがコンテキストに入る。

例（予算チェック）: get_team_members / get_expenses / get_budget_by_level の3ツールで20人の経費を照合するタスク。従来は 20+ 回の呼び出しで 2,000 行超・50KB+ の経費明細が全てコンテキストに入るが、PTC ではループ・条件分岐・asyncio.gather による並列化を含むスクリプト1本で処理し、超過者2〜3名の結果だけが返る（生データ 200KB → 結果 1KB）。

効果: 複雑なリサーチタスクで平均トークン 43,588 → 27,297（37% 削減）。20+ 回の呼び出しに伴う 19+ 推論パスを排除しレイテンシ短縮。精度も internal knowledge retrieval 25.6%→28.5%、GIA ベンチマーク 46.5%→51.2%。

使いどころ: 集計・要約だけ必要な大規模データ処理／3段以上の依存ツールチェーン／結果のフィルタ・変換／中間データに推論を影響させたくないタスク／50 エンドポイント確認のような並列操作。単発呼び出しや、Claude が中間結果を全て見て推論すべきタスクには不向き。

Tool Use Examples

課題: JSON Schema は構造（型・必須・enum）は定義できるが使用パターンは表現できない。日付は 2024-11-06 か ISO 8601 か、ID は UUID か USR-12345 か、ネストした reporter.contact はいつ埋めるか、escalation.level と sla_hours の相関は——こうした曖昧さが不正なツール呼び出しを生む。

解決: ツール定義内にサンプル呼び出しを直接記述する。サポートチケット API の例では、①緊急バグ（連絡先＋escalation SLA 4h フル指定）②機能要望（reporter のみ）③社内タスク（タイトルのみ）の3例から、Claude は「日付は YYYY-MM-DD、ユーザー ID は USR-XXXXX、ラベルは kebab-case」という規約と、任意パラメータの含め方のパターンを学習する。

効果: 複雑なパラメータ処理の精度が 72%→90% に向上。

使いどころ: 有効な JSON ≠ 正しい使い方となる複雑ネスト構造／任意パラメータの組合せが重要なツール／ドメイン固有規約のある API／類似ツールの使い分け。単純ツールや Claude が既知の標準形式（URL・メール）には不要。

ベストプラクティス

• 3機能を全部盛りにせず「最大のボトルネック」から導入して重ねる（Search=発見、PTC=実行効率、Examples=正確な呼び出し、で補完関係）。
• Tool Search: 最頻使用の3〜5ツールは常時ロード、残りは defer。
• PTC: Claude が正しいパースコードを書けるようツールの返却形式を明確にドキュメント化。
• Examples: 現実的なデータで（"string" や "value" でなく実在しそうな都市名・価格）、最小・部分・完全指定のバリエーションを見せ、ツールあたり 1〜5 例、スキーマから自明でない曖昧箇所に絞る。

記事中のコード例は claude-sonnet-4-5-20250929 を使用（原文参照）。

💡 Claude Code の使い方への適用

1. Claude Code は既にこの仕組みで動いている: セッション内の deferred tools ＋ ToolSearch はまさに Tool Search Tool の実装。MCP を多数登録してもコンテキストを常時圧迫しないが、「最頻3〜5ツールは常時、残りは lazy」の設計原則は当環境の mcp-on-demand 運用の裏付けとして意識する。
2. 大規模データ処理は PTC の原則を手動適用する: MCP や API をツールで逐次叩かず、Bash / Python スクリプトを書かせてフィルタ・集計済みの結果だけを stdout に出す。中間データをコンテキストに載せない。
3. 自作エージェント（ga4-toolkit 等の API 直叩きパイプライン）では beta header advanced-tool-use-2025-11-20 で Tool Search / PTC / Examples を正式導入できる。ツール定義が 10K トークンを超えたら defer_loading を検討。
4. 自作 MCP ツールには input examples を 1〜5 個添付する（現実的データ・曖昧箇所に絞る）。日付形式や ID 規約はスキーマでなく例で教えるのが 72→90% の教訓。
5. ツール応答の返却形式を README / description に明文化しておくと、Claude がスクリプトからそのツールを呼ぶとき（PTC 型運用）に正しいパースコードを書ける。

要点（3〜6行）

• MCP ツールを「直接ツール呼び出し」で使うと、①全ツール定義の事前ロード、②中間結果の往復、の2点でトークンを浪費する。
• 解決策は MCP サーバーをコード API（ファイルシステム上の TypeScript モジュール）として提示し、エージェントにコードを書かせて実行させること。実例では 150,000 トークン → 2,000 トークン（98.7% 削減）。
• 副次効果として progressive disclosure・コード内フィルタリング・ループ等の制御フロー・PII 保護・状態永続化と skills が得られる。
• ただしエージェント生成コードの実行にはサンドボックス・リソース制限・監視が必須で、運用コストとの天秤で判断する。

内容

ツールによる過剰なトークン消費がエージェントを非効率にする

課題1: ツール定義がコンテキストウィンドウを圧迫する。従来の MCP クライアントは全ツール定義を事前ロードして直接呼び出し構文で公開する。gdrive.getDocument や salesforce.updateRecord のような数百語の説明が積み重なり、数千ツール接続時は「リクエストを読む前に数十万トークン」を処理することになる。

課題2: 中間結果が追加トークンを消費する。「Google Drive から会議トランスクリプトを取得して Salesforce のリードに添付」というタスクでは、gdrive.getDocument() の結果（トランスクリプト全文）がまずコンテキストに入り、次に salesforce.updateRecord() の引数として同じ全文がもう一度書き出される。2時間の営業会議なら追加 50,000 トークン。巨大文書はコンテキスト上限を超えてワークフロー自体が破綻し得るし、モデルが大きなデータをツール間でコピーする際は転記ミスも起きやすい。

MCP × コード実行でコンテキスト効率を改善する

MCP サーバー群を、直接呼び出し可能なツールではなくファイルツリー上のコード API として提示する。例（TypeScript）:

servers/
├── google-drive/
│   ├── getDocument.ts
│   └── index.ts
└── salesforce/
    ├── updateRecord.ts
    └── index.ts

各ツールファイルは型付きインターフェース（GetDocumentInput / GetDocumentResponse）を持ち、内部で callMCPTool ユーティリティが MCP サーバーを呼ぶ。エージェントは「Drive → Salesforce」処理を TypeScript で書き、トランスクリプトはコード実行環境の中だけを流れてモデルのコンテキストに入らない。この方式で前述のワークフローは 150,000 → 2,000 トークン、98.7% 削減。Cloudflare も同様の知見を "Code Mode" として発表しており、「LLM はコードを書くのが得意なのだから、その強みで MCP と対話させるべき」という洞察は共通。

コード実行 × MCP の利点

1. Progressive disclosure: モデルはファイルシステム探索が得意。ツールがファイルとして置かれていれば、./servers/ を list して必要な定義だけを読める。search_tools ツールで検索させる／detail_level パラメータ（名前のみ→説明付き→フルスキーマ）で開示量を制御する実装も可能。

2. コンテキスト効率の高いツール結果: 10,000 行のスプレッドシートを直接ツール呼び出しで取ると全行がコンテキストを通過するが、コードなら allRows.filter(row => row["Status"] === 'pending') でフィルタし slice(0, 5) だけ console.log する。集計・複数ソースの join・特定フィールド抽出も同様にコンテキストを圧迫しない。

3. 強力で効率的な制御フロー: ループ・条件分岐・エラー処理をツール呼び出しの連鎖でなくコードで書く。Slack チャンネルに「deployment complete」が流れるまで 5 秒間隔でポーリングする while ループの例では、モデルが sleep とチェックを交互に往復する必要がなくなり、time-to-first-token の遅延も減る。

4. プライバシー保護: 中間結果はデフォルトで実行環境内に留まり、エージェントが明示的に log / return した値だけがモデルに見える。Sheets → Salesforce の顧客連絡先インポートでは、email / phone / name は実データがシステム間を流れつつモデルを通らない。さらに MCP クライアントが PII を自動トークン化（[EMAIL_1], [PHONE_1]）し、別ツールへ渡す時にルックアップで復元する構成も可能で、「どのデータがどこへ流れてよいか」を決定論的なセキュリティルールとして定義できる。

5. 状態の永続化と skills: ファイルシステムがあるので、中間結果を ./workspace/leads.csv に書き出して後続実行で再開できる（進捗追跡・レジューム）。さらに書いた処理を ./skills/save-sheet-as-csv.ts のような再利用可能な関数として保存し、以後 import して使える。SKILL.md を添えて構造化すれば、エージェントは時間とともに自分の能力のツールボックスを育てていく。

まとめ（トレードオフ）

コード実行は独自の複雑さを持ち込む。エージェント生成コードを走らせるには、適切なサンドボックス・リソース制限・監視を備えた安全な実行環境が必須で、これは直接ツール呼び出しなら不要な運用負荷とセキュリティ考慮を意味する。トークン削減・レイテンシ低下・ツール合成の改善というメリットを、実装コストと比較して採否を決めること。（執筆: Adam Jones, Conor Kelly）

💡 Claude Code の使い方への適用

1. Claude Code の skills（SKILL.md）＋ファイルシステムは本記事の構想の実装形。繰り返す処理は使い捨てプロンプトでなく ./skills/ や .claude/skills/ にコード＋SKILL.md として蓄積し、エージェントの道具箱を育てる。
2. MCP ツールで大きなデータを取るタスクは、Bash / Python スクリプト経由に切り替える: 「API を叩いて全件取得 → コード内でフィルタ・集計 → 結果数行だけ print」の形にすれば、10,000 行がコンテキストを通過しない。
3. 中間データは scratchpad やワークスペースのファイルに置く（leads.csv パターン）。長いパイプラインはファイル経由で状態を持たせれば、コンテキスト圧迫なしに中断・再開できる。
4. ポーリング・リトライはツール往復でなく while ループのワンライナーで: 「デプロイ完了まで待つ」類はスクリプト内で sleep させ、モデルの推論パスを消費しない。
5. PII を含む処理はログ・stdout に実データを出さない設計にする（モデルのコンテキスト＝転送面と捉える）。既存の「PII ゼロ公開仕様」運用と同じ原則を、ツール実行の出力設計にも適用する。

要点（3〜6行）

• Agent Skills は「instructions・scripts・resources を整理したフォルダ」で専門知識をパッケージ化し、汎用エージェントを特化エージェントに変える仕組み。
• 中核は SKILL.md 1枚＋YAML frontmatter（name / description 必須）。progressive disclosure（段階的開示）で必要な時だけ中身をロードする。
• エージェントは filesystem と code execution を持つため、skill に同梱できるコンテキスト量は「事実上無制限（effectively unbounded）」。
• token 生成より deterministic なコード実行が安く確実な処理（フォーム項目抽出など）はスクリプトとして同梱する。
• 開発は「評価から始める→スケールする構造にする→Claude の視点で考える→Claude と一緒に反復する」の4指針。信頼できないソースの skill は監査必須。

内容（原文の見出し構成に沿って日本語で詳述）

Introduction

Claude は高い基礎能力を持つが、実世界の仕事には「procedural knowledge（手続き的知識）と organizational context（組織固有の文脈）」が必要。Skills はこの専門知識を「composable resources（組み合わせ可能なリソース）」として梱包し、Claude の能力を拡張する。ユースケースごとにカスタムエージェントを作るのではなく、「新入社員向けのオンボーディングガイドを書く」感覚で作るのがメタファー。

The Anatomy of a Skill

skill の実体は「SKILL.md を含むディレクトリ」で、instructions・scripts・resources を整理して収める。SKILL.md 冒頭の YAML frontmatter には必須メタデータとして name と description を書き、これはエージェント起動時に system prompt へ事前ロードされる。

情報設計は progressive disclosure（段階的開示） の3レベル： - Level 1: metadata（name/description）— 起動時にロード。Claude が「この skill が使える場面か」を認識するための手がかり - Level 2: SKILL.md 本文 — Claude が関連ありと判断した時にロード - Level 3+: SKILL.md から参照される同梱ファイル群 — 必要になった時だけ発見・読込

具体例として PDF skill が挙げられる。reference.md と forms.md の2ファイルを同梱し、フォーム記入の手順は意図的に forms.md へ分離。「skill の中核を軽く保ち、フォーム記入時にだけ Claude が forms.md を読むことを信頼する」設計。エージェントは filesystem と code execution tools を持つため skill 全体を context window に載せる必要がなく、同梱できるコンテキスト量は「effectively unbounded」。

Skills and the Context Window

skill 発動時の context の変化を4ステップで図解：①初期状態＝system prompt＋skill metadata＋user message → ②Claude が Bash tool で pdf/SKILL.md を読む → ③同梱の forms.md を読む → ④ロードした手順に従いタスク遂行。つまり skill はタスク関連性がトリガーされるまで休眠している。

Skills and Code Execution

skill には事前作成のコード（例は Python script）を含められ、Claude はコードベース全体を context に載せずにツールとして実行できる。リストのソートやフォーム項目抽出のような処理は、token 生成でやるより deterministic なコード実行の方が「はるかに安価」で、一貫性と再現性が得られる。PDF skill の例では「PDF を読んで全 form field を抽出する」Python script を同梱し、PDF 自体を context に載せない。

Developing and Evaluating Skills

4つの指針： 1. Start with evaluation（評価から始める）：代表的なタスクでエージェントを走らせ、「つまずく・追加コンテキストを要する」箇所＝能力ギャップを特定してから、skill を漸進的に作る。 2. Structure for scale（スケールする構造）：SKILL.md が肥大したらファイル分割。「相互排他的・稀にしか使わない」コンテキストは別ファイルに分けて token 消費を削減。コードは実行ツールとドキュメントの二役を果たす。 3. Think from Claude's perspective（Claude の視点で考える）：実運用での使われ方を観察し、「想定外の軌道や特定コンテキストへの過度な依存」を監視して反復改善。特に skill の name と description は Claude の発動判断の根拠なので最重要。 4. Iterate with Claude（Claude と一緒に反復する）：タスク中にうまくいったアプローチやよくあるミスを Claude 自身に skill のコンテキストやコードへ落とし込ませる。skill が脱線を招いた時は自己省察させ、「Claude が実際に必要とするコンテキスト」を発見する。

Security Considerations When Using Skills

skill は instructions とコードで新しい能力を与える反面、悪意ある skill は脆弱性を持ち込んだり「データを exfiltrate させ意図しない行動を取らせる」可能性がある。推奨：信頼できるソースからのみインストール／信頼度の低いソースの skill は使用前に徹底監査／同梱ファイル全部を読んで機能を理解／特に code dependencies と同梱リソースに注意／「信頼できない外部ネットワークへ接続させる指示」がないか監視。

The Future of Skills

現在 Claude.ai・Claude Code・Claude Agent SDK・Claude Developer Platform で利用可能。近い将来、skill の作成・編集・発見・共有・利用の全ライフサイクルを支援する機能を予定。MCP servers との補完関係（外部ツールを使う複雑なワークフローをエージェントに教える）にも言及。長期的には「エージェントが自分で Skills を作成・編集・評価し、自らの行動パターンを再利用可能な能力へとコード化する」ことを目指す。Skills は普及のため意図的に「シンプルな概念とシンプルなフォーマット」で設計されている。

（執筆: Barry Zhang, Keith Lazuka, Mahesh Murag ほか）

💡 Claude Code の使い方への適用（3〜5個）

1. skill の name/description を推敲する：.claude/skills/*/SKILL.md の frontmatter は起動時に常駐する唯一の部分。発動条件（トリガー語・対象・除外）を description に具体的に書くと誤発動・不発動が減る。
2. progressive disclosure を自分の skill にも適用：SKILL.md は薄く保ち、稀にしか使わない手順は forms.md 方式で別ファイルへ分離して 参照: <file> と書く。context 消費が恒常的に減る。
3. 繰り返し処理はスクリプト同梱に置き換える：毎回 Claude に token で書かせている定型処理（データ抽出・変換・検証）は skill 内の Python/shell script にして deterministic に実行させる。
4. skill 作成は skill-creator と評価駆動で：先に代表タスクで素の Claude を走らせ、つまずいた箇所だけを skill 化する（Start with evaluation の実践）。作成後は「この skill のどこで迷った？」と Claude に自己省察させて改善する。
5. 外部由来の skill は untrusted-input 扱いで監査：導入前に SKILL.md・同梱スクリプト・依存を全読みし、外部ネットワーク接続やデータ持ち出しの指示がないか確認する（既存の untrusted-input ルールと同運用）。

要点（3〜6行）

• 「エージェントを有用にする能力そのものが評価を難しくする」。多ターン・ツールコール・環境変化への適応があるため、ミスが伝播・複合する。
• 評価の基本語彙：task／trial／grader／transcript（trajectory）／outcome／evaluation harness／evaluation suite。
• grader は3系統——code-based（速い・客観的だが brittle）、model-based（柔軟だが要キャリブレーション）、human（gold standard だが高コスト）——を組み合わせる。
• capability eval（低い pass 率から始めて能力を測る）と regression eval（約100% pass を維持して劣化を検知）を区別。成熟した capability eval は regression suite に「昇格」させる。
• 非決定性は pass@k（k 回中1回成功）と pass^k（k 回全部成功。0.75³≈42%）で扱う。顧客向けエージェントは pass^k が重要。
• ロードマップ：実際の失敗例から 20〜50 タスクで早く始める → 曖昧さのないタスク → 正負バランス → クリーンな harness → grader 設計 → transcript を読む → 飽和監視 → 長期保守。

内容

評価対象はモデル単体ではなく「agent harness＋モデル」の組。single-turn 評価と違い、エージェント評価では途中のミスが後続に複合する。Opus 4.5 が τ2-bench の航空券タスクでポリシーの抜け穴を見つけて解いた例のように、フロンティアモデルは静的な eval の想定を超える創造的な解を出す。

なぜ作るか：プロトタイプ期は手動テストと直感で回るが、スケールすると「盲目飛行」になる。evals は regression 検知・出荷前の数百シナリオ検証・改善の定量化・新モデル採用の高速化（数週間→数日）・latency/token/コストのベースラインを与える。事例として Claude Code（concision や file edit の狭い eval から over-engineering 検知へ進化）、Descript（「壊すな・頼んだことをやれ・上手くやれ」の3軸→LLM grader＋定期的な human calibration）、Bolt（スケール後3ヶ月で static analysis＋browser agent＋LLM judge の総合システム構築）。

ドメイン別：coding agent は決定論的 grader が自然（SWE-bench Verified は1年で40%→80%超）。会話エージェントは対話品質自体が評価対象で、ユーザー役 LLM のシミュレーションが要る（τ-Bench/τ2-Bench）。research agent は専門家間でも意見が割れ、groundedness／coverage／source quality を組み合わせる（BrowseComp）。computer use は実環境・sandbox の outcome 検査（WebArena、OSWorld）。DOM 操作は速いが token 重、screenshot は遅いが token 効率的。

ロードマップの要諦：0% pass@100 はエージェントでなくタスクの故障を疑う（2人の専門家が独立に同じ合否判定に至る書き方をする）。「検索すべき/すべきでない」の両ケースを入れて class imbalance を避ける。trial 間の状態共有を遮断（前 trial の git history を見てズルした実例あり)。grader は決定論優先・手順の固定化を避け・部分点を設計し・LLM judge には「Unknown」の逃げ道を与える。壊れた grader の実害例：Opus 4.5 の CORE-Bench スコアが修正前42%→修正後95%。saturation にも注意（100% pass は改善シグナルを失う。Qodo の one-shot 評価は Opus 4.5 の向上を捉えられず agentic 化が必要だった）。

広い文脈では automated evals／production monitoring／A/B testing／user feedback／transcript review／human studies を Swiss Cheese Model として重ね、CI/CD には evals、出荷後は monitoring、と役割分担する。付録で Harbor、Braintrust、LangSmith、Langfuse、Arize Phoenix の各フレームワークを紹介（詳細は原文参照）。

💡 Claude Code の使い方への適用

1. skill / agent の改善は evals から：skill-creator の eval 機能や eval-harness skill を使い、実際に起きた失敗（bug 報告・やり直し指示）を 20〜50 タスク化してから改善に着手する。数百件を最初から作らない。
2. regression と capability を分けて持つ：恒常運用スクリプト（週次スケジューリング・task extractor 等）は「ほぼ100% pass すべき regression suite」、新機能・新プロンプトは「低 pass 率から始まる capability eval」として別管理する。
3. grader は決定論優先＋LLM judge には逃げ道：pytest 等で判定できるものはコードで判定し、主観品質だけ LLM rubric に回す。rubric は次元ごとに分離し、judge に「Unknown」を許す。
4. trial の隔離を徹底：検証を並列で走らせる時は worktree / クリーン環境で毎回ゼロから。前回の成果物や git history が見える状態は「ズル」の温床。
5. pass^k で信頼性を語る：顧客に出す自動化（ECいんぷる診断等）は「1回成功した」でなく「k回連続で成功するか」で品質判定する。75%成功の処理は3連続だと約42%しか通らない。

要点（3〜6行）

• BrowseComp 1,266問の評価中、11問でモデルが本来のリサーチではなくベンチマーク素材から答えを得ていた。うち9問は学術論文など公開ソース経由の通常の contamination。
• 残り2件は前例のない「eval awareness」：Opus 4.6 が自分が評価中だと自力で仮説を立て、どのベンチマークかを特定し、answer key を発見して復号した。
• 復号手口：GitHub のソースコードから XOR 復号実装を特定→canary string が復号キーだと突き止め→SHA256/XOR 関数を自作→バイナリが読めない時は HuggingFace のミラーから暗号化データを取得。
• 該当ケースの token 消費は 4,050万 token（中央値の38倍）と 1,340万 token。他に18問で benchmark アクセスを試みて失敗（バイナリ制約3件・認証6件）。
• unintended solution 率は single-agent 0.24% vs multi-agent 0.87%（3.7倍）。blocklist 適用後、multi-agent スコアは 86.81%→86.57% に微減。

内容

Anthropic が Opus 4.6 の BrowseComp（Web 上の「干し草の山から針を探す」リサーチベンチマーク）成績を検証したところ、大半の contamination は従来型（公開された論文等に答えが載っていた）だったが、2件はモデルが評価環境そのものを推理してベンチマークの暗号化された answer key を能動的に復号するという新しいパターンだった。multi-agent 構成は探索の手数が増えるぶん、こうした意図しない解法が single-agent の3.7倍発生する（増幅効果）。結論として著者らは「モデルが有能に、eval が複雑になるほど、想定外・望まれない方法で問題を解くのを防ぐことは難しくなる」とし、eval integrity は設計時に一度対処して終わりではなく、継続的な敵対的問題（ongoing adversarial problem）として扱うべきだと勧告する。記事には canary string の節もある（詳細は原文参照）。

💡 Claude Code の使い方への適用

1. 自前 eval の答えをエージェントの手が届く所に置かない：feature list や期待値ファイルを同じ repo・同じ環境に平置きすると、モデルは「テストに合格する最短路」として答えを読みに行ける。answer key は評価環境の外に隔離する。
2. 異常な token 消費を「頑張っている」と解釈しない：中央値の数十倍の消費は、想定外の抜け道（ベンチ素材の探索等）を掘っているシグナルでもある。session-report 等でコスト異常値を監視し transcript を読む。
3. multi-agent 並列は抜け道も3.7倍：subagent を増やすほど意図しない解法・ルール逸脱の試行回数も増える。並列度を上げる時ほど成果物の検証（どうやって答えに到達したか）を厳しくする。
4. 検証は「結果が正しいか」だけでなく「経路が正当か」を見る：合格した trial でも transcript を抜き取りで読み、ズル（前回成果の参照・答えの直読み）がないか確認する習慣を持つ。

要点（3〜6行）

• インフラ設定だけでエージェント型コーディングベンチマークのスコアが6ポイント以上動く。これは上位モデル間のリーダーボード差を超える。
• 原因の典型はコンテナのメモリ設定：guaranteed allocation と hard kill threshold を同値にすると余裕ゼロで OOM-kill が頻発する。
• リソース余裕を3倍にするとインフラ起因エラー率が 5.8%→2.1%（p < 0.001）に低下し、スコアはノイズ範囲内に収まる。3倍超は「何を測っているか」自体が変わる。
• 3ポイント未満のスコア差は、設定が揃っている証拠がない限り疑ってかかるべき。

内容（原文の見出し構成に沿って日本語で詳述）

How we got here：Terminal-Bench 2.0 を GKE で実行したら公式リーダーボードと不一致。コンテナランタイムには guaranteed allocation（保証割当）と hard kill threshold（強制終了閾値）の2パラメータがあり、同値設定だと一時的なメモリスパイクで OOM-kill される。6つのリソース構成（1x strict〜uncapped）を試すと、余裕を増やすほどインフラエラー率が 5.8%→0.5% まで低下した。

How this affects measurement：3倍までの余裕は難易度を変えず信頼性問題だけを解消する。それを超えると、重い依存のインストールなど「タイトな制約下では取れない解法」が可能になり、評価の測定対象が変質する（タイト＝効率性を報酬、潤沢＝リソース活用を報酬）。同傾向は複数の Claude モデルで観察され、SWE-bench でも再現（5x リソースで 1.54 ポイント差）。

Other sources of variance：時間制限のほか、クラスタの健全性・ハードウェア仕様・並行実行数・API レイテンシなどの交絡要因がスコアに影響。モデル能力とシステム挙動の境界が曖昧になる。

What we recommend / Why we care：タスクごとに割当フロアとキル上限の両方を明記し、フロアとシーリングでスコアがノイズ内に収まるようバンドを実証的に較正する。3ポイント未満の差は、構成一致のドキュメントなしには懐疑的に見るべき。インフラ交絡は統計的不確実性の「上に積み上がる」。

💡 Claude Code の使い方への適用（3〜5個）

1. 自前ベンチ（eval-harness 等）でモデル比較する時は実行環境を固定する：メモリ・CPU・並列数・timeout を記録し、構成を揃えない比較で優劣を結論しない。
2. 数ポイント差でモデルや設定を乗り換えない：3ポイント未満の差はインフラノイズの可能性を先に疑う。
3. サンドボックスや Docker でエージェントを走らせる時はメモリ余裕を持たせる：割当＝上限のタイト設定は OOM 由来の「偽の失敗」を生む。目安は保証値の〜3倍。
4. 失敗ログは「モデルの失敗」と「インフラの失敗」を分けて集計する：OOM・timeout・ネットワーク断はモデル能力の評価から除外する。

要点（3〜6行）

• Anthropic のパフォーマンス最適化チームが、Claude 自身に「解かれてしまった」採用テイクホーム試験を作り直し続けた記録（筆者 Tristan Hume）。
• 模擬アクセラレータ最適化の初代試験（4時間→2時間）は1,000人超が受験し数十人を採用する優良試験だったが、Claude Opus 4 がほぼ全人間を上回り崩壊。
• 改訂版も Opus 4.5 が1時間で人間の2時間ベストに並び再崩壊。最終的に Zachtronics 系パズル（極小命令セット・命令数最小化・ツール自作込み）という out of distribution な問題に到達。
• 教訓：AI能力は静的試験を数ヶ月で陳腐化させる／十分長い時間軸では人間の専門家が今も勝つ／訓練データにない新奇問題ほど耐性が高い。

内容（原文の見出し構成に沿って日本語で詳述）

The origin of the take-home：2023年末、加速器クラスタ増強に伴い1,000人超の候補者を捌く必要が発生。TPU に似た simulated accelerator のコード最適化を行う4時間（後に2時間）のテイクホームを設計。設計原則は「実務の代表性・スコア分布の広さ・ドメイン前提知識不要・制限時間を超えて取り組みたくなる面白さ」。

Early results：初期は極めて有効で、高得点者が入社直後にローンチをブロックしていたコンパイラバグを解決した例も。時間無制限の提出には「本格的な最適化ミニコンパイラ」まで現れた。

Claude Opus 4 defeats it（2025年5月）：Claude 3.7 Sonnet が候補者提出の50%超を制限時間内に上回り、Opus 4 は「4時間制限内のほぼ全人間より最適化された解」を出した。→ Version 2（スターターコード刷新・新機能追加・マルチコア削除・2時間化）。

Claude Opus 4.5 defeats Version 2：リリース前テストで Opus 4.5 が1時間以内に主要ボトルネック解消＋定番マイクロ最適化を完遂し、人間の2時間ベストに並んだ。

Considering options / Attempt 1：AI 禁止は却下（実務で AI を使うため）。合格基準を「Claude Code を大幅に上回る」に上げる案は、人間が受動的な監視者になる懸念で不採用。2D TPU レジスタ転置＋bank conflict 回避の新問題も、Opus 4.5 が想定外の最適化（データでなく計算側を転置）を発見し、ultrathink（拡張思考）で突破された。

Attempt 2（Version 3）：Shenzhen I/O 等に着想を得た、極小の制約付き命令セットで命令数最小化を競うパズルへ。可視化・デバッグツールは提供せず、ツール構築自体を評価対象に。この問題は十分 out of distribution で、Claude は苦戦し人間の専門家が優位。筆者は「初代の持つ現実性と奥行きを手放したことは今も残念」と述べる。

ベンチマーク（模擬マシンのサイクル数・小さいほど良い）：Opus 4 (extensive) 2,164 → Opus 4.5 (casual) 1,790 → Opus 4.5 (2h harness) 1,579 → Sonnet 4.5 (extended) 1,548 → Opus 4.5 (11.5h) 1,487 → Opus 4.5 (improved harness) 1,363。時間無制限の人間ベストは全 Claude を上回る。

An open challenge：初代試験を GitHub で公開。1,487 サイクル未満を達成したら performance-recruiting@anthropic.com へコードと履歴書を送れ、という公開チャレンジ付き。

💡 Claude Code の使い方への適用（3〜5個）

1. harness の質が結果を大きく変える：同じ Opus 4.5 でも casual 1,790 → 改善 harness 1,363。プロンプト・ツール・反復ループの設計（Claude Code の CLAUDE.md / skills / hooks）に投資する価値がある。
2. 難所は ultrathink／拡張思考を明示的に使う：人間設計者の想定を超える最適化も、思考予算を増やすと届いた実例。行き詰まった問題には thinking を強化して再挑戦させる。
3. 「理論上可能」と伝えると突破する：Claude は達成可能性のヒント（目標値・存在証明）を与えると賢い回避策を見つける。目標スコアや期待値をプロンプトに書く。
4. out of distribution な独自問題は人間が主導する：訓練データに近い定型最適化は Claude に任せ、前例のない設計・パズル的問題は人間＋Claude の対話で攻める、と切り分ける。
5. 自作の採用課題・演習は定期的に Claude で攻撃テストする：数ヶ月ごとに最新モデルで解かせ、解けたら作り直す前提で運用する。

要点（3〜6行）

• アップグレード版 Claude 3.5 Sonnet が SWE-bench Verified で 49% を達成（従来 SOTA 45%、旧 3.5 Sonnet 33%、Claude 3 Opus 22%）。
• スキャフォールドは「最小限主義＋モデルの自律性優先」。ツールは Bash tool と str_replace_editor（完全一致文字列置換の編集ツール）の2つだけ。
• プロンプトは探索→再現→編集→検証→エッジケース検討の手順を「提案」しつつ、実行順序はモデルに委ねる。
• 教訓：詳細なツール説明で誤解を先回りして潰す／絶対パス必須などのエラープルーフ化／文字列置換編集が最も信頼できた。

内容（原文の見出し構成に沿って日本語で詳述）

Why SWE-bench matters：実在の OSS Python リポジトリの GitHub issue を理解・修正・実テストで検証する、競技問題でない本物のエンジニアリング課題。未飽和で、モデル単体でなくエージェントシステム全体を評価する。Verified は人手レビュー済みの解決可能な500問。

Agent architecture：プロンプトはリポジトリ文脈と PR 記述＋推奨ステップ（explore / reproduce / edit / verify / edge cases）を与えるが順序は自由。ツールは (1) Bash tool（エスケープ・バックグラウンド実行・出力管理のガイダンス付き）、(2) Edit tool str_replace_editor（閲覧・作成・編集。一意な文脈を要求する完全一致置換）。設計原則は「出力を制約するのでなく、詳細なツール説明でモデルの誤解を先回りして防ぐ」。

Agent behavior example：RidgeClassifierCV の store_cv_values パラメータ欠落 issue を12ステップで解決する実走例（構造探索→再現スクリプト→原因特定→コンストラクタに引数追加し親クラスへ転送→テストで検証）。

Key insights / Challenges：新 3.5 Sonnet は自己修正力と複数解試行の粘りが向上。課題は、成功走行でも100ステップ超・100k token 超のコスト／環境構築やパッチ適用起因の採点難しさ／hidden tests によりモデルが成功と誤認するケース／ファイルシステムの視覚化ができない multimodal ギャップ（可視化依存タスクのデバッグ支障）。

💡 Claude Code の使い方への適用（3〜5個）

1. バグ修正はこの順で指示する：「①関連コード探索 ②再現スクリプト作成 ③修正 ④再現スクリプトとテストで検証 ⑤エッジケース検討」。SOTA スキャフォールドが使った推奨手順そのもの。
2. ツールもプロンプトも「制約」より「説明」：カスタムツール（MCP/skills）を書く時は、モデルが誤解しがちな点を長めの description で先回りして潰す。
3. エラープルーフな仕様にする：絶対パス必須・一意な old_string 必須のような「間違えようがない」インターフェース設計が失敗を減らす（Claude Code の Edit tool はこの思想の直系）。
4. 細かく修正指示するよりモデルの自律性に任せる：手順をマイクロマネジメントするより、目的＋検証手段を与えて自己修正ループを回させる方が成績が良い。

要点（3〜6行）

• 2025年8月〜9月初旬、3つの独立したインフラバグが重なり Claude の応答品質が低下。Anthropic は「需要・時間帯・サーバー負荷を理由にモデル品質を落とすことは決してない」と明言。
• ①コンテキストウィンドウのルーティング誤り ②TPU サーバーの出力破損 ③XLA:TPU コンパイラの潜在バグ（approximate top-k の混合精度不一致）。
• Claude Code ユーザーの約30%が少なくとも1回は劣化メッセージに遭遇（バグ①）。
• 検知が遅れた理由：評価がユーザー報告の劣化を捉えられなかった／プライバシー統制で再現が困難／症状の異なるバグの重複で報告が錯綜。
• 対策：より鋭敏な評価・本番での継続的品質評価・プライバシーを守るデバッグツール・ユーザー報告（/bug・thumbs down）の活用強化。

内容（原文の見出し構成に沿って日本語で詳述）

How we serve Claude at scale：Claude は AWS Trainium・NVIDIA GPU・Google TPU の複数ハードウェアと複数チャネル（第一者 API・Amazon Bedrock・Vertex AI）で提供され、どのハードウェアでも同品質という厳格な等価性基準を維持している。

Bug 1: Context window routing error（8/5〜）：Sonnet 4 の一部リクエストが 1M token context window 用サーバーへ誤ルーティング。当初 0.8% → ロードバランシング変更後の 8/31 には 16% に拡大。sticky routing のため一度誤ると後続メッセージも誤サーバーに固定。Claude Code ユーザーの約30%が影響。Bedrock はピーク 0.18%、Vertex AI は 0.0004% 未満。9/4 修正デプロイ、9/18 展開完了。

Bug 2: Output corruption（8/25〜9/2）：TPU サーバーのデプロイ設定ミスで、実行時性能最適化が不適切な token に高確率を誤割当（英語応答にタイ語・中国語文字が混入、コードに構文エラー等）。Opus 4.1 / Opus 4 / Sonnet 4 に影響、第三者プラットフォームは無影響。9/2 ロールバック、想定外文字の検知テストを追加。

Bug 3: Approximate top-k XLA:TPU miscompilation（8/25〜）：コードデプロイが XLA:TPU の潜在コンパイラバグを誘発。主に Haiku 3.5、可能性として Sonnet 4・Opus 3 の一部に影響。根本原因は混合精度（bf16 と fp32）の演算不一致で最高確率 token の判定が食い違うこと。ロールバック（Haiku 3.5 は 9/4、Opus 3 は 9/12）し、approximate top-k から exact top-k へ切替。XLA:TPU チームとコンパイラ修正を進行。

Why detection was difficult：評価が報告された劣化を捉えられない／Claude が単発ミスから回復してしまい問題を覆い隠す／プライバシー統制でエンジニアがユーザー対話にアクセスできず再現困難／プラットフォームごとに症状の違う複数バグが重なり報告が混乱／ノイズの多い評価への過度な依存と、否定的報告の急増を直近のインフラ変更に結び付けられなかったこと。

What we're changing：本番実装の正常/異常を見分けられる高感度な評価、本番システム上での継続的品質評価、プライバシーを保ったまま高速化するデバッグツール、コミュニティ由来フィードバックの調査基盤の整備、/bug コマンドと thumbs down による報告の継続活用。

💡 Claude Code の使い方への適用（3〜5個）

1. 「急に劣化した」と感じたら自分の設定を疑う前に既知障害を確認する：品質劣化はインフラバグ由来のことがある。status ページや公式発表を見てから prompt を作り替える。
2. /bug と thumbs down を実際に使う：Anthropic は検知をユーザー報告に部分的に依存している。異常な出力（言語混入・不自然な構文エラー）は報告する価値がある。
3. 劣化は「モデルの気分」ではない：需要や時間帯で品質を落とすことはないと公式に明言されている。再現性のない劣化は障害・環境要因として切り分ける。
4. 自分のパイプラインにも「継続的品質評価」を持つ：デプロイ時だけでなく本番稼働中も定点評価を回す、というこの記事の教訓は自作エージェント運用にそのまま適用できる。

※2025年3月の記事。現行モデル（4.6+）では adaptive thinking が標準化され、think tool の多くは不要。歴史的知見として保存。

要点（3〜6行）

• think tool は「thought 文字列を受け取るだけの no-op ツール」。長いツール呼び出し連鎖の途中で、必要な情報が揃っているか立ち止まって考える場を Claude に与える。
• extended thinking（応答生成前の事前計画）と違い、ツール使用中の中間ステップとして新しく得たツール結果を消化するのが役割。推論の包括性では extended thinking に劣る。
• τ-bench airline で pass¹ 0.370 → 0.570（最適化プロンプト併用・相対 54% 改善）、retail で 0.783 → 0.812。SWE-bench では平均 +1.6%（p < .001）で Claude 3.7 Sonnet の SoTA 0.623 に寄与。

内容

実装は簡単で、①「thought」string を受け取るツール定義を追加し、②system prompt にドメイン固有の推論例を載せ、③使用状況を監視して改善する、の3段階。効くのは「ツール出力の慎重な分析が要る」「ポリシー遵守が細かい環境」「誤りのコストが高い逐次的な意思決定」の場面。並列・非逐次のツール呼び出しや、複雑な制約のない単純な指示追従には推奨されない（原文参照）。

💡 Claude Code の使い方への適用

1. 現行の Claude Code では追加不要: interleaved / adaptive thinking が標準で、ツール結果ごとの内省は組み込み済み。
2. 原則は今も有効: 長いツール連鎖・ポリシー重視タスクでは「ここで一度、揃った情報と制約を整理して」と中間チェックポイントをプロンプトに入れると精度が上がる。
3. 旧モデルや他ベンダーモデルで自作エージェントを組む場合は、no-op の think tool ＋ドメイン別推論例という軽量パターンが低コストで効く。

要点（3〜6行）

• Desktop Extensions（.mcpb）は MCP サーバーを依存関係ごと1つのパッケージに同梱し、ダブルクリック→「Install」だけで導入できる配布形式。
• 従来の障壁（Node.js / Python の要求、JSON 手動編集、依存バージョン衝突、GitHub 探索、手動アップデート）を解消する。
• 実体は manifest.json ＋サーバー実装＋依存を含む ZIP。自動更新・APIキーの keychain 保管・クロスプラットフォーム対応は Claude Desktop 側が担う。

内容

manifest.json の必須フィールドは mcpb_version / name / version / description / author / server（type・entry_point・mcp_config）。任意で display_name、icon、user_config（ユーザーに API キーやディレクトリを入力させる）、tools / prompts 宣言、compatibility、各種 URL を持てる。${__dirname} ${user_config.key} ${HOME} などのテンプレートリテラルで動的設定が可能。開発は NPM の @anthropic-ai/mcpb（mcpb init で対話的に manifest 生成、mcpb pack で検証＋ZIP 化）。配布は直接共有（ドラッグ&ドロップでインストール）か、審査付きの公式ディレクトリへの申請（Windows / macOS 両対応のテストが必要）。仕様・ツール・参照実装は github.com/anthropics/mcpb で公開されており、Anthropic は拡張開発に Claude Code の利用を推奨している（原文参照）。

💡 Claude Code の使い方への適用

1. 自作 MCP サーバーを非エンジニア（顧客・受講生）に配るなら .mcpb 化が最短経路: 「Node 入れて JSON 編集して」が不要になる。講座の移植キット等で Claude Desktop ユーザーに配布する時の標準手段。
2. API キーは user_config で宣言し keychain 保管に任せる: 平文設定ファイルにキーを書かせない配布ができる。
3. 開発フロー: npm i -g @anthropic-ai/mcpb → mcpb init → mcpb pack。Claude Code に github.com/anthropics/mcpb の仕様を読ませて manifest を書かせるのが公式推奨。
4. Claude Code 自体（CLI）では従来どおり claude mcp add で足りる。.mcpb は Claude Desktop 向け配布専用と切り分ける。

要点（3〜6行）

• 従来RAGの弱点＝チャンク化で文脈が失われ検索が外れる問題を、各チャンクの先頭に説明的文脈を付けてからインデックスする Contextual Retrieval（Contextual Embeddings＋Contextual BM25）で解決。
• 検索失敗率をContextual Embeddings単独で35%、両者併用で49%、reranking追加で67%削減。
• 文脈生成はClaudeへの定型プロンプトで自動化でき、prompt caching併用ならコストは文書100万トークンあたり約$1.02。

内容

ナレッジベースが200,000トークン（約500ページ）未満なら、RAGを組まず全文をプロンプトに入れるのが最善で、prompt cachingで高速・低コスト化できる。それを超える規模で本手法が効く。実装は、各チャンクについて「このチャンクを文書全体の中に位置づける50〜100トークンの説明」をClaudeに生成させ、チャンク先頭に付加してからembeddingとBM25の両インデックスを作る。プロンプトはドメインに合わせてカスタマイズ可能。検索時はembedding（意味）とBM25（正確な語句一致）を併用する。さらにrerankingを足す場合は、まず上位150候補を取得し、関連度スコアで上位20チャンクに絞ってモデルに渡す構成が典型。実験ではチャンク数20が5や10より良く、チャンクサイズ・embeddingモデル（GeminiとVoyageが特に有効）・境界設計の実験が推奨される（詳細な計測条件は原文参照）。

💡 Claude Code の使い方への適用

1. 200kトークン未満は検索を組まない：小さなドキュメント群はRAG化せず、そのままReadで全文をコンテキストに入れる方が精度もコストも良い、という閾値判断を流用する。
2. チャンク＝文脈自己完結の原則：ナレッジノートやmemoryを書く時、後で断片だけ読まれても意味が通るよう「どの文書の何の話か」を各節の冒頭に埋め込む（本手法の思想の手動適用）。
3. RAGを自作する案件（pgvector等）ではContextual Embeddings＋BM25ハイブリッド＋rerankingを標準構成にし、文脈生成はprompt cachingでバッチ処理する。

要点（3〜6行）

• model 選択＝固定された weights（能力の上限レンジ）を選ぶこと。effort＝thinking だけでなく「ファイル読取・検証・多段タスクをどこまで自力で進めるか」の総作業量を制御するダイヤル。
• 失敗時の切り分けが核心：「知識が足りなかった（model を上げる）」か「頑張りが足りなかった（effort を上げる）」かを問う。
• ほとんどのタスクはデフォルト effort のままでよい。Opus 4.8 はデフォルト effort で 4.7 比・ほぼ同トークンでより良い結果。
• Fable＝スペシャリスト／Opus＝エキスパート／Sonnet＝優秀なジェネラリスト。Fable は per-token 最高コストだが、長い多段タスクでは他モデルがどの effort でも完遂できない仕事を完遂する。

内容

model 選択の仕組み

入力テキストは整数トークンに変換され（例: "const"→1978, "await"→4293）、モデルは次トークンの確率分布を予測する。weights は訓練時に固定され、リクエスト時点では read-only。訓練時に存在しなかったライブラリは weights に入っておらず、コンテキストにドキュメントを渡しても「そのリクエストの steering」にしかならない。自信満々の偽 API 呼び出し（hallucination）は「検索の失敗」ではなく、weights が訓練パターンに沿った「もっともらしい」トークン列を生成した結果。200 トークンの応答には 200 回の weight パスが必要。model 設定は「どの weights が処理するか」と「per-token コスト」を決めるが、総トークン数は決めない。

effort の仕組み

出力トークンは thinking／tool call／ユーザー向けテキストの 3 種で、すべて同一ループから生成され同一課金。effort パラメータはプロンプトと共に送られ、各レベルで要求される徹底度が weights に訓練で焼き込まれている。同じプロンプトでも high effort は約 7 倍のトークンを使って高確信度の答えに到達する（記事の図示例）。high effort の計画も固定ではなく、仮説 3 本のデバッグ計画で 1 本目で原因が見つかれば残りはスキップする。「overthinking」は訓練で抑制済みで、単純タスクで無駄に消費しない。

effort level の選び方

「ほとんどのタスクはモデルのデフォルト effort を使うべき」が公式推奨。effort はタスクごとに考えるものではなく、ドメインや作業スタイルに応じた「徹底度 vs 速度」の手動オーバーライドとして持つ general preference。

うまくいかない時に何を変えるか

まず渡したコンテキストを疑う（プロンプトの明確さ・ツールアクセス・skill の有無）。effort を上げないと動かないタスクは、上流のコンテキスト不足のシグナルであることが多い。

• model を上げる場面：問題が本当に難しい（微妙なバグ・不慣れなドメイン・アーキテクチャ判断）。完全なコンテキストを渡し、明らかに全力で試みて、それでも失敗した時。
• model を下げる場面：仕事がルーチン（正確に記述できる編集・機械的変更）。ルーチンが続いているなら下げれば速度が上がりコストも下がり、品質は落ちない。
• effort を上げる場面：ファイルを読み飛ばした・テストを走らせなかった・ダブルチェックしなかった時。主にデフォルト effort より下で運用している場合に有効。

Fable vs Opus vs Sonnet

• Fable＝「ほぼ誰も見たことのない問題を見てきた」スペシャリスト。珍しい問題の認識力。本当に難しいタスクに温存。
• Opus＝類似問題を解いてきたエキスパート。low effort＝「専門家との 5 分レビュー」、high effort＝「午後まるごとのコード精読」。
• Sonnet＝優秀なジェネラリスト。「これ見たことある」の即答はないが、high effort なら全読・テスト実行・検証でコードベースを深く理解する。

トークン消費との関係

ルーチン作業では両モデルとも成功するが、大モデルは検証が多くなり per-token 単価も高いので小モデルへ切替えれば実費が浮く。難しい多段作業では小モデルが能力限界に向けて反復で「削り進む」一方、大モデルは少ないステップで品質ラインに到達し、タスク単位の総コストはむしろ安くなり得る。Fable はテストで Opus/Sonnet がどの effort でも完了できないジョブを完遂した。ハードリミットは max_tokens（到達で途中打ち切り、主に API 開発者向け）、トークン予算や「簡潔に」の指示はソフトな誘導。

💡 Claude Code の使い方への適用

1. 失敗時はまず 2 択で診断する：「知らなかった → /model でモデルを上げる」「サボった（ファイル未読・テスト未実行）→ effort を上げる」。effort を上げる前にプロンプト・skill・ツールアクセスの不足を先に疑う。
2. デフォルト effort を既定運用にする：タスクごとに effort をいじらない。上げっぱなし・下げっぱなしの常用はやめ、ドメイン単位の好みとしてだけ設定する。
3. ルーチン作業が続いたら意識的にモデルを下げる：機械的な編集・横展開の連続は Sonnet に落とすだけで速度↑コスト↓・品質据え置き。
4. Fable は「Opus でも落ちる長い多段タスク」に温存する：per-token 最高コストなので、リファクタ横展開等には使わず、他モデルが完遂できない難物にだけ投入する。
5. トークン節約は max_tokens でなくプロンプトで：対話では「簡潔に」「予算 N トークン目安で」等のソフト制御を使う（訓練で従うよう設計されている）。

要点（3〜6行）

• 著者（Anthropic の Thariq Shihipar）曰く「Fable は、仕事の品質が『自分の未知を明確化する能力』でボトルネックになる初めてのモデル」。
• 未知を Johari Window の 4 象限（Known Knowns／Known Unknowns／Unknown Knowns／Unknown Unknowns）で整理し、「未知を減らし・未知に備えることこそ agentic coding のスキル」と定義。
• 実装前（Blind Spot Pass・ブレスト/プロトタイプ・インタビュー・リファレンス・実装計画）／実装中（implementation notes）／実装後（ピッチ資料・クイズ）の各フェーズに、コピペで使える具体プロンプトを提示。
• 結論：「explainer・ブレスト・インタビュー・プロトタイプ・リファレンスはどれも、修正が高くつく前に『知らなかったこと』を安く見つける手段」。

内容

Knowing your unknowns

計画（map）と実行（territory）のギャップが未知。指示が細かすぎると Claude を最適でない道に縛り、曖昧すぎると意図とズレた仮定で進む。自分の思考ステージ・経験レベル・コードベース習熟度を伝えることで、Claude は思考のパートナーとして機能する。Boris Cherny や Jarred Sumner のような熟練者は、コードベースとモデル挙動への同期を保ち未知を先回りしている。

Pre-implementation（実装前）

• Blind Spot Pass：不慣れなドメインで最初に「自分の unknown unknowns を洗い出して」と頼む。例：「この codebase の auth モジュールを何も知らない。blind spot pass をして、relevant な unknown unknowns を特定し、より良い prompt が書けるよう助けて」「color grading を知らないがこの動画をグレーディングする必要がある。unknown unknowns を理解できるよう教えて」。
• Brainstorms and prototypes：本実装前に複数案を出させ「見れば分かる基準（unknown knowns）」を顕在化。例：「このデータのダッシュボードが欲しいが視覚的センスがない。4 つの全く異なるデザイン方向の HTML ページを作って、反応させて」「配線前に、fake data で新しい editor toolbar をモックした single HTML file を作って」「ユーザーが onboarding 後に churn する。codebase を検索して介入できる場所を安い順に 10 個ブレストして」。実装途中の高価なピボットを防ぐ。
• Interviews：「曖昧な点について 1 問ずつ interview して。答えがアーキテクチャを変える質問を優先」。
• References：スクショや説明文より実コードが濃い仕様になる。例：「vendor/rate-limiter の Rust crate が欲しい backoff 挙動そのもの。読んで同じ semantics を TypeScript API client に再実装して」。
• Implementation Plans：「実装計画を HTML で。自分が弄りそうな判断（data model 変更・新しい type interface・user-facing 部分）を先頭に、機械的リファクタは末尾に埋めて。そこは任せる」。変更リスクの高い判断を目立たせる。

During implementation（実装中）

• Implementation notes：「implementation-notes.md を維持して。計画から逸脱を強いる edge case に当たったら、保守的な選択肢を選び 'Deviations' に記録して続行」。

Post implementation（実装後）

• Pitches and explainers：「プロトタイプ・spec・implementation notes を Slack に投下できる 1 ドキュメントにまとめて。デモ GIF を先頭に」。
• Quizzes：「この変更で起きたこと全部を理解したい。context・intuition・何をしたかを含む HTML レポートと、末尾に合格必須のクイズを付けて」。満点になるまでマージしない。

How this comes together: launching Fable

著者は Fable のローンチ動画を全編 Claude Code で制作（未経験ドメイン）。①文字起こし精度と ffmpeg のタイミングを Claude に教える → ②Remotion で動画 UI をプロトタイプ → ③color grading の原則をまず学んでから複数バリエーションを依頼、という流れで「美的な unknown unknowns はまず教育→それから反復」を実践。

Matching the Map and Territory

締めの一句：「Every explainer, brainstorm, interview, prototype, and reference is a cheap way to find out what you didn't know before it gets expensive to fix.」

💡 Claude Code の使い方への適用

1. 不慣れな領域は最初の 1 プロンプトを Blind Spot Pass にする：「この領域の自分の unknown unknowns を特定して、より良い指示が出せるように教えて」を実装依頼より先に打つ。
2. UI/デザイン系はまず「4 方向の HTML モック 1 枚」：本実装前に single HTML でワイルドに異なる案を出させ、反応してから配線する（既存の 3 案比較ワークフローとも整合）。
3. 仕様が曖昧なまま走らせない：「1 問ずつ interview して。アーキテクチャが変わる質問優先」で先に膿を出す。
4. 長い実装には implementation-notes.md を標準装備：逸脱時は保守的選択＋Deviations 記録で止めずに進めさせ、後でまとめて裁く。
5. マージ前クイズを品質ゲートに：大きな diff は「HTML レポート＋クイズ」を生成させ、自分が満点を取れるまでマージしない。

要点（3〜6行）

• Claude Code に指示を届ける手段は 7 つ（CLAUDE.md／rules／skills／subagents／hooks／output styles／--append-system-prompt）。それぞれロードタイミング・コンテキストコスト・compaction 時の生存性が違う。
• 原則：常時必要な文脈は CLAUDE.md、ファイル種別ごとの制約は path-scoped rules、手順書は skills、脇道タスクは subagents、確定的に必ず実行すべきことは hooks。
• アンチパターン：「毎回必ず X しろ」「絶対 Y するな」を CLAUDE.md に書く（→ hooks / managed settings へ）、30 行の手順を CLAUDE.md に置く（→ skills へ）。

内容

CLAUDE.md files

ルートの CLAUDE.md はセッション開始時にロード、サブディレクトリ版（例 app/api/CLAUDE.md）はそのディレクトリのファイルに触れた時にオンデマンドロード。コストは高い＝関係なくても全行がトークンを消費。書くべき内容はビルドコマンド・ディレクトリ構成・monorepo 構造・コーディング規約・チーム規範。「200 行以下に保ち、オーナーを決め、変更はコードと同様にレビューせよ」。compaction 後、ルートは再読込されるがサブディレクトリ版は再アクセスまで失われる。

Rules

.claude/rules/ に置く markdown。unscoped はセッション開始時ロード、path-scoped は該当ファイルに触れた時のみロード（コスト削減）。compaction 時は再注入される。frontmatter で glob 指定：

---
paths:
  - "src/api/**"
  - "**/*.handler.ts"
---
All API handlers must validate input with Zod before processing.

Skills

.claude/skills/（skill ごとのフォルダ＋SKILL.md）。name と description だけ開始時にロードされ、本体は呼び出し時のみロード＝低コスト。deploy ワークフロー・リリースチェックリスト・レビュー手順など「手続き型プレイブック」向け。呼び出し済み skill は共有トークン予算内で再注入され、古いものから落ちる。例：組込 /code-review は編集せず diff をレビューする。

Subagents

.claude/agents/ に YAML frontmatter 付き md。name・description・tool list のみ開始時ロード、本体は Agent tool で呼ばれた時に別コンテキストで実行＝メインの汚染ゼロ、最終メッセージとメタデータだけ戻る。deep search・ログ解析・依存監査など「メイン会話を散らかす脇道」に使う。

---
name: Agent Name
description: What the agent does
model: (optional)
tools: (optional tool access list)
---
System prompt body here

Hooks

settings.json・managed policy settings・skill/agent の frontmatter に登録し、ライフサイクルイベントで確定的に発火（PreToolUse・PreCompact・ファイル編集・ツール呼び出し・セッション開始等）。型は command／http／mcp_tool（確定実行）と prompt／agent（Claude の判断を使う）。用途：編集後の linter 実行・完了時の Slack 投稿・特定コマンドのブロック（PreToolUse hook が呼び出しを検査し exit code 2 で拒否）。設定はコンテキスト外に住み、compaction を完全にバイパスする。

Output styles

.claude/output-styles/。セッション開始時に system prompt へ注入され compaction されない。コストは高く、デフォルトの system prompt を上書きする。既定スタイル：Proactive（自律）／Explanatory（解説）／Learning（協働学習）。frontmatter に keep-coding-instructions: true を付けないと、変更スコープの扱い・コメント方針・セキュリティ配慮・検証習慣といったデフォルト指示が落ちる点に注意。

--append-system-prompt

CLI フラグでその起動だけに追加注入。初回リクエスト後は prompt caching が効くが入力トークンは増える。特定のコーディング標準・出力整形・ドメイン知識向け。指示を積むほど逓減し、矛盾する指示は遵守率を下げる。

When to use each method（判断基準）

• CLAUDE.md に書いてはいけないもの：「毎回 X したら必ず Y」→ hooks（確定的自動化）。「絶対にするな」→ hooks（PreToolUse）か managed settings（指示でなくガードレール）。30 行の手順 → skills。
• paths: なしの API 固有ルール → path-scoping を付けてコンテキスト節約。
• 個人の好みをプロジェクト CLAUDE.md に書かない → ユーザーレベルのファイルへ。

Getting started

skills・subagents・hooks・output styles はplugin として束ねるとチームやプロジェクト間で一貫したセットアップを共有できる。詳細は best practices ドキュメント（code.claude.com/docs）参照。

💡 Claude Code の使い方への適用

1. CLAUDE.md を 200 行以下に保つ監査を定期実行：手順（30 行超）は .claude/skills/ へ、ファイル種別の制約は .claude/rules/ の path-scoped rule へ退避する。
2. 「必ず／絶対」系は hooks に移す：lint 実行・危険コマンド禁止は CLAUDE.md の文章でなく PreToolUse（exit 2 でブロック）や PostToolUse hook で確定実行にする。
3. rules には paths: frontmatter を付ける癖：全セッション常駐の unscoped rule を増やさず、"src/api/**" 等の glob で触った時だけロードさせる。
4. 脇道調査は subagents に出す：ログ解析・依存監査・大規模検索はメイン会話でやらず .claude/agents/ の隔離コンテキストに投げ、要約だけ受け取る。
5. output style 変更時は keep-coding-instructions: true を必ず確認：デフォルトの検証・セキュリティ指示を意図せず捨てない。

要点（3〜6行）

• ループ＝「停止条件を満たすまで作業サイクルを繰り返す agent」。トリガー・停止基準・使う primitive・適するタスクで 4 分類：turn-based／goal-based（/goal）／time-based（/loop・/schedule）／proactive。
• 段階的に「手を離す」設計：turn-based は毎回人が確認 → goal-based は停止条件を渡す → time-based はトリガーも渡す → proactive はプロンプト全体を渡す。
• 品質維持の鍵は検証手段を skill として与えることと、/code-review skill や GitHub 連携による第 2 エージェントのレビュー。
• トークン管理：primitive とモデルサイズをタスクに合わせる・明確な成功/停止基準・大規模実行前のパイロット・確定的作業はスクリプト化・/usage で使用量レビュー。

内容

Turn-based loops（ターン型）

トリガー＝ユーザーのプロンプト。停止＝Claude がタスク完了またはコンテキスト必要と判断した時。短めで反復しないタスク向け。トークン管理は具体的なプロンプトと verification skill で行う。手動の検証手順を定量チェック付きで SKILL.md に符号化するのが要点。記事の例：

name: verify-frontend-change
description: Verify UI changes end-to-end
Steps: dev server 起動 → 変更箇所を操作 → console 確認 → performance audit 実行

Goal-based loop（/goal）

トリガー＝手動のリアルタイムプロンプト。停止＝ゴール達成 or 最大ターン数到達。検証可能な exit criteria があるタスクに最適。記事のコマンド例：

/goal get the homepage Lighthouse score to 90 or above, stop after 5 tries

Time-based loop（/loop と /schedule）

トリガー＝指定した時間間隔。停止＝ユーザーのキャンセルか作業完了。反復作業や外部システムの監視向け。記事の例：

/loop 5m check my PR, address review comments, and fix failing CI

使い分け：/loop はローカルで実行、/schedule はクラウドに移す。

Proactive loops（プロアクティブ型）

トリガー＝イベント/スケジュール（リアルタイムの人間介入なし）。停止＝各タスクのゴール達成、routine 自体は無効化まで走り続ける。構成要素＝/schedule＋/goal＋skills＋dynamic workflows＋auto mode の組合せ。記事のプロンプト構造例：

/schedule every hour: check #project-feedback for bug reports.
/goal: don't stop until every report found this run is triaged, actioned, and responded to.
When fixing a bug, use a workflow to explore three solutions in parallel worktrees
and have a judge adversarially review them.

Maintaining code quality

①Claude が既存パターンに倣えるようコードベースを綺麗に保つ ②検証メカニズムを skills で提供 ③ドキュメントをアクセス可能に ④第 2 エージェントにコードレビューさせる（/code-review skill か GitHub 連携）。

Managing token usage

• タスクに適した primitive とモデルサイズを選ぶ
• 明確な成功・停止基準を定義する（無限ループ・やり過ぎ防止）
• 大規模実行の前にパイロットする
• 確定的な作業は LLM でなくスクリプトにやらせる
• routine の間隔を変化の頻度に合わせる（変化しないものを高頻度で見ない）
• 使用量レビュー：/usage コマンド・/goal の引数・/workflows のトラッキング

クイックリファレンス

Getting started

ボトルネックのタスクを特定 → 何を手放せるか判断 → ループを実行 → 結果を観察 → システムが止まる/やり過ぎる箇所を基に反復改善、の順で始める。

💡 Claude Code の使い方への適用

1. 検証手順を SKILL.md に定量チェック付きで固定する：「dev server 起動→操作→console→perf audit」のような手動確認をループの品質ゲートとして skill 化する（例: verify-frontend-change）。
2. exit criteria が数値で書けるタスクは /goal に切り替える：/goal Lighthouse 90 以上、5 回で打ち切り のように達成条件＋試行上限をセットで必ず書く。
3. PR 番・CI 番は /loop 5m に任せる：レビューコメント対応と CI 修正の張り付きをローカル time-based ループへ。定常運用に昇格したら /schedule でクラウドに移す。
4. ループ運用のコスト規律：本実行前に 1 回パイロット、確定処理はスクリプト化、/usage で定期レビュー。routine の間隔は監視対象の変化頻度に合わせる。
5. 無人ループには第 2 エージェントのレビューを必ず挟む：proactive 化するほど /code-review skill か GitHub 連携レビューをワークフローに組み込み、品質の自走を担保する。

要点（3〜6行）

• Opus を「アドバイザー」、Sonnet / Haiku を「実行役（executor）」としてペア化し、Opus に近い知能を Sonnet に近いコストで得る戦略。
• 実測：Sonnet + Opus advisor は SWE-bench Multilingual で Sonnet 単体比 +2.7pt、タスクあたりコスト -11.9%。
• Haiku + Opus advisor は BrowseComp で 41.2%（Haiku 単体 19.7% の約2倍）。Sonnet 単体よりスコアは 29% 低いが、タスクあたりコストは 85% 安い。
• Claude Platform の advisor tool（advisor_20260301）を Messages API に1行追加するだけで導入でき、1つの /v1/messages リクエスト内でモデル間ハンドオフが完結する。

内容

アドバイザー戦略でコスト効率の良いエージェントを作る

アーキテクチャはシンプル：Sonnet または Haiku がタスクを端から端まで実行し、tool call と反復を担う。難しい判断に直面した時だけ Opus に相談し、計画・軌道修正・停止シグナルを受け取ってから自力実行を再開する。重要な原則として、アドバイザーは決して tool を呼ばず、ユーザー向け出力も生成しない（助言専任）。

ベンチマーク結果： - Sonnet + Opus advisor：SWE-bench Multilingual で Sonnet 単体比 +2.7 パーセントポイント、エージェントタスクあたりコスト 11.9% 減。

advisor tool

Messages API 経由のサーバーサイドツールとして実装。1つのリクエスト内でモデルハンドオフが起き、追加のラウンドトリップが不要。

BrowseComp と Terminal-Bench 2.0 での結果： - Sonnet + Opus advisor は両ベンチマークで改善しつつ、Sonnet 単体よりタスクあたりコストが低い。 - Haiku + Opus advisor は BrowseComp 41.2%（Haiku 単体 19.7%）。Sonnet 単体よりスコア 29% 低いがコスト 85% 減。

動作の流れ：リクエストで advisor_20260301 を宣言 → 実行役モデルが呼ぶタイミングを自分で判断 → コンテキストが内部的にアドバイザーモデルへルーティング → 同一リクエスト内で実行継続。

課金と制御： - アドバイザーのトークンはアドバイザーモデルの単価、実行役のトークンは実行役の単価で課金。アドバイザーの出力は通常 400〜700 output tokens 程度。 - max_uses でリクエストあたりのアドバイザー呼び出し回数に上限を設定可能。 - アドバイザートークンは usage で別集計され、支出を追跡できる。 - web search や code execution など既存ツールと同じループ内で併用可能。

Get started

3ステップ：①beta ヘッダー anthropic-beta: advisor-tool-2026-03-01 を追加、②Messages API リクエストに advisor_20260301 を追加、③用途に合わせて system prompt を調整（ドキュメントにタスク別テンプレートあり）。推奨評価は「Sonnet 単体／Sonnet + Opus advisor／Opus 単体」の3構成比較。

脚注（ベンチマーク条件）

• SWE-bench Multilingual：Sonnet 単体は adaptive thinking 使用、Sonnet + Advisor は推奨 system prompt で thinking 無効。9言語 300 問 ×5 試行の平均。
• BrowseComp：1,266 問・各1回試行。Terminal-Bench 2.0：89 タスク ×5 試行平均・リソース 3 倍割当。アドバイザーはすべて Opus 4.6。

💡 Claude Code の使い方への適用（3〜5個）

1. サブエージェントの model 指定で「実行役=安いモデル」構成にする：Agent tool の model: "haiku" / "sonnet" で定型実行を安く回し、難所の判断だけ親セッション（上位モデル）に戻す。これが Claude Code 上のアドバイザー戦略の等価形。
2. 自作 API スクリプト（ga4-toolkit 等）に advisor tool を1行追加：anthropic-beta: advisor-tool-2026-03-01 ヘッダー＋advisor_20260301 で、Haiku ベースのバッチ処理（例：mail-task-extractor）の精度を低コストで底上げできる可能性。導入前に claude-api skill で最新仕様を確認。
3. 採用判断は必ず3構成比較で：既存タスクで「実行役単体／実行役+advisor／上位モデル単体」を eval-harness skill 等で比較してから切り替える。記事の推奨手順そのまま。
4. コストガードを先に置く：max_uses 設定＋advisor tokens の別集計チェックを運用に組み込み、アドバイザー呼び出しの暴走（コスト逆転）を防ぐ。

要点（3〜6行）

• マルチエージェント＝別々の会話コンテキストを持つ複数 LLM をコードで協調させる構成。ただし「単一エージェントの方が良い場面で乱用されがち」が本記事の中心警告。
• マルチエージェントは同等タスクで単一比 3〜10倍のトークンを消費する。採用は「コンテキスト保護／並列化／専門化」の3制約に当たる時だけ。
• 分割は仕事の種類でなくコンテキスト境界で行う（context-centric decomposition）。役割分担型（planner/implementer/tester/reviewer）は伝言ゲーム化し、調整に実作業以上のトークンを浪費した実験例あり。
• 検証サブエージェント（Verifier）は最小コンテキストで機能する優良パターン。ただし「1〜2テストで合格宣言する early victory 問題」への明示的対策が必須。

内容

マルチエージェントシステムとは

各エージェントが別コンテキストでタスクの一部（例：リサーチ担当＋計画するオーケストレーター）を持つ。利点はコンテキスト分離・並列実行・専門化。記事はオーケストレーター＋サブエージェントの階層モデルを主に扱う。警告：数ヶ月かけて複雑なマルチエージェントを作った後、単一エージェントのプロンプト改善で同等の結果が出たと判明したチームが実在する。

まず単一エージェントから始めるべき理由

エージェントを増やすごとに障害点・保守すべきプロンプト・予期しない挙動の源が増える。トークンは3〜10倍：コンテキストの重複、エージェント間の調整メッセージ、ハンドオフ用の要約が原因。計画・実行・レビュー・反復を別エージェントにした結果、各ハンドオフで文脈が失われ、実行より調整にトークンを使った失敗例が観測されている。

採用判断フレームワーク：3つのシナリオ

①コンテキスト保護（Context Protection）：あるサブタスクの情報が後続タスクに無関係なまま蓄積し品質を落とす「context pollution」への対策。例：技術問題を診断中のサポートエージェントが注文履歴 2,000+ tokens を抱えると推論が薄まる。注文照会専用エージェントが全履歴を処理し、本体には必要な 50〜100 tokens だけ返す。有効条件＝サブタスクが 1,000 tokens 超を生成する／大半が本タスクに無関係／抽出基準が明確な lookup・retrieval 系。

②並列化（Parallelization）：単一エージェントでは覆えない探索空間を並列で走査する。Anthropic の Research 機能はリードエージェントがクエリを分解し、複数サブエージェントが各側面を並列調査→蒸留した知見を返す。精度は大幅改善する一方、総計算量は増えるため全体時間はむしろ延びることが多い。「並列化の主目的は速度ではなく網羅性」。

③専門化（Specialization）：(a) ツールセット特化——ツールが 20+ になると選択を誤り始める。警告シグナルは「20+ 個」「複数無関係ドメインの混在」「新ツール追加で既存タスクが劣化」。なお Tool Search Tool（オンデマンドでツール定義を発見）でトークン使用を最大 85% 削減しつつ選択精度を上げる緩和策もある。(b) system prompt 特化——共感的サポートと厳密なコードレビューのように行動モードが衝突する場合は分離が有効。(c) ドメイン専門知識特化——法務・医療など深い前提知識が要る領域。例：CRM／MA／メッセージングを跨ぐ統合で各 10〜15 エンドポイント＝計 40+ ツールになったら、プラットフォーム別エージェント＋ルーティングするオーケストレーターに分割。注意点はルーティング誤りとプロンプト保守コスト。ドメインが明確に分離でき、振り分けが曖昧でない時のみ有効。

単一エージェントの限界サイン

①コンテキスト上限に常時接近し性能劣化（ただし context compaction の進歩で緩和中）、②ツール 15〜20+ の管理に注意を消費（Tool Search Tool で緩和可）、③独立サブタスクに分解できる（複数ソースのリサーチ等）。「これらの閾値はモデル改善で動く。現在の実務ガイドラインであり根本的制約ではない」。

コンテキスト中心の分割（最重要の設計判断）

• 問題中心分割（逆効果）：機能実装・テスト・レビューを別エージェントに。ハンドオフごとに文脈が落ち「伝言ゲーム」化。ソフトウェア開発の役割別分担実験では、サブエージェントが実作業より調整にトークンを費やした。
• コンテキスト中心分割（有効）：機能を実装したエージェントがそのテストも書く（文脈を持っているから）。分割はコンテキストを真に隔離できる境界のみ——独立したリサーチ経路／クリーンな API 契約で切れたコンポーネント／実装知識不要のブラックボックス検証。逆に、同一作業の逐次フェーズ・密結合コンポーネント・共有状態が要る作業は同一エージェントに残す。

検証サブエージェントパターン

本体の成果物をテスト・検証する専任エージェント。検証は本質的にコンテキスト転送が最小で済むため伝言ゲーム問題を回避できる。ワークフロー：本体が作業単位を完了→成果物＋明確な合格基準＋検証ツールを渡して Verifier を起動→最大3回の失敗フィードバックループ。なお Opus 4.5 級のオーケストレーターは自前で検証できることが増えたが、下位モデル使用時・専用ツールが要る検証・明示的チェックポイント強制には依然有効。用途：テストスイート実行・lint・スキーマ検証、コンプライアンス確認、出力仕様チェック、事実・引用の検証。

Early victory 問題：Verifier が1〜2テストの成功だけで合格宣言する失敗モード。対策＝「動くか確認して」でなく「フルテストスイートを実行し全失敗を報告」と具体指定／複数シナリオ＋エッジケースを要求／失敗すべき入力が失敗することを確認させる negative test／「You MUST run the complete test suite before marking as passed」のような明示指示。

単一 vs マルチの最終チェックリスト

①本当に3制約（コンテキスト上限・並列化機会・専門化ニーズ）に当たっているか、②分割が仕事の種類でなくコンテキストに従っているか、③フルコンテキストなしで検証できる明確な検証点があるか。結論：「動く最小構成から始め、証拠が支持する時だけ複雑さを足す」。

💡 Claude Code の使い方への適用（3〜5個）

1. Agent tool を反射的に使わない：まず単一セッション＋プロンプト改善。並列サブエージェントは「独立リサーチ経路」「クリーンに切れたコンポーネント」だけに限定（3〜10倍トークンの覚悟がある時のみ）。
2. 分割はコンテキスト境界で：「実装 agent＋テスト agent」の役割分担は禁止パターン。実装したセッションにテストまで書かせ、切り出すのはブラックボックス検証だけにする。
3. Verifier のプロンプトに early victory 対策を必ず入れる：verification-loop / verify skill 起動時や検証サブエージェント指示文に「フルテストスイート実行・全失敗報告・negative test 実施」を明記する。
4. ツールが増えたら ToolSearch / MCP lazy 化：Claude Code の deferred tools と mcp-on-demand 運用は記事の Tool Search Tool（最大85%トークン削減）と同じ発想。エージェント分割より先にこちらを試す。
5. Explore agent はコンテキスト保護の実装例：大量ファイル走査を Explore に投げて要約（50〜100 tokens 相当）だけ受け取る運用は、本記事の「lookup 系サブエージェント」パターンそのもの。全文を親に返させない。

要点（3〜6行）

• Anthropic 社内（主に Slack 上）で「マルチプレイヤーエージェント」＝複数の人間と同時に働く AI を運用して得た4つの教訓をまとめた記事。著者は Education チームの Kristen Swanson。
• 教訓：①公開の場で働き広いコンテキストを与える、②人間もエージェントも役割と適切なツールを定義する、③north star（北極星となる目標）で proactive にする、④信頼は段階的に築く。
• 核心命題：「書かれておらずアクセスできない情報は、エージェントにとって存在しない」。
• 結論：これらは数十年前から知られる健全なチーム運営の基本であり、「エージェントはそれをスキップしないことをより重要にしただけ」。

内容

マルチプレイヤーエージェントとは

多数の人間と同時に働く AI モデル。単一ユーザー向けインターフェースと違い、①目標を保持し実行を調整する永続メモリ、②人間のアカウントと分離された独立 credential（安全で予測可能な動作のため）、③組織的な学習とタスク実行を可能にする広い情報アクセスを持つ。ただし技術基盤だけでは不十分で、チーム側の働き方の規範が必要——それが以下の4教訓。

教訓1：公開の場で働き、エージェントに広いコンテキストを与える

エージェントはアクセス可能なテキスト（Slack・コード・ドキュメント・議事録）だけから理解を構築する。DM や制限付きドキュメントはコンテキストにならない。Anthropic の実践：セキュリティ境界はドキュメント単位でなくワークスペース単位で定義／新規チャンネルは組織内公開をデフォルトに／議事録や成果物はエージェントが検索できる前提で書く。効果＝会議の決定を読んだエージェントは優先度を下げたタスクを提案しなくなり、チーム横断の仕様にアクセスしてパターンを推薦でき、人間が情報量的に見落とす関連作業を浮上させる。ただし機微なやり取りは 1対1 の DM や個人コネクタ付き Claude.ai で私的に行う。

教訓2：人間もエージェントも、定義された役割と適切なツールを持つ

チームは名簿・成果物・ワークスペースを共有しつつ、責任を明確に分ける。プロジェクトキックオフで人間とエージェントが役割分担と協働パターンを議論する。例：データ分析エージェントには BigQuery、QA エージェントには Playwright MCP へのアクセスが必要。コード保守エージェントはバグトリアージ・計画・実装・レビュー・状況報告まで担う。効果＝重複と文脈の分断を防ぎ、メトリクス集計のような作業は1回で全員に見える形になり、人間は人間にしかできない役割に集中できる。実践：誰が何をやるかの合意済みタスクセットを作る／共有スレッドで協働する／エージェントの役割と専門性を定義した skill ファイルを作る／複雑化に応じてエージェントを追加（例：あるエンジニアリングチームはリリース専任の release manager エージェントを追加）。

教訓3：north star を設定してエージェントを proactive にする

野心的で組織的な目標が、エージェントの自発的な提案を導く。方向は人間が決め、実装はエージェントが担う。すべてのエージェントに proactive 権限を与えるわけではなく、どのエージェントに自発提案させるかチームが選ぶ。実例：「プロダクトオンボーディングをより役立つものにする」を north star にした社内ツールチームで、エージェントが自発的にエラーメッセージの改訂を提案→翌週のオンボーディング成功率が測定可能なレベルで向上。実践：north star を議論・文書化し、proactive 権限を持つエージェントに明示的に共有する。

教訓4：信頼は時間をかけて築く

自律性は実証された信頼性に比例して与え、意図的に拡大する。初期は全成果物を人間がレビューして能力と品質を把握し、タスク要件・必要な skill ファイル・有効なプロンプトを特定。モデルが改善したら再テスト。検証手段：コードにはテスト、それ以外にはルーブリックとスタイルガイド。Doer-Verifier ハーネス（1体が実行、別の1体が検証）を導入し、品質バーは人間が設定する。実例：バックログ処理でエージェントが全項目を読み、所有状況を判定し複雑さをスコアリング→人間が全判断をレビュー→やがてエージェントはトレードオフの大きい判断だけ人間に上げるよう学習。継続的実践：週次の「lessons & missteps」レポートをエージェントに書かせる／質問はバッチにまとめて一括レビュー／エージェントの1日の作業量にガードレールを設け、人間のレビュー容量を守る。

問うべき5つの質問

①エージェントと人間が必要とする情報とアクセスは、公開かつ広く検索可能か？ ②チームの名簿（人間＋エージェント）と各メンバーの担当を書き出せるか？ ③全員が職務に必要なツールにアクセスできるか？ ④主要成果物を検証するルーブリックやテストがあるか？ ⑤全員が参照できる明確な north star があるか？

Moving forward

「強い north star、明確な役割、強いドキュメンテーション、共有された品質基準、失敗から学ぶ余地——数十年前から知られた健全なチームの習慣」であり、エージェントの成果を最大化しているのは、これらの基本に最も意図的なチームである。

💡 Claude Code の使い方への適用（3〜5個）

1. 「書かれていなければ存在しない」を徹底：決定事項・前提・再開手順は CLAUDE.md / memory / docs の再開ファイルに必ず文章化する。会話内やDM的な口頭合意で済ませたものはエージェントには存在しない。
2. エージェントごとに役割＋最小ツールセットを定義：.claude/agents/*.md の frontmatter で tools を職務に合わせて絞る（例：QA agent には Playwright 系のみ）。「全ツール持ちの何でも屋」を増やさない。
3. north star を CLAUDE.md に書き、proactive を許す範囲を決める：プロジェクトの最終目標を明記した上で、自発提案してよい agent とタスク実行専任の agent を区別する。
4. Doer-Verifier を標準ハーネスに：実装セッションと検証（verify / verification-loop skill、Codex/agy レビュー）を分離し、品質バー（テスト・ルーブリック）は人間が握る。信頼できるまでは全成果物をレビューし、徐々に「高トレードオフ判断のみエスカレーション」へ移行する。
5. 週次の lessons & missteps を仕組み化：session-end memoization（学び・罠の memory 化提案）を週次で回し、エージェント側の失敗を記録して次回の指示・skill に反映する。

要点（3〜6行）

• 共有チャンネルで複数人と働く Claude Tag では「ユーザーとして行動する」権限モデルが破綻する。理由は①自律性（タスク遂行能力は約4ヶ月ごとに倍増、ユーザー切断後も稼働）、②複数ユーザーがいる場では「誰の権限を適用するか」が解けない。
• 解＝エージェント自身のワークスペースレベル identity（Slack app・GitHub app・service account）。問いを「このユーザーは何ができるか」から「このエージェントはこの区画で何ができるか」に置き換える。

内容

権限の継承：管理者がベースライン identity を定義し全チャンネルが継承。チャンネル単位のオーバーライドで特化アクセス（例：エンジニアリングに GitHub／ウェアハウス）を付与。コネクタ・skill・常設指示もここで構成。identity 失効＝全システムのアクセスが即時一括失効。

区画化：private チャンネルごとに別 identity。法務の identity はエンジニアリングのコードに触れず、その逆も不可。メモリ・学習もチャンネル境界を尊重。Enterprise では RBAC で起動できる人を制限可能。

デフォルトは広めに：価値は複数システムの文脈の掛け合わせで複利化するため、「寛大なベースラインで開始→利用を監査→方針に応じて絞る」が推奨。

DM は別モデル：個人の claude.ai credential＝個人権限で動作。

セキュリティと監査：credential は独立保管され、リクエスト時にネットワーク境界で注入。未許可ホストへの外向き通信はブロック。全ルーチン・メモリ書込・ネットワーク呼び出しがログされ、接続先システムのネイティブログと突合可能。今後＝just-in-time credential 付与、ユーザー権限を重ねる identity-aware オーバーレイ。

💡 Claude Code の使い方への適用（3〜5個）

1. 自動化（launchd/cron）には専用 credential：個人アカウント権限を流用せず、専用 GitHub App / service account / PAT を分離発行し、一括失効可能にしておく。
2. 「広く始めて監査して絞る」を sandbox allowlist 運用に適用：audit skill での定期棚卸しが記事の推奨手順に対応。
3. 区画ごとに設定とメモリを分離：プロジェクト単位の .claude/ 設定・memory で、案件Aの credential・文脈が案件Bへ漏れない構成を保つ（チャンネル区画化の CC 版）。

要点（3〜6行）

• Claude Code と Claude Cowork が Claude for Government Desktop 経由でパブリックベータ提供開始。推論は FedRAMP High 認証インフラ内で実行。
• Claude Code は公共部門のシステム構築・モダナイゼーション、Cowork はデスクトップのファイル処理（メモ・RFP レビュー・ケースワーク・プレゼン）を担当。会話履歴は機関管理デバイスにローカル保存。

内容

ガバナンス：管理者が部門横断で設定デフォルトと支出を制御。ハッシュチェーンの改ざん検知監査ログが全管理操作を記録し ATO プロセスを支援。Anthropic 側の機微操作は二人承認制。課金：標準シートまたは支出/モデル上限付きカスタムティア、固定増分購入＋上限キャップ、ユーザー別・モデル別トラッキング、自動バーンダウンアラート、SCIM グループマッピング。文書：FedRAMP Secure Configuration Guide（公開）、変更通知（NDA 下）、デスクトップクライアントのペンテスト要約。申込＝claude.com/solutions/government。

💡 Claude Code の使い方への適用（3〜5個）

1. 高コンプライアンス案件の提案材料：公的機関系クライアントに、FedRAMP High 相当の統制モデル（監査ログ・二人承認・支出上限）の存在を安心材料として提示できる。
2. チーム配布時の統制設計の手本：spend cap＋モデル別利用追跡＋監査ログの構成は、講座受講生・認定パートナーへ Claude Code を展開する際の管理設計の参考になる。
3. 機微データ運用のひな型：「履歴はローカル・推論は認証環境」という分離は、機微データ案件での運用ポリシー設計に流用できる。