OVERVIEW — 78本を1ページに
sources/ 78本を横断して残るものだけを置く。個々の文書の要約ではなく、複数の原典を並べて初めて見えるもの（数字、判断の分岐点、文書同士の食い違い）を集めている。
索引は SOURCES.md、読む順は README.md。ここは思い出すためのページ。
テーマごとの深掘りは topics/（10本）。このページの各節が、おおむね1つの topic に対応する。
最終更新: 2026-08-12
1. 貫いている一つの制約
78本の大半は、同じ一つの制約から導かれている。別々の文書が独立に同じことを言っている。
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 — 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. — effective-context-engineering-for-ai-agents working memory の容量が限られている人間と同じく、LLM も大量の context を解釈するときに引き出す「attention budget」を持っている。新しいトークンが1つ入るたびに、この予算はいくらか目減りする。
制約から導かれる結論を、原典は記事の結語として置いている。
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 の編集。
委譲の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 から下げる）を選ぶ。
権限（Claude Code）
ルールは deny → ask → allow の順。最初に一致したものが決める。具体性は順序を変えない。 → 広い deny に狭い allow の例外は作れない。
唯一の抜け道: PreToolUse hook の exit code 2 は permission ルールの評価より前に止まるので、「Bash を全許可して一部だけ hook で止める」が成立する。
eval の grader
| 種類 | 強み | 弱み |
|---|---|---|
| code-based | 速い・安い・再現する | 正当なバリエーションに脆い |
| model-based | 柔軟・ニュアンス | 非決定的・人間との calibration が必要 |
| 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 |
コスト
| 数字 | 出所 |
|---|---|
| 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倍 | prompt-caching |
| 16エージェント・2週間・$20,000 で10万行の C コンパイラ | building-c-compiler |
効果
| 数字 | 出所 |
|---|---|
| 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 |
上限・しきい値
| 数字 | 出所 |
|---|---|
| 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 |
4. モデル世代の落とし穴
最新モデルへの移行で最も多い失敗は「古いプロンプトを持ち越すこと」。 しかも足りないのではなく、余計なものが害になる。
最新モデルでは「足す prompting」より 旧世代向けに書いた過剰な指示を剥がす prompting のほうが重要 — claude-prompting-best-practices
剥がすべきもの
| 旧世代で書いていたもの | 最新モデルでの害 |
|---|---|
CRITICAL: You MUST use this tool when... | 過剰発火。Use this tool when... に戻す |
| 「最後に検証ステップを入れよ」 | Opus 5 は指示なしで自己検証する。over-verification になる。書き換えではなく削除 |
| 「ダブルチェックせよ」 | 同上 |
| 「3ツール呼び出しごとに進捗を要約せよ」 | Sonnet 5 / Opus 4.8 は自分で質の高い更新を出す。scaffolding を外す |
| 「もっと徹底的に」（anti-laziness） | 過剰発火 |
| 「思考を見せろ」「推論を説明しろ」 | Fable 5 では reasoning_extraction 拒否を誘発し、フォールバックが増える |
| 「重大な問題だけ報告せよ」（コードレビュー） | 忠実に守るので 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 を切れない |
| Fable 5 / Mythos 5 | thinking 常時オン。1リクエストが数分〜数時間走る（タイムアウトを先に直す） |
thinking と effort の混同
thinkingパラメータ = thinking ブロックで考えるかeffortパラメータ = 応答全体（テキスト + ツール呼び出し + thinking）にどれだけ労力を割くかadaptiveをeffortの値として渡してはいけない（thinkingのモードであって effort のレベルではない）- 費用の厳密な上限は
max_tokensだけ。effortはソフトな指針 effortを変えるとプロンプトキャッシュが壊れる → 会話ごとに固定し、ターン単位の調整は per-message prompting で
→ 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（2024-09）: チャンクに文脈を前置して埋め込め
- effective-context-engineering-for-ai-agents（現在）: まず context に載せられないかを考えよ
→ 1M context の時代に「そもそも RAG が要るか」の判断基準が変わった。原典自身が「20万トークン未満なら全部プロンプトに入れろ」と書いている。
think ツールが自分自身を非推奨にしている
claude-think-tool は 2025-12-15 の更新で 「extended thinking が改善したので、ほとんどの場合そちらを使え」と原典に明記された。ただしポリシー遵守が重い多段ツール使用では依然として参考になる（プロンプトとセットで 54% 改善）。
harness の作り込みが自分の陳腐化を予告している
- effective-harnesses-for-long-running-agents: 4つの成果物を作り込め
- managed-agents: harness はモデルが良くなるほど陳腐化する前提が埋め込まれている
- prompting-claude-fable-5: 旧モデル向けの skill は Fable 5 には規範的すぎて品質を落とす
→ harness と skill は資産であると同時に負債。モデルリリースのたびに削る対象として見直す。
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 | クライアントが強制する。モデルの判断に依存しない |
| 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 内の指示を懐疑的に扱うよう訓練されている。
7. 長時間・自律実行の型
複数の文書が同じ型に収束している。
毎セッションの立ち上がり（effective-harnesses-for-long-running-agents）
1. pwd で作業ディレクトリを確認
2. git ログと progress ファイルを読む
3. 未完了で最優先の機能を1つ選ぶ
4. init.sh で開発サーバを起動
5. 新しい作業の前に 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 を自動で走らせる。特にコードを書く前にテストを生成させる
8. 78本の地図
テーマ別。詳細は各ファイルへ。
基礎（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 の仕組み（6本） — claude-code-best-practices / how-claude-code-works / features-overview / context-window / glossary / whats-new
Claude Code の拡張（8本） — memory / skills / sub-agents / agent-teams / cross-session-messaging / workflows / hooks-guide / hooks
Claude Code の運用（8本） — mcp / permission-modes / permissions / costs / large-codebases / headless / settings / common-workflows
prompting（8本） — claude-prompting-best-practices（living reference）/ prompt-engineering-overview / best-practices-for-prompt-engineering / モデル別4本（prompting-claude-opus-5 / prompting-claude-sonnet-5 / prompting-claude-opus-4-8 / prompting-claude-fable-5）/ prompt-library
context 管理（6本） — context-windows / compaction / context-editing / manage-tool-context / prompt-caching / memory-tool
thinking と effort（3本） — thinking / thinking-steering-and-cost / effort
ツール（6本） — define-tools / tool-search-tool / programmatic-tool-calling / advanced-tool-use / code-execution-with-mcp / desktop-extensions
skill（2本） — agent-skills-overview / equipping-agents-for-the-real-world-with-agent-skills
eval（6本） — develop-tests / demystifying-evals-for-ai-agents / AI-resistant-technical-evaluations / infrastructure-noise / eval-awareness-browsecomp / swe-bench-sonnet
guardrails（4本） — reduce-hallucinations / increase-consistency / mitigate-jailbreaks / reduce-latency
セキュリティ（4本） — claude-code-sandboxing / claude-code-auto-mode / how-we-contain-claude / secure-deployment
エージェント設計の事例（6本） — 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
その他（7本） — contextual-retrieval / claude-think-tool / choosing-a-model / 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 は最も長持ちする。制約と層構造と失敗モードは、モデルが良くなっても形が変わりにくい
鮮度の確認は ./scripts/freshness-check.sh。