Claude 5モデル向けの新しいコンテキストエンジニアリング規則

• Claude Opus 5とClaude Fable 5では、Claude Codeのシステムプロンプトを80%以上削減しても、コーディング評価で測定可能な性能低下はなかった
• 過去のモデルで最悪の事態を防いでいた詳細なルールは、システムプロンプト・Skills・CLAUDE.md・ユーザー要求の間で衝突することがあり、最新モデルでは周辺コンテキストと自己判断を活用させるほうがよい
• すべての指示やツール例を事前に与える代わりに、表現力のあるインターフェースと、必要な時点で情報・ツールを呼び出す段階的開示(progressive disclosure) を適用する
• CLAUDE.mdにはリポジトリの落とし穴だけを簡潔に記録し、長い指示はSkillsに分離し、仕様・テストスイート・HTMLモック・コード・評価基準表のような豊富な参照資料を活用する構成が推奨される
• /doctorとclaude doctorでSkillsとCLAUDE.mdのサイズを調整でき、最新モデルのコンテキストは反復と過度な制約を減らし、必要なときに関連情報を探せるよう構成すべき

---

プロンプトを超えるコンテキストエンジニアリング

• Claudeがメッセージを処理するとき、ユーザープロンプトは全体コンテキストの一部にすぎず、残りはシステムプロンプト、Skills、CLAUDE.md、メモリなどから組み立てられる
• コンテキストエンジニアリングは複数の要求に共通して適用されるため、個別プロンプトのように具体的に書くのは難しいが、Claude Codeや独自エージェントの結果に大きく影響する
• ユーザー要求を事前に知らない状態で一般的なプロンプトや指示を設計する必要があり、Claudeの能力が向上するほど適切な方式も変わる
• Claude Opus 5とClaude Fable 5では、Claude Codeシステムプロンプトの80%以上を削除しても、コーディング評価で測定可能な性能低下はなかった
• このベストプラクティスはclaude doctorに反映されており、Claude Codeでは/doctorでSkillsとCLAUDE.mdを適切なサイズに調整できる

過度な制約からモデルを解放する

• 既存のClaude Codeは、システムプロンプトだけでなくCLAUDE.mdやSkillsでも過剰な制約を受けていた
  • ある要求では「適切な文書を残せ」と「コメントを追加するな」のような指示が、システムプロンプト・Skills・ユーザー要求を通じて衝突することがある
  • Claudeがユーザー意図を解釈できても、重複や競合する指示のために、行動を決める前により慎重に考えなければならない
• 過去には最悪の事態を避けるためにこうした制約が必要だったが、最新モデルでは複数の制約を削除し、周辺コンテキストと自己判断を活用させられる
• Claude Codeが活用できるツールも増えている
  • 過去にはCLAUDE.mdがメモリ・情報・指示の主要な保存先だった
  • 現在はメモリ、アーティファクト、Skillsを通じて、セッション間でコンテキストを呼び出し共有できる

固定ルールよりコンテキストベースの判断を活用

• 初期のClaude Codeには、ファイル削除のような最悪の事態を防ぐため、常に適切とは限らない強い指示が入っていた
• 以前のシステムプロンプトは、コードに基本的にコメントを書かず、複数段落のdocstringや複数行コメントを禁止し、ユーザーが要求しない限り計画・意思決定・分析文書を作らないよう求めていた
• こうしたルールは一部の要求では不適切になりうる
  • ユーザーが別の文書化の好みを持っている場合がある
  • 複雑なコードの特定部分には複数行コメントが必要な場合がある
• 旧モデルでは保護策がないと誤ったコメントを書くことが多く、こうしたトレードオフが必要だったが、最新モデルは明示的ルールがなくても関連する判断をよりうまく処理できる
• 新しいシステムプロンプトは、「周囲のコードのように読めるコードを書き、コメント密度・命名・慣用表現を合わせよ」というコンテキストベースの指針を使う

例示より表現力のあるインターフェース設計

• 過去のツール利用における中心的ルールは、Claudeに使用例を提供することだった
• 最新モデルでは、例示が探索範囲を特定領域に限定してしまうことがあるため、ツール・スクリプト・ファイルのインターフェースとパラメータの表現力を優先すべき
• Todoツールのstatusをpending、in_progress、completedの列挙型で定義すれば、使い方を自然に示せる
• 1項目だけをin_progressに保つという指示は、要求される動作をインターフェースレベルで具体化する

必要な瞬間に情報を開く段階的開示

• Claude Codeがコーディングに集中していた初期には、コードレビューや検証方法をシステムプロンプトに詳しく書いていた
• この情報は常に必要ではなかったが、特定の作業では重要だった
• 現在は、必要な時点で適切なコンテキストを呼び出す段階的開示を活用できる
  • 検証とコードレビューの指示をそれぞれ別のSkillに移し、Claude Codeが選択的に呼び出せるようにする
  • 一部のツールは遅延ロードされ、エージェントは使用前にToolSearchで完全な定義を検索しなければならない
  • Taskツールのように多くのツールを提供しつつ、必要になるまでコンテキストを占有しないようにできる
• CLAUDE.mdやSkill.mdを、考えうるすべての慣行の中央保管庫にする必要はない
• 代わりに、必要時に呼び出すファイルツリーとして構成でき、このアプローチはタスクごとの動的ワークフローハーネスでも扱われている

反復する指示を単純なツール説明に統合

• 以前のClaudeモデルでは、同じ指示を繰り返す必要があることがあり、コンテキスト先頭より末尾の指示によく従うこともあった
• このため、システムプロンプト本文とツール説明の両方に、同じツール利用指示や例示を入れていた
• 最新モデルでは反復例示を削除し、ツールの使い方をツール説明のみに配置できる

CLAUDE.mdから自動メモリへ移行

• 過去には#ショートカットで情報をCLAUDE.mdに自動記述し、ユーザーがClaudeのメモリを直接保存するよう勧めていた
• 現在のClaudeは、作業やユーザーに関する情報を自動的にメモリ化する

単純な仕様を超える豊富な参照資料

• 計画モードのClaude Codeは、必要時に再参照するためMarkdownの計画ファイルに大きく依存しており、長期プロジェクトではコードベース内に仕様を保存することもあった
• 最新のClaudeは、より複雑な形式の参照資料を処理できる
  • 新しいアーティファクト機能で生成したHTMLアーティファクト
  • 他のコードベースから移植する関数のようなコード
  • 詳細なテストスイートで表現した仕様
• 評価基準表(rubric)は、特定分野の好みや品質基準をClaudeに試行・検証させる別の参照形式でもある
  • 優れたAPI設計とは何か、といった基準を定義できる
  • 動的ワークフローを通じて、その評価基準表を使う検証エージェントを生成できる

コンテキスト構成要素ごとの役割

• システムプロンプト

  • 製品コンテキストと密接に結びついており、Claudeがどの製品内で何の作業をしているかを伝える
  • Claude Codeユーザーが修正することはほとんどないが、独自のエージェントハーネスを作るなら多くの時間を割くべき領域

• CLAUDE.md

  • 軽量に保ち、リポジトリの用途を短く記述しつつ、ほとんどのトークンはコードベース内の注意すべき落とし穴を記録するのに使うべき
  • すべての型を1つの単一ファイルにだけ置くというリポジトリ規則は記録する価値がある
  • ファイルシステムやリポジトリを見ればClaudeが分かる自明な情報は避けるべき
  • 作業検証に複数の固有指示があるなら、検証Skillを作り、CLAUDE.mdから参照する形で段階的開示を適用する

• Skills

  • Claudeが必要なときに情報を見つけられるよう助ける軽量ガイドとして構成する
  • 非常に重要な領域でない限り、過度な制約は避けるべき
  • 長いSkillは複数ファイルに分け、段階的に読み込ませるほうがよい
  • 個人・チーム・製品に特化した見解、知識、ベストプラクティスを含めるときに最も有用

• 参照資料

  • @でファイルをメンションすると、現在の計画に関連する詳細情報をClaudeが確認できる
  • 仕様ファイル、モック、コードベース全体も参照資料になりうる
  • コードはClaudeがよく理解する言語で明確かつ忠実な指示を与えるため、一般にコード形式のファイルを優先するほうがよい
  • デザイン説明やスクリーンショットより、HTMLデザインモックのほうが一般に良い結果を生む

既存コンテキストの単純化

• システムプロンプト、Skills、CLAUDE.md全体で不要なルール・反復・情報を削除し、コンテキストを単純化すべき
• claude doctorコマンドは、この単純化作業を自動で支援する
• 高度なモデル向けのプロンプト作成法は、Claude Fable現場ガイドでさらに確認できる