SUMMARY — 1枚だけ読むなら
OVERVIEW（数字と食い違い）・PRINCIPLES（命令形の一文）・QUOTES（原典のことば）の要点を、 作業の流れ順に8点へまとめた最短版。
ここにあるのは結論だけ。背景と条件は各リンク先にある。 本文の表と数字は OVERVIEW からの抜粋で、正はそちら。 抜いた箇所の下に、元の節と、そちらにしか無い列・行を書いた。
0. 前提 — すべてはここから出ている
The context window is a public good.
context window は公共財である。 — agent-skills-best-practices
Most best practices are based on one constraint: Claude’s context window fills up fast, and performance degrades as it fills.
ほとんどのベストプラクティスは、ひとつの制約に基づいている。Claude の context window はすぐ埋まり、埋まるにつれて性能が落ちる、という制約である。 — claude-code-best-practices
打てる手は5つしかない。使うまでロードしない / 別の context に追い出す / context の外に状態を置く / 要らなくなったら捨てる / そもそも入れない。
排他ではなく層をなすので、どれが自分のトークンを食っているかを先に特定する（/context、manage-tool-context）。
→ OVERVIEW §1「貫いている一つの制約」の5行の表を1文に畳んだもの。5つの手それぞれの具体例（skill の progressive disclosure、MCP の tool search 等）はそちら。
1. 設計 — 単純なほうから始める
When building applications with LLMs, we recommend finding the simplest solution possible, and only increasing complexity when needed.
LLM でアプリケーションを作るときは、可能な限り単純な解を見つけ、必要になったときにだけ複雑さを増すことを勧める。 — building-effective-agents
足すのは引き金が引かれたときだけ。
| 引き金 | 足すもの |
|---|---|
| 規約やコマンドを 2回間違えた | CLAUDE.md |
| 同じ手順書を 3回目貼った | skill |
| 二度と参照しない出力で会話が溢れる | subagent |
| 頼まなくても毎回起きてほしい | hook（指示は要求、hook は強制） |
→ OVERVIEW §2「何を使って拡張するか」の8行から4行。残る4行（user-invocable な skill / MCP server / code intelligence プラグイン / plugin）はそちら。
委譲は3段階。subagent（親にのみ報告・親の context を使う）→ agent team（teammate 同士が直接通信、3〜5人から）→ workflow（中間結果はスクリプト変数、1 run に数十〜数百）。 選ぶ基準は「ワーカー同士が通信する必要があるか」と「計画を誰が持つか」。
→ OVERVIEW §2「委譲の3段階」に表がある。中断されたときにどうなるかはそちらにしか無い。
2. 書く — 渡す言葉
Think of Claude as a brilliant but new employee who lacks context on your norms and workflows.
Claude は、優秀ではあるがあなたの規範や仕事の流れを知らない新入社員だと考えよ。 — claude-prompting-best-practices
書いた後の検算はこの2つ。
- 前提を知らない同僚に見せて、その人が戸惑うなら Claude も戸惑う（claude-prompting-best-practices）
- 「この行を消したら Claude はミスをするようになるか？」ならないなら削れ（claude-code-best-practices）
長さの目安は CLAUDE.md 200行未満 / SKILL.md 500行未満。肥大した CLAUDE.md は、重要なルールがノイズに埋もれて実際の指示を無視させる。
禁じるルールがあるのに守られないなら、ルールを強めるのではなくまずファイルの長さを疑う。
抽象的な指示より望む出力の例が効く。「わからない」と認めてよいと明示すると誤情報が減る。
3. ツール
Provide extremely detailed descriptions. This is by far the most important factor in tool performance.
極めて詳細な説明を書け。これがツールの性能を左右する、群を抜いて最も重要な要因である。 — define-tools
説明は最低3〜4文。引数の形を変えてそもそも間違えにくくする（ポカヨケ）。ただしツールが多いほど良い結果になるとは限らない（writing-tools-for-agents）。
増えたときは症状で対処を選ぶ。
| 症状 | 手段 |
|---|---|
| 定義が先読みで context を食う | tool search（10個以上が目安。30〜50個超で選択精度自体が落ちる） |
tool_result の往復が多い | programmatic tool calling（fan-out 型のみ。逐次型は逆に高くつく） |
| 同じ定義に毎回払っている | prompt caching（初日から。2回目のヒットで元が取れる） |
古い tool_result が溜まる | context editing |
→ OVERVIEW §2「ツールが増えたとき」と同じ4行。しきい値が独立した列になっている。
4. 測る
having a good evaluation set is the most important step in the process
良い evaluation セットを持つことが、この過程で最も重要なステップである — choosing-a-model
- 実際の失敗から取った20〜50タスクで始める。大量のドキュメントを書く「前」に作る
- エージェントが辿った経路ではなく、生み出した成果物を採点する
- 良いタスクとは、2人のドメイン専門家が独立に判定して同じ合否に至るもの
- grader が機能しているかは、多数の試行のトランスクリプトと採点結果を読まない限り分からない
- ベンチマークの差が3ポイント未満なら疑う（インフラ設定だけで6ポイント動く / infrastructure-noise）
→ 数字の出所は OVERVIEW §3「上限・しきい値」。§1 の 3〜5人（agent team）も同じ表にある。
5. 守る — 順序が決まっている
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 自身のファイル・プロセス操作には効かない） |
3. モデル — system prompt のポリシー、tool_result への隔離 | 指示であって強制ではない |
→ OVERVIEW §6「セキュリティの層」と同じ3層。手段が独立した列になっていて、見落とされた実例4件もそちらにある。
片方だけでは不十分。ファイルシステム隔離だけならネットワーク経由で持ち出され、ネットワーク隔離だけならサンドボックスから脱出される。
信頼できない第三者のコンテンツは tool_result にだけ入れる（system プロンプトや素の user text には入れない）。最も弱い層は、自分で作った層である。
6. 長く走らせる
Rather than one-shotting implementations, agents work on only one feature at a time.
実装を一発で書き切らせるのではなく、エージェントには一度に1機能だけを担当させる。 — effective-harnesses-for-long-running-agents
3つの失敗モードと対処。
| 失敗 | 対処 |
|---|---|
| 部分的な進捗で「終わった」と宣言する | 検証（ビルド・テスト・lint）を自動で走らせる |
| 自分の結果を好む（特に検証を頼まれたとき） | 別 context の verifier（self-critique より強い） |
| 目的が徐々にずれる（特に compaction 後） | 目的をファイルに保存する |
→ OVERVIEW §7「3つの失敗モード」と同じ3行。agentic laziness / self-preferential bias / goal drift という名前はそちらにある。
作業するエージェントと判定するエージェントを分けることが強力なレバーになる。 そして、間違いを直そうとするより、やり直すほうが成功率が高いことが多い。
7. モデルは変わり続ける
Skills developed for prior models are often too prescriptive for Claude Fable 5 and can degrade output quality.
以前のモデル向けに作った skill は、Claude Fable 5 には指示が細かすぎることが多く、出力品質を下げうる。 — prompting-claude-fable-5
移行で最も多い失敗は「古いプロンプトを持ち越すこと」。しかも足りないのではなく、余計なものが害になる。剥がす。
| 旧世代で書いていたもの | 最新モデルでの害 |
|---|---|
CRITICAL: You MUST use this tool when... | 過剰発火。Use this tool when... に戻す |
| 「最後に検証せよ」「ダブルチェックせよ」 | Opus 5 は指示なしで自己検証する。書き換えではなく削除 |
| 「3ツール呼び出しごとに進捗を要約せよ」 | scaffolding を外してみる |
| 「もっと徹底的に」（anti-laziness） | 過剰発火 |
→ OVERVIEW §4「剥がすべきもの」の9行を4行に畳んだもの（検証とダブルチェックを1行に統合した）。落ちている4行（「think carefully」／Sonnet 5 向けの回避策／「思考を見せろ」／「重大な問題だけ報告せよ」）と、世代で向きが反転するもの・モデル別の破壊的変更は同じ §4 にある。
harness と skill は資産であると同時に負債で、モデルリリースのたびに削る対象になる。 そして性能が足りない/過剰なときは、モデルを乗り換える前に effort を動かす（choosing-a-model）。
次に読む
| 何が増えるか | |
|---|---|
| QUOTES | 原典のことばだけ57件で通す全体像 |
| PRINCIPLES | 命令形・判断基準になる一文だけ41件 |
| OVERVIEW | 具体的な数字・判断の早見表・原典どうしの食い違い |
| SOURCES | 原典128本の台帳 |