OVERVIEW — 128本を1ページに
原典128本を横断して残るものだけを置く。個々の文書の要約ではなく、複数の原典を並べて初めて見えるもの（数字、判断の分岐点、文書同士の食い違い）を集めている。
原典の索引は SOURCES。ここは思い出すためのページ。 テーマごとの深掘りは topic（10本）。このページの各節が、おおむね1つの topic に対応する。
1. 貫いている一つの制約
128本の大半は、同じ一つの制約から導かれている。別々の文書が独立に同じことを言っている。
The context window is a public good. — agent-skills-best-practices
context window は公共財である。
Most best practices are based on one constraint: Claude’s context window fills up fast, and performance degrades as it fills. — claude-code-best-practices
ほとんどのベストプラクティスは、ひとつの制約に基づいている。Claude の context window はすぐ埋まり、埋まるにつれて性能が落ちる、という制約である。
more context isn’t automatically better. As token count grows, accuracy and recall degrade, a phenomenon known as context rot. — context-windows
context は多いほど自動的に良くなるわけではない。トークン数が増えるにつれて正確性と再現率は劣化する —— context rot として知られる現象である。
Like humans, who have limited working memory capacity, LLMs have an “attention budget” that they draw on when parsing large volumes of context. Every new token introduced depletes this budget by some amount, increasing the need to carefully curate the tokens available to the LLM. — effective-context-engineering-for-ai-agents
working memory の容量が限られている人間と同じく、LLM も大量の context を解釈するときに引き出す「attention budget」を持っている。新しいトークンが1つ入るたびにこの予算はいくらか目減りし、LLM に渡すトークンを慎重に選ぶ必要がその分だけ増す。
制約から導かれる結論を、原典は記事の結語として置いている。
Find the smallest set of high-signal tokens that maximize the likelihood of your desired outcome. — effective-context-engineering-for-ai-agents
望む結果が得られる見込みを最大にする、高信号なトークンの最小集合を見つけよ。
この制約から出てくる手が、文書をまたいで同じ形をしている。
| 手 | 具体例 |
|---|---|
| 使うまでロードしない | skill の progressive disclosure / MCP の tool search / .claude/rules/ の paths: |
| 別の context に追い出す | subagent / workflow のスクリプト変数 / programmatic tool calling |
| context の外に状態を置く | CLAUDE.md / auto memory / memory tool / progress.txt + git |
| 要らなくなったら捨てる | /clear / compaction / context editing |
| そもそも入れない | Read deny ルール / MCP より CLI / hook で前処理して絞る |
この5つは相互に排他ではなく、層をなす。 どれが自分のトークンを食っているかを先に特定する（/context、/usage、manage-tool-context）。
2. 判断の早見表
実際に迷ったときに引くもの。しきい値は原典が明示しているものだけを載せた。
何を使って拡張するか（Claude Code）
| 引き金 | 足すもの |
|---|---|
| 規約やコマンドを 2回間違えた | CLAUDE.md |
| 同じプロンプトを毎回打っている | user-invocable な skill |
| 同じ手順書を 3回目貼った | skill |
| ブラウザからデータをコピーし続けている | MCP server |
| 大量のファイルを読んでシンボルを探している | code intelligence プラグイン |
| 二度と参照しない出力で会話が溢れる | subagent |
| 頼まなくても毎回起きてほしい | hook（指示は要求、hook は強制） |
| 2つ目のリポジトリで同じ設定が要る | plugin |
同じ引き金は更新のタイミングでもある。繰り返す間違いは、チャットでの訂正ではなく CLAUDE.md の編集。
plugin は使わないセッションでも context を食う。 有効な plugin の skill・agent・command のうち Claude が自分で呼べるものは、名前と説明が毎ターン context に載る（plugins）。単体の設定から移すと skill と agent には plugin 名の接頭辞が付くが、hook には付かないので、元の設定を消すまで同じ hook が2回走る（plugins-create）。
委譲の3段階
| 通信 | 中間結果の置き場 | 規模 | 中断されたら | |
|---|---|---|---|---|
| subagent | 親にのみ報告 | 親の context | 1ターンに数個 | ターンをやり直す |
| agent team | teammate 同士が直接 | 共有タスクリスト | 数人の長時間 peer | teammate は走り続ける |
| workflow | — | スクリプト変数 | 1 run に数十〜数百 | 同一セッション内で再開可能 |
選ぶ基準は「ワーカー同士が通信する必要があるか」と「計画を誰が持つか」。
ツールが増えたとき（4つの発生源に4つの対処）
| 症状 | 手段 | しきい値 |
|---|---|---|
| ツール定義が先読みで context を食う | tool search | 10個以上 / 定義 10kトークン超 / MCP 複数集約。30〜50個超で選択精度自体が落ちる |
tool_result の往復が多い | programmatic tool calling | fan-out 型のみ。逐次型は逆に高くつく（τ²-bench で +8%） |
| 同じ定義に毎回払っている | prompt caching | 初日から。2回目のヒットで元が取れる |
古い tool_result が溜まる | context editing | 会話が長引き初期の結果が無関係になったら |
モデルか effort か
Tuning effort is often a better lever than switching models. — choosing-a-model
effort を調整するほうが、モデルを乗り換えるよりも効くレバーであることが多い。
まず effort を動かす。それでも足りない/過剰なら、効率優先（Haiku から上げる）か能力優先（Opus 5.5 から下げる。xhigh / max でも足りなければ Fable 5.1 へ）を選ぶ。
権限（Claude Code）
ルールは deny → ask → allow の順。最初に一致したものが決める。具体性は順序を変えない。 → 広い deny に狭い allow の例外は作れない。
抜け道は2つ: ① PreToolUse hook の exit code 2 は permission ルールの評価より前に止まるので、「Bash を全許可して一部だけ hook で止める」が成立する。② パスのルール（Read / Edit）に限り、同じ設定ファイルの deny / ask リストの中で ! を使えば前のルールから切り抜ける（Read(*.env) の後に Read(!sample.env)）。Bash のルールには効かない。
この評価順の上に座るものがある —— tool.check を扱う mod。 ルールと hook が決めた後に答え、ask ルール・hook のブロック（managed settings の hook は除く）・分類器を覆して承認できる。deny ルールについては、managed settings のあるマシンか Team / Enterprise のサインインでは既定で deny が勝つ（組織が変えられる）が、それ以外では mod が覆せる（permissions）。しかも deny ルールと managed hook が効くのは Claude のツール呼び出しだけで、mod 自身のファイル読み書き・プロセス起動（$.fs / $.process）には効かない。mod はサンドボックスにも入らない（mods-admin / mods-overview）。
compaction の方式（API）
Use on-demand compaction wherever it is available. — compaction
使えるところでは、要求時 compaction を使え。
| 方式 | いつ要約するか | 選ぶ場面 |
|---|---|---|
| 要求時（compaction-on-demand） | 自分がリクエストを送って | いつ compact するかを決めたい／要約を待って止まれない／直近のターンとその thinking を残したい（thinking を残すには3条件。compaction-thinking-blocks）。Bedrock では使えない |
| 閾値（compaction-threshold） | 入力が閾値に達したとき API が | 普段のリクエストに1パラメータ足して任せたい |
| context editing（context-editing） | 規則で | 要約せず、古いツール結果や thinking を消すだけでよい |
eval の grader
| 種類 | 強み | 弱み |
|---|---|---|
| code-based | 速い・安い・再現する | 正当なバリエーションに脆い |
| model-based | 柔軟・ニュアンス | 非決定的・人間との較正が必要 |
| human | ゴールドスタンダード | 高価・遅い |
capability eval（低い pass rate から登る）と regression eval（ほぼ100%）を混ぜない。
3. 覚えておく数字
原典が明示している実測値。「なんとなく効く」ではなく「これだけ効く」で判断するため。
context / トークン
| 数字 | 出所 |
|---|---|
| 150,000 → 2,000 トークン（98.7%減） MCP をコードの API にする | code-execution-with-mcp |
| ツール定義だけで 55K〜134K トークン（会話開始前） | advanced-tool-use |
| tool search で 85%減 / PTC で 37%減 / examples で精度 72%→90% | advanced-tool-use |
| ツール定義 10〜49個の本番リクエストで 20〜40% の削減 | programmatic-tool-calling |
| skill の Level 1 = 約100トークン / Level 2 < 5k / Level 3 = 読むまでゼロ | agent-skills-overview |
| subagent: 6,100トークン読んで 420トークン返す | context-window |
| subagent は数万トークン以上使って探索し、返すのは 1,000〜2,000 トークンの要約 | effective-context-engineering-for-ai-agents |
| Claude Code 起動時点で約 7,850トークン（system prompt 4,200 が最大） | context-window |
CLAUDE.md は 200行未満、MEMORY.md は 200行 or 25KB | memory |
| compaction 後の skill 再注入は 1本 5,000 / 合計 25,000 トークン、古い順に落ちる | context-window |
| Claude Code の system prompt を Opus 5 / Fable 5 向けに 8割以上削っても、コーディングの評価は測れるほど落ちなかった | new-rules-of-context-engineering |
| Claude Code の使われ方: 1リクエストの context が2.6倍、入力と出力の比は 189:1 → 324:1、1プロンプトあたりの作業は3.3倍長く、割り込みは68%減 | opus-5-5-for-longer-coding-sessions |
コスト
| 数字 | 出所 |
|---|---|
| 1開発者あたり 1稼働日 $13 / 月 $150〜250、90%が1日$30未満 | costs |
| agent teams は plan mode で 約7倍のトークン | costs |
| evaluator 付き harness は 20倍（$9/20分 → $200/6時間） | harness-design-long-running-apps |
| multi-agent は chat の 約15倍（単体エージェントは4倍） | multi-agent-research-system |
| キャッシュ書き込み 1.25倍（5分）/ 2倍（1時間）、読み取り 0.1倍（Opus 5.5 は 0.05倍、Fable 5.1 / Mythos 5.1 は 0.025倍） | prompt-caching |
| Opus 5.5 は Opus 5 より入出力 20%・キャッシュ読み取り 60% 安い（読み取りは入力単価の 20分の1）。Claude Code のキャッシュ寿命は購読で1時間（usage credits を使い始めたら5分）、API キーとクラウドプロバイダで既定5分 | what-a-task-costs-on-opus-5-5 |
| Sonnet 5.5 は 入力 $2 / 出力 $10（Sonnet 5 と同じ単価）。最小キャッシュ長は 512 トークン（Sonnet 5 は 1,024） | building-with-claude-sonnet-5-5 / sonnet-5-5-migration-guide |
| 16エージェント・2週間・$20,000 で10万行の C コンパイラ | building-c-compiler |
| multi-agent は同等タスクで単体の 3〜10倍のトークン（別の測り方。上の15倍と併読する） | building-multi-agent-systems |
| 100万行の Zig→Rust 移行で未キャッシュ入力 59億 / 出力 6.9億トークン ≒ $165,000 | ai-code-migration |
compaction を使うと usage のトップレベルは要約の分を含まない（要求時 compaction では 0）。課金の合計は usage.iterations を足す | compaction-threshold / compaction-on-demand |
効果
| 数字 | 出所 |
|---|---|
| multi-agent が単体を 90.2% 上回る。ただし性能分散の80%はトークン量で説明される | multi-agent-research-system |
| contextual retrieval で検索失敗率 5.7% → 1.9%（67%減） | contextual-retrieval |
| sandbox で権限プロンプト 84%減 | claude-code-sandboxing |
| ユーザーは権限プロンプトの93%を承認している。auto mode の偽陽性 0.4%、偽陰性 17% | claude-code-auto-mode |
| prompt injection: 単発 0.1% → 100回の適応試行で 5〜6% | how-we-contain-claude |
| think ツール単体 0.404 → プロンプトと組み合わせて 0.570（ベースライン 0.370） | claude-think-tool |
| 長い入力で問い合わせを末尾に置くと応答品質が最大 30% 向上 | claude-prompting-best-practices |
| web 検索で結果を context 前に絞ると BrowseComp が 45.3%→61.6%（Opus 4.6）。2ベンチ平均で精度 +11%・入力トークン -24% | improved-web-search-with-dynamic-filtering |
| compaction の効きが世代で割れる。同条件で Sonnet 4.5 は 43% で頭打ち、Opus 4.6 は 84% | harnessing-claudes-intelligence |
| memory folder で BrowseComp-Plus が 60.4%→67.2%。subagent で BrowseComp +2.8% | harnessing-claudes-intelligence |
| rubric を採点役に持たせると成功率最大+10ポイント（docx +8.4% / pptx +10.1%）。最大の利得は最も難しい問題で出る | new-in-claude-managed-agents |
| harness と sandbox を分離すると TTFT が p50 で約60%・p95 で90%超の削減 | building-with-claude-managed-agents |
| 社内で最難タスクの成功率が倍増する一方、介入回数は 5.4 → 3.3 に減少 | measuring-agent-autonomy |
| 熟練で自動承認 20%→40%超、割り込みは 5%→9%（どちらも増える） | measuring-agent-autonomy |
| effort を上げた効き方は分野で違う。Terminal-Bench 3.0 での Fable 5.1 の通過率（低い2段の合算 → 高い3段の合算）で ハードウェア 34%→75%、セキュリティ 64%→87%、運用 12%→22%（社内の実行、安全介入オフ） | spending-your-effort |
| hillclimb でサポートのベンチマークの検証の14件が 78.6%→90.5%、コストは約5分の1（prompt の点検、モデルを Opus 4.8（high）から Sonnet 5（low）に変えたこと、その後に足した振り分けの規則と返金上限の相互参照をすべて合わせた結果） | automating-eval-design-and-hillclimbing |
| 運用会社の実タスクの、関係する部分集合（それ自体が数千件）で Fable 5 が 89.4%（それまでの本番モデルは 86.1%） | balyasny-evaluates-fable-5 |
| 営業の購入エージェント: 引き継がれた客が商談になる割合は旧フォームの2倍超、成約は約5日早い。引き継ぎの理由を直し続けて、人が要る会話の割合が約半分に | sales-buying-agent |
| Managed Agents の memory で、Rakuten は最初の試行の誤りが97%減（顧客の報告） | managed-agents-memory |
| エージェントを作るエージェントで、最初の導入にかかる時間がおよそ半分（Cresta の報告） | cresta-agent-builder |
| claude.ai の主要操作を2週間で約3倍速く、3,000超の変更を顧客向けの事故もロールバックも無くマージ | how-we-made-claude-ai-faster |
| ブラウザの prompt injection（プロの red-teamer の攻撃。モデルに届いた攻撃のうちの成功率。Opus 4.5 は extended thinking、他は adaptive の medium）: 追加の防御なしで Opus 4.5 が 17.6%、Opus 5 が 3.8%。probe と分類器を重ねると Sonnet 5 / Opus 5 で 0、Fable 5 で 0.3%（Mythos 5 も 0 とする文と挙げない文が原典に並ぶ） | claude-in-chrome-prompt-injection |
上限・しきい値
| 数字 | 出所 |
|---|---|
| subagent: 同時 20、ネスト 3層、transcript 保持 30日 | sub-agents |
| workflow: 同時 16、1 run 合計 1,000 エージェント、警告は 25体 / 150万トークン | workflows |
| eval は 実際の失敗から取った 20〜50タスクで始める | demystifying-evals-for-ai-agents |
| ベンチマークの差が3ポイント未満なら疑う（インフラ設定だけで6ポイント動く） | infrastructure-noise |
| agent team は 3〜5人から。teammate 1人あたり 5〜6タスク | agent-teams |
| RAG が要るのは 20万トークン（約500ページ）超から | contextual-retrieval |
閾値 compaction のトリガーは最低 50,000 トークン（既定 150,000）。要求時 compaction の instructions は最大 16,384 文字 | compaction-threshold / compaction-on-demand |
| ツールが 20個以上だと選択に苦労する。15〜20個で multi-agent より先に tool search を検討 | building-multi-agent-systems |
| 設定の見直しは 3〜6ヶ月ごと。加えて大きなモデルリリース後に頭打ちを感じたとき | how-claude-code-works-in-large-codebases |
| Claude Code のターン中央値 約45秒。動くのは尾で、99.9%ile が3ヶ月で25分未満→45分超 | measuring-agent-autonomy |
4. モデル世代の落とし穴
最新モデルへの移行で最も多い失敗は「古いプロンプトを持ち越すこと」。 しかも足りないのではなく、余計なものが害になる。
最新モデルでは「足す prompting」より 旧世代向けに書いた過剰な指示を剥がす prompting のほうが重要 — claude-prompting-best-practices
剥がすべきもの
| 旧世代で書いていたもの | 最新モデルでの害 |
|---|---|
CRITICAL: You MUST use this tool when... | 過剰発火。Use this tool when... に戻す |
| 「最後に検証ステップを入れよ」 | Opus 5 は指示なしで自己検証する。over-verification になる。書き換えではなく削除 |
| 「ダブルチェックせよ」 | 同上 |
| 「think carefully」「think step by step」 | Opus 5.5 は返答の前に必ず考える。消すと返答が早く始まり、品質の目立った低下は無かった（getting-the-most-out-of-opus-5-5） |
| Sonnet 5 向けの回避策（拒否の誘導、ツール呼び出しの再試行の shim、「do not be lazy」） | Sonnet 5.5 では外してから eval を回す（building-with-claude-sonnet-5-5） |
| 「3ツール呼び出しごとに進捗を要約せよ」 | Sonnet 5 / Opus 4.8 は自分で質の高い更新を出す。scaffolding を外す |
| 「もっと徹底的に」（anti-laziness） | 過剰発火 |
| 「思考を見せろ」「推論を説明しろ」 | Fable 5.1 / Fable 5 / Opus 5.5 / Opus 5 / Sonnet 5.5 では reasoning_extraction 拒否を誘発しうる（thinking。Fable 5 では、サーバ側フォールバックはこれを再試行せず、拒否がそのまま返る）。答えの短い説明か行動の要約を求め、推論が要るなら thinking ブロックを読む |
| 「重大な問題だけ報告せよ」（コードレビュー） | 忠実に守るので recall が落ちて見える。カバレッジ目的だと明示し、フィルタは別段階へ |
世代で向きが反転するもの
これが最も危険。 同じ指示が逆効果になる。
| subagent の傾向 | 必要な prompt | |
|---|---|---|
| Opus 4.8 | 少なく起こす | 「こういう場面では委譲せよ」と促す |
| Opus 5 / Fable 5 | 多く起こす | 「小さい仕事は自分でやれ」と抑える |
モデル別の破壊的変更
| モデル | 変更 |
|---|---|
| Claude 4.6 以降 | prefill が 400 エラー（Structured Outputs か system prompt へ） |
| Claude 4.7 以降 | budget_tokens が 400 エラー（adaptive thinking + effort へ） |
| Sonnet 5 | adaptive thinking が既定オン / temperature top_p top_k が 400 / 新トークナイザで約30%多いトークン |
| Opus 5 | thinking が既定オン。xhigh / max では thinking を切れない |
| Opus 5.5 | thinking 常時オン（disabled はどの effort でも 400）/ 強制ツール使用が 400 / effort の既定が medium（省くと Opus 5 より1段低い。Anthropic の試験では Opus 5.5 の medium が Opus 5 の high に並ぶか上回るので、Claude Code の原典は移るときはレベルを持ち越さず medium から始めよと言う —— model-config）/ 会話の前方（system・tools・過去のターン）を変えると過去の thinking を送り返すリクエストが 400（一定の日以降のアカウントと、prefix_mismatch_behavior を設定したリクエスト。アカウントの古さに関わらず append-only にする。thinking-troubleshooting）/ Claude API と Google Cloud では computer use が computer_toolset_20260801 のみ（computer-use-tool） |
| Sonnet 5.5 | thinking budget・サンプリングパラメータ・prefill も 400。Claude API と Google Cloud の computer use は computer_toolset_20260801 だけ（computer_20251124 は 400、computer_20250124 はどこでも不可）、advisor の相手も絞られた（sonnet-5-5-migration-guide）/ thinking 既定オン（常時オンではない。disabled は 400 で、事前の thinking を切るには between_tools、effort high 以下のみ）/ 強制ツール使用が 400 / Opus 5.5 と同じ prefix 検査（会話の前方を変えると過去の thinking を送り返すリクエストが 400。thinking-troubleshooting）/ Sonnet 5.5 の thinking ブロックを読める他のモデルは Claude API と Google Cloud 上の Opus 5.5 だけで、ブロックは生んだアカウントにも結びつく（そこで Opus 5.5 へ上げる切り替え以外では推論は引き継がれない。thinking。ブログは「他のモデルは読まない」と書いている —— §5）/ effort の既定は Claude API で high（effort）、Claude Code で medium（model-config）。API では Sonnet 5 の設定を持ち越さず effort sweep をやり直せと原典は言う |
| Fable 5.1 / Mythos 5.1 | thinking 常時オン（disabled は 400）/ 強制ツール使用が 400 / Fable 5.1 は Opus 5.5 と同じ prefix 検査 |
| Fable 5 / Mythos 5 | thinking 常時オン。1リクエストが数分〜数時間走る（タイムアウトを先に直す） |
thinking と effort の混同
thinkingパラメータ = thinking ブロックで考えるかeffortパラメータ = 応答全体（テキスト + ツール呼び出し + thinking）にどれだけ労力を割くかadaptiveをeffortの値として渡してはいけない（thinkingのモードであって effort のレベルではない）- 費用の厳密な上限は
max_tokensだけ。effortはソフトな指針 effortを変えるとプロンプトキャッシュが壊れる → 会話ごとに固定し、ターン単位の調整は per-message prompting で。ただし既定値を明示的に書くのは省略と同じで壊さず、per-message effort に対応したモデルならrole: "system"メッセージで運ぶ変更も壊さない（prompt-caching）。Claude Code では、Opus 5.5 を API キーか購読で使うなら/effortを変えてもキャッシュは保たれる（Bedrock・Agent Platform・Claude apps gateway では壊れる。what-a-task-costs-on-opus-5-5）。別の記事は「Opus 5.5 や Fable 5.1 のような新しいモデル」でキャッシュを保ったまま effort を変えられると書くが、提供経路の条件には触れていない（opus-5-5-for-longer-coding-sessions）。以前の記事との食い違いは §5
→ thinking / effort / thinking-steering-and-cost
5. 原典どうしが食い違っている点
単一の文書を読んでいては見えない。 ここが横断してまとめる最大の理由。
「eval が突破される」が4つの異なる機構で語られている
| 機構 | 出所 |
|---|---|
| 人間向けの課題をモデルが解いてしまう | AI-resistant-technical-evaluations |
| モデルが「これは評価だ」と気づき、答えの鍵を復号する | eval-awareness-browsecomp |
| インフラ設定だけでスコアが6ポイント動く | infrastructure-noise |
| capability eval が飽和して改善シグナルが消える | demystifying-evals-for-ai-agents |
→ eval の integrity は「設計時の関心事」ではなく継続的な敵対的問題。
RAG の位置づけが2つの時点で違う
- contextual-retrieval: チャンクに文脈を前置して埋め込め
- effective-context-engineering-for-ai-agents（現在）: まず context に載せられないかを考えよ
→ 1M context の時代に「そもそも RAG が要るか」の判断基準が変わった。原典自身が「20万トークン未満なら全部プロンプトに入れろ」と書いている。
think ツールが自分自身を非推奨にしている
claude-think-tool は その後の更新で 「extended thinking が改善したので、ほとんどの場合そちらを使え」と原典に明記された。ただしポリシー遵守が重い多段ツール使用では依然として参考になる（プロンプトとセットで 54% 改善）。
harness の作り込みが自分の陳腐化を予告している
- effective-harnesses-for-long-running-agents: 4つの成果物を作り込め
- managed-agents: harness はモデルが良くなるほど陳腐化する前提が埋め込まれている
- prompting-claude-fable-5: 旧モデル向けの skill は Fable 5 には規範的すぎて品質を落とす
→ harness と skill は資産であると同時に負債。モデルリリースのたびに削る対象として見直す。
Sonnet 5.5 の thinking ブロックを他のモデルが読めるか
On the Claude API and Google Cloud, Claude Opus 5.5 reads Claude Sonnet 5.5’s blocks and no other model does
Claude API と Google Cloud では、Claude Opus 5.5 が Claude Sonnet 5.5 のブロックを読み、他のモデルは読まない — thinking
No other model reads Sonnet 5.5’s blocks.
Sonnet 5.5 のブロックを読む他のモデルは無い。 — building-with-claude-sonnet-5-5
→ ブログは「他のモデルは読まない」、ドキュメントは Claude API と Google Cloud の Opus 5.5 を例外にしている。thinking のドキュメント自身も、以前の取得までは「Sonnet 5.5 のブロックを読める他のモデルは無い」と書いていた（thinking の要約に記録）。原典はどちらもこの違いに触れていない。
Claude Code で会話の途中に effort を変えるとキャッシュが壊れるか
Set your model and effort level before you start. Changing either one mid-conversation can bust your prompt cache, which can increase token cost.
始める前にモデルと effort レベルを決めよ。会話の途中でどちらかを変えると prompt cache を壊しうるので、トークンの費用が増えうる。 — maximizing-session-value
On Opus 5.5 with an API key or a Claude subscription, changing effort keeps the cache. You can raise it for one hard step and lower it again without rewriting the conversation.
Opus 5.5 を API キーか Claude の購読で使うなら、effort を変えてもキャッシュは保たれる。難しい1歩のために上げ、会話を書き直さずにまた下げられる。 — what-a-task-costs-on-opus-5-5
For newer models like Opus 5.5 and Fable 5.1, you can now change effort levels during your sessions without resetting your cache.
Opus 5.5 や Fable 5.1 のような新しいモデルでは、セッション中に effort レベルを変えてもキャッシュをリセットしなくなった。 — opus-5-5-for-longer-coding-sessions
→ 1つ目がいちばん早く出た。2つ目は Opus 5.5 について書き、Amazon Bedrock・Google Cloud の Agent Platform・Claude apps gateway では effort の変更がキャッシュを消すと書く。3つ目は Opus 5.5 と Fable 5.1 を「like」で挙げ、提供経路の条件を書かない。3つ目は本文で2つ目と1つ目の両方にリンクし、2つ目は1つ目を末尾の関連記事（Further reading）に挙げるが、どれも互いの主張の違いには触れていない。
同じ44件のベンチマークで、費用の下がり方が合わない
The move to Opus 5.5, at low effort, cut the benchmark’s cost by about 18%. Running prompt-audit cut it by a further 9%, to about 25% below the Opus 4.8 starting point.
Opus 5.5 の low effort に移すと、ベンチマークの費用は約18%下がった。prompt-audit を走らせるとさらに9%下がり、Opus 4.8 の出発点より約25%下になった。 — what-a-task-costs-on-opus-5-5
This cleared the baseline accuracy bar at 87.8% and cut cost to 1.9 cents per ticket, less than half the starting cost.
これで基準の正答率を 87.8% で越え、費用は1件 1.9 セントと、出発点の半分未満になった。 — automating-eval-design-and-hillclimbing
→ どちらも社内のサポートのベンチマーク44件で、Opus 4.8 から prompt の点検と Opus 5.5 の low への移行を経た費用だが、約25%減と半分未満で合わない。前者はモデル移行が先、後者は点検が先で、後者は探索用30件の数字である。原典はどちらも相手に触れていない。
大きいモデルをどこに置くかで、2本が逆を向いている
どちらも実運用の報告で、結論が正反対になっている。
-
ai-code-migration（大規模なコード移行）
save your largest model for reviewers and for anything that writes rules other agents will follow — ai-code-migration
最大のモデルはレビュアーと、他のエージェントが従うルールを書くものに取っておけ。
実装の fan-out には小さいモデルを撒く（Sonnet で 12 subagent）。
-
new-in-claude-managed-agents（Spiral by Every の執筆エージェント）
The lead agent runs on Haiku: it fields incoming requests, poses quick follow-up questions when needed, then delegates the drafting to subagents running on Opus. — new-in-claude-managed-agents
lead agent は Haiku で走る。受け付けたリクエストを捌き、必要なら短い追加質問を投げ、それから草稿作成を Opus で走る subagent へ委譲する。
→ 反転させているのは「審判が誰か」。 移行では審判がコンパイラとテストスイート（機械）なので、生成は安くてよく、人間の判断を代行するレビュアー側に大きいモデルが要る。執筆では審判が rubric による採点で、価値そのものが生成物の質にあるので配置が逆になる。
判断の順序としては、まず「このタスクの審判は客観的か」を決めてからモデルを配置する。§7 の「作る者と判定する者を分ける」はどちらの側にも当てはまるが、どちらを厚くするかはここで決まる。
「harness を削れ」と「harness がモデルと同じくらい効く」
-
harnessing-claudes-intelligence
Agent harness design is the practice of deciding what belongs in that scaffolding and, as models improve, what you can take out. — harnessing-claudes-intelligence
agent harness 設計とは、その足場に何が属するかを決め、そしてモデルが良くなるにつれて何を取り除けるかを決める実践である。
-
how-claude-code-works-in-large-codebases
the ecosystem built around the model—the harness—determines how Claude Code performs more than the model alone — how-claude-code-works-in-large-codebases
モデルの周りに構築されたエコシステム —— harness —— の方が、モデル単体よりも Claude Code の性能を決めている。
→ 同じ語で違う層を指している。 前者が削れと言うのはループとオーケストレーション（結果をどう回すか、いつ context を切るか）で、モデルが賢くなるほど不要になる部分。後者が効くと言うのはcontext の供給（CLAUDE.md / skill / LSP / MCP）で、これはモデルが賢くなっても代替されない —— Claude はあなたのコードベースの構造も組織の規約も知らないからだ。
実際、前者自身が差別化すべき場所として context 管理とドメインの専門性を名指ししている。削るのはループ側、積むのは context 側。
6. セキュリティの層
順序が決まっている。 逆順にすると効かない。
Design for containment at the environment layer first, then steer behavior. — how-we-contain-claude
まず環境レイヤーでの封じ込めを設計し、その上で振る舞いを誘導せよ。
| 層 | 手段 | 保証の強さ |
|---|---|---|
| 1. 環境 | sandbox（ファイルシステム隔離とネットワーク隔離の両方）、egress 制御、プロキシによる認証情報の注入 | 成功した注入でも被害が閉じる |
| 2. 権限 | deny ルール、permission mode、PreToolUse hook | クライアントが強制する。モデルの判断に依存しない（ただし入れた mod は、managed でない hook のブロックや、条件次第で deny ルールを覆せる。deny は mod 自身のファイル・プロセス操作には効かず、mod はサンドボックスの外で動く。§2） |
| 3. モデル | system prompt のポリシー、分類器、tool_result への隔離 | 指示であって強制ではない |
片方だけでは不十分という指摘が繰り返される。
- ファイルシステム隔離だけ → ネットワーク経由で持ち出される
- ネットワーク隔離だけ → サンドボックスから脱出される
- CLAUDE.md に「
.envを編集するな」 → 要求であって保証ではない。PreToolUsehook が強制
見落とされた実例（how-we-contain-claude が自ら開示）:
- 信頼ダイアログより前に hook が実行されていた
- フィッシングでユーザー自身が注入経路になった（統制試験で 25回中 24回成功）
- allowlist 上の自社 API が持ち出し経路になった
- VM 隔離が EDR まで締め出した
間接注入への最重要の対策: 信頼できない第三者コンテンツは tool_result にだけ入れる（system prompt や user text には入れない）。Claude は tool result 内の指示を懐疑的に扱うよう訓練されている。
統制はモデルの周りに置く。
A more capable model does not receive broader authority simply because it can reason or plan more effectively.
より上手に推論や計画ができるからといって、より能力の高いモデルが広い権限を受け取るわけではない。 — balyasny-evaluates-fable-5
運用会社 BAM は、承認されたデータの境界・最小権限・ツール単位の権限・ログと追跡・重要な出力の人のレビュー・例外の明確な上げ先を置き、広げる前に敵対的・失敗の場面を試す。
Those controls were a day-one priority, and security did not fundamentally change with Fable.
それらの統制は初日からの優先事項で、Fable になってもセキュリティは根本的には変わらなかった。 — balyasny-evaluates-fable-5
人とエージェントのチームでは、エージェントの実効の権限を起動した人の権限で縛り、恒久の memory に書ける人を管理者と編集者に限る（asana-human-agent-teams）。
7. 長時間・自律実行の型
複数の文書が同じ型に収束している。
毎セッションの立ち上がり（effective-harnesses-for-long-running-agents）
pwdで作業ディレクトリを確認- git ログと progress ファイルを読む
- 未完了で最優先の機能を1つ選ぶ
init.shで開発サーバを起動- 新しい作業の前に end-to-end テストを走らせる
初期化エージェントが作る4つの成果物: feature_list.json（JSON なのは上書きされにくいから）/ git リポジトリ / claude-progress.txt / init.sh
3つの失敗モード（a-harness-for-every-task）
| 名前 | 内容 | 対処 |
|---|---|---|
| agentic laziness | 部分的な進捗で「終わった」と宣言する | loop until done / 検証ループ |
| self-preferential bias | 自分の結果を好む（特に検証を頼まれたとき） | 別 context の verifier（adversarial verification） |
| goal drift | 目的への忠実さが徐々に失われる。特に compaction 後 | 目的をファイルに保存する |
作業するエージェントと判定するエージェントを分けることが強力なレバーになる — harness-design-long-running-apps
fresh context の verifier subagent は self-critique より優れる — prompting-claude-fable-5
実践者が口を揃えること（how-anthropic-teams-use-claude-code）
- 技術者チーム: checkpoint を刻んで試し、ダメなら捨ててやり直す
修正しようとするより、やり直したほうが成功率が高いことが多い
- 非技術者チーム: Claude.ai で計画し、Claude Code で作る
- 自己検証のループを作る — ビルド・テスト・lint を自動で走らせる。特にコードを書く前にテストを生成させる
業務をエージェントに任せるときの組織の側
エージェントが変更を速く書くようになると、大規模なコード移行のボトルネックは組織の側に移る。 実行の前に、人を介さずに確かめられる条件で書いた「証明書」と、変更ごとの人のレビューの深さを段階で決めた「昇格の方針」を、レビューする人と一緒に決め、小さな区画で端から端まで通してから広げる（preparing-for-code-modernization）。エージェントに業務をさせる事例では、規則の一覧より目的を渡し、人への引き継ぎの理由をすべてフィードバックとして扱う（sales-buying-agent）、会話のどこを柔軟にしどこを決定的にするかを線引きし、新しいモデルが出るたびに同じ評価を回し直す（cresta-agent-builder）。
8. 128本の地図
テーマ別。詳細は各ファイルへ。
基礎（4本） — building-effective-agents（workflow と agent の区別）/ effective-context-engineering-for-ai-agents（attention budget）/ writing-tools-for-agents（ツール設計7原則）/ agent-skills-best-practices（context は公共財）
Claude Code の仕組み（7本） — claude-code-best-practices / how-claude-code-works / features-overview / context-window / model-config（default の解決先と effort の既定）/ glossary / whats-new
Claude Code の拡張（15本） — memory / skills / sub-agents / agent-teams / cross-session-messaging / workflows / hooks-guide / hooks / plugins（配布の単位。有効なら使わないセッションでも毎ターン context を食う） / plugins-create（.claude-plugin/ に入るのは plugin.json だけ）/ mods-overview（Claude Code の中で動く JavaScript の hook。描き、書き換え、承認もできるがサンドボックスは無い）/ mods-create / mods-events（tool.check は権限の判断の後に走る）/ mods-admin（deny は Claude のツール呼び出しにしか効かない）/ getting-started-with-claude-code-mods
Claude Code の運用（13本） — mcp / permission-modes / permissions / costs / maximizing-session-value（セッションの請求額と、prompt cache を捨てる操作）/ what-a-task-costs-on-opus-5-5（タスクの値段はターン数とキャッシュで決まる）/ opus-5-5-for-longer-coding-sessions（1リクエストの context が半年で2.6倍）/ worktrees（並行セッションの隔離。4つの検査で強制される）/ sessions（再開で戻らないものの境目）/ large-codebases / headless / settings / common-workflows
リファレンス（3本） — 引くための表。要約はせず、原典へ送るだけにしている: cli-reference / env-vars / tools-reference
prompting（9本） — claude-prompting-best-practices（living reference）/ prompt-engineering-overview / best-practices-for-prompt-engineering / モデル別5本（prompting-claude-opus-5 / prompting-claude-sonnet-5 / prompting-claude-sonnet-5-5 / prompting-claude-opus-4-8 / prompting-claude-fable-5）/ prompt-library
context 管理（10本） — context-windows / compaction（3方式の比較。使えるなら要求時）/ compaction-on-demand / compaction-threshold / compaction-thinking-blocks（残したターンの thinking の3条件。破っても compact は成功し、後で 400 か黙って捨てられる）/ context-editing / manage-tool-context / prompt-caching / memory-tool / managed-agents-memory（memory をファイルシステムに置く理由）
thinking と effort（5本） — thinking / thinking-steering-and-cost / effort / spending-your-effort（effort は検証とエッジケースの量を変える）/ thinking-troubleshooting（モデル別に 400 で蹴られる設定。症状から引く）
ツール（9本） — define-tools / tool-search-tool / programmatic-tool-calling / advanced-tool-use / code-execution-with-mcp / desktop-extensions / improved-web-search-with-dynamic-filtering（結果を context 前に絞る）/ code-execution-tool（インターネットの無いサンドボックス。$OUTPUT_DIR のものだけが返る）/ computer-use-tool（座標は自分が返した画像の画素空間）
skill（4本） — agent-skills-overview / how-we-use-skills（社内の9分類と、description は発火条件）/ equipping-agents-for-the-real-world-with-agent-skills / improving-frontend-design-through-skills（分布収束と、禁止が作る新しい既定）
eval（9本） — develop-tests / automating-eval-design-and-hillclimbing（良い eval の4条件と過学習の防ぎ方）/ demystifying-evals-for-ai-agents / AI-resistant-technical-evaluations / infrastructure-noise / eval-awareness-browsecomp / swe-bench-sonnet / clio（何を探すか事前に決められないとき）/ balyasny-evaluates-fable-5（実タスク数千件で評価する運用会社の事例）
guardrails（4本） — reduce-hallucinations / increase-consistency / mitigate-jailbreaks / reduce-latency
セキュリティ（6本） — claude-code-sandboxing / claude-code-auto-mode / how-we-contain-claude / secure-deployment / create-files（実行環境を与えると外向きの経路が開く）/ claude-in-chrome-prompt-injection（ブラウザの注入対策の3層）
エージェント設計の事例（12本） — multi-agent-research-system / effective-harnesses-for-long-running-agents / harness-design-long-running-apps / managed-agents / building-c-compiler / a-harness-for-every-task / ai-code-migration（コードではなくループを直す）/ how-we-made-claude-ai-faster（測ることがそのまま取り組めることになる）/ preparing-for-code-modernization（ボトルネックは組織側に移る）/ sales-buying-agent（規則より目的）/ asana-human-agent-teams（使うことと鍛えることを分ける）/ cresta-agent-builder（柔軟さと決定性の線引き）
multi-agent の判断（4本） — building-multi-agent-systems（使うか否か。context で切る）/ multi-agent-coordination-patterns（繋ぎ方5種を壊れ方で選ぶ）/ building-with-claude-managed-agents（脳と手の分離）/ new-in-claude-managed-agents（別 context の採点役）
harness を削る（4本） — harnessing-claudes-intelligence（何をやめられるか）/ new-rules-of-context-engineering（system prompt を8割削っても落ちなかった）/ how-claude-code-works-in-large-codebases（設定を3〜6ヶ月で見直す）/ measuring-agent-autonomy（実際に与えられている裁量の実測）
モデルの選択と移行（4本） — choosing-a-model / getting-the-most-out-of-opus-5-5 / building-with-claude-sonnet-5-5（Sonnet 5.5 か Opus 5.5 か）/ sonnet-5-5-migration-guide（400 になる設定5つ）
その他（6本） — contextual-retrieval / claude-think-tool / use-case-guides / how-anthropic-teams-use-claude-code / prompt-eng-interactive-tutorial / claude-cookbooks
9. ここからどこへ
各節を深掘りしたものが topics/ にある。
| このページの節 | 深掘り |
|---|---|
| §1 貫いている一つの制約 | context-engineering |
| §2 委譲の3段階 | agent-design |
| §2 ツールが増えたとき / §3 context の数字 | tool-design |
| §2 eval の grader / §5 eval が突破される4機構 | evals |
| §4 モデル世代の落とし穴 | model-migration |
| §4 剥がすべきもの以外の prompting | prompting |
| §6 セキュリティの層 | security |
| §7 長時間・自律実行の型 | agent-design / claude-code-workflow |
| 文書の書き方全般 | writing-for-agents |
10. このページの読み方
- 数字（§3）は原典が明示しているものだけ。自分の環境で再現する保証はない。特にモデル世代に依存するものは whats-new と突き合わせる
- §4 と §5 は陳腐化が最も速い。モデルがもう1世代進んだら真っ先に見直す
- §1 と §6 と §7 は最も長持ちする。制約と層構造と失敗モードは、モデルが良くなっても形が変わりにくい