Claude 5世代モデルのための
「コンテキストエンジニアリング」新ルール

以前の記事では、最新世代のClaude 5モデルへの上手な指示の出し方や、対話を重ねながら「本当に作りたいもの」を見つけていく方法についてお話ししました。

しかし、あなたがClaudeにメッセージを送るとき、その文章(プロンプト)は、Claudeが受け取る情報全体のほんの一部にすぎません。実際には、システムプロンプト、Skills、CLAUDE.mdファイル、メモリなど、さまざまな情報源から「コンテキスト」が組み立てられて渡されています。これを設計する技術を私たちはコンテキストエンジニアリングと呼んでおり、Claude Codeを使うときも、自分でエージェントを作るときも、結果の質を大きく左右します。

ここで難しいのは、コンテキストの性質です。一回きりの質問文と違って、コンテキストはあらゆるリクエストに共通して使われるため、内容をあまり具体的にできません。ユーザーが何を頼んでくるか事前には分からない中で、どうやって汎用的な指示や手引きを書けばよいのでしょうか?

これはClaude自身の能力が進化するにつれて、意外なほど難しい問題になります。直近では、最新世代のClaudeモデルへの指示の出し方が大きく変わったことに私たちは気づきました。Claude Opus 5やClaude Fable 5といったモデル向けには、Claude Codeのシステムプロンプトの80%以上を削除しても、コーディング性能の評価テストで測定できるほどの低下は一切ありませんでした。

この記事では、この新しい世代のモデルへの指示について私たちが学んだことと、それを皆さんのコンテキストエンジニアリングにどう応用できるかをまとめます。なお、これらのベストプラクティスはclaude doctorに組み込みました。Claude Code内で/doctorコマンドを実行すると、SkillsやCLAUDE.mdファイルを適正なサイズに整えるお手伝いをしてくれます。

Claudeの「足かせ」を外す

全体を振り返って分かったのは、私たちがシステムプロンプト・CLAUDE.md・Skillsを通じて、Claude Codeを過剰に縛りすぎていたということです。

たとえば、社内でのClaude Code利用記録を読み返すと、1つのリクエストの中に矛盾した指示が複数混ざっているケースが見つかります。「必要に応じてドキュメントを残すこと」という指示と「コメントは絶対に書くな」という指示が、システムプロンプト・Skills・ユーザーの依頼文の間で衝突している、といった具合です。

Claudeはたいてい、ユーザーの意図をくみ取って正しい答えにたどり着けます。しかし、こうした重複・矛盾した指示があると、何をすべきか決める前に余計な熟考を強いられてしまいます。

こうした制約は、かつては「最悪の事態」(たとえば大事なファイルを消してしまう等)を避けるために必要でした。しかし今では、その多くを削除して、周囲の文脈とモデル自身の判断力に任せられることが分かってきました。

さらに、Claude Codeが使える道具は当時よりずっと増えています。以前のClaudeは、記憶・情報・指針のよりどころとしてCLAUDE.mdに頼っていました。今ではメモリ機能、アーティファクト、Skillsがあり、Claudeはこれらを使って、セッションをまたいで文脈を読み込み・共有する新しい方法を自分で作り出せます。

「これまで」と「これから」

かつてはベストプラクティス(定石)とされていたのに、今では「神話」になってしまったコンテキストエンジニアリングの手法がいくつもあります。順に見ていきましょう。

Claude Codeを最初にリリースした頃は、ファイル削除のような最悪の事態を確実に避ける必要がありました。そのため、「常に正しいとは限らない」強い指示をあえて与えていました。たとえば、かつてのシステムプロンプトにはこう書かれていました。

コードでは:原則としてコメントを書かないこと。複数段落のドキュメント文字列や複数行のコメントブロックは決して書かないこと──最大でも短い1行まで。ユーザーに頼まれない限り、計画書・判断メモ・分析文書を作らないこと。中間ファイルではなく会話の文脈から作業すること。

しかし、一部のケースではこの指示は間違いになります。ドキュメントについてはユーザー自身のこだわりがあるかもしれませんし、非常に複雑なコードの特定の箇所には、複数行のコメントブロックが必要な場合もあります。

それでも、旧世代のモデルではこのガードレールなしだとClaudeの書くコメントが不適切になることが多く、このトレードオフを受け入れるしかありませんでした。しかし新しいモデルは判断力が向上しており、明示的なルールがなくてもこうした判断を適切にこなせます。

新しいシステムプロンプトでは、こう書いているだけです。

周囲のコードに溶け込むコードを書くこと:コメントの密度、命名、書き方の流儀を周囲に合わせること。

ツールの使い方を教える際の鉄則は、「使用例を見せること」でした。ところが最新モデルでは、例を与えると、かえってモデルの探索範囲がその例の枠内に狭められてしまうことが分かりました。

例を並べる代わりに、ツール・スクリプト・ファイルの設計そのものにもっと頭を使いましょう。Claudeにどんなパラメータ(設定項目)を渡せるのか、それをどうすればより表現力豊かにできるのか、という視点です。

たとえば図のTodoツール(やることリスト管理ツール)の例では、ステータスの選択肢を「pending(未着手)/in_progress(作業中)/completed(完了)」の3つに限定して列挙するだけで、使い方のヒントがClaudeに伝わります。「作業中の項目は常に1つだけにする」という一文が、求める挙動の定義になっているわけです。

Claude Codeはコーディングに特化しているため、以前のシステムプロンプトにはコードレビューや検証のやり方について詳細な説明が含まれていました。これらは常に必要なわけではないものの、必要な場面では極めて重要な情報でした。

その後、Claude Codeは段階的開示(progressive disclosure)──適切なタイミングで適切な文脈だけを読み込むこと──が非常に上手になりました。たとえば私たちは、検証とコードレビューの手順をそれぞれ独立したSkillに切り出し、Claude Codeが必要なときだけ呼び出せるようにしました。

段階的開示はSkillsだけの話ではなく、ツールにも使っています。一部のツールは「遅延読み込み(deferred loading)」方式になっており、エージェントは使う前にToolSearch(ツール検索機能)で完全な定義を検索する必要があります。これにより、Taskツール群のような多数のツールを、必要になるまでコンテキストを消費させずに持てるようになりました。

同じことは、皆さん自身のCLAUDE.mdやSKILL.mdファイルにも当てはまります。よくある誤解が、「Claudeは自分で見つけられないから、遭遇しそうなノウハウは全部1か所に集約しておくべきだ」というものです。そうではなく、適切なタイミングで読み込めるファイルのツリー(階層構造)を作ることを検討してください。

初期のClaudeモデルは、指示を繰り返し書く必要があったり、コンテキストの冒頭よりも末尾に書かれた指示のほうに従いやすかったりすることがありました。そのため以前のシステムプロンプトでは、本文中でツールに言及しつつ、ツールの説明文にも同じ指示を書く、といった重複がありました。

現在では、こうした重複した記述は削除でき、ツールの使い方に関する指示は、システムプロンプトではなくツールの説明文の中に一度だけ書けば十分だと分かりました。

以前は、#ホットキーを使ってCLAUDE.mdに自動追記する形で、覚えておいてほしいことをClaudeのメモリに手動保存するよう推奨していました。今ではその代わりに、Claudeが作業とあなたに関係のある事柄を自動的に記憶するようになっています。

プランモード(作業前に計画を立てるモード)では、Claude Codeは計画を書いたMarkdownファイルに大きく依存してきました。計画をファイルとして保存しておけば、必要なときにClaudeが参照できるからです。同様に、長期プロジェクトでは仕様書(スペック)をコードベース内に置いてClaudeに参照させる、というのも定番の手法でした。

しかし、Claudeはますます複雑な参照資料を扱えるようになっています。単純なMarkdownファイルの代わりに、新しいアーティファクト機能で作ったHTMLの成果物を参照させることができます。

参照資料をコードの形で渡すこともできます。仕様書の代わりに、詳細なテストスイート(動作確認プログラム一式)を渡してもいいですし、別のコードベースにある関数を「これを移植して」と渡す形でもかまいません。

ルーブリック(評価基準表)も参照資料の一形態です。ルーブリックを使うと、特定分野におけるあなたの「良し悪しの感覚」(たとえば「良いAPI設計とはどういうものか」)をClaudeが検証できるようになります。具体的には、動的ワークフローを使い、そのルーブリックを持たせた検証役エージェントを立ち上げる、という方法です。

自分のコンテキストにどう応用するか

ここまでの話を総合すると、コンテキストを組み立てるとき、それぞれの構成要素はどうあるべきでしょうか。

システムプロンプト

システムプロンプトは、プロダクト(製品)の文脈と密接に結びついています。Claudeに「自分がどの製品の中で動いていて、何をしているのか」を伝える役割です。Claude Codeを使うだけなら、ここを自分で変更することはまずないでしょう。しかし、自前のエージェント基盤を作るなら、最も時間をかけるべき場所です。

CLAUDE.md

CLAUDE.mdは軽量に保ちましょう。リポジトリ(コード置き場)が何のためのものかは簡潔に述べるにとどめ、トークンの大半は、そのコードベース特有の「落とし穴」の説明に使うのが正解です。たとえば「型定義は1つの大きなファイルに集約し、他の場所には書かない」といった、そのプロジェクト独自のルールです。ファイルシステムやリポジトリを見れば分かる「当たり前のこと」をわざわざ書くのは避けましょう。

段階的開示も積極的に使ってください。たとえば、作業の検証方法について独自の手順がいくつもあるなら、検証用のSkillを作り、CLAUDE.mdからはそれを参照するだけにします。

Skills

Skillsは、必要なときにClaudeが情報を見つけるための軽量なガイドだと考えてください。本当に重要な領域を除いて、縛りすぎないようにしましょう。

長いSkillでは、できる限り段階的開示を使ってください。つまり、複数のファイルに分割して切り出すのです。

Skillsが最も真価を発揮するのは、あなた・あなたのチーム・あなたの製品に固有の意見、知識、ベストプラクティスを記述したときです。

参照資料(References)

@でファイルをメンション(指名)すると、参照資料として含めることができます。参照資料があると、Claudeは現在の計画に関する深い情報を参照できます。

参照資料は、仕様ファイル、モックアップ(デザイン見本)、さらにはコードベース丸ごとでもかまいません。一般には、コードの形になっているファイルを優先すべきです。コードは、Claudeが熟知した言語で書かれた、明確で忠実度の高い指示になるからです。たとえばデザインを伝える場合、文章による説明やスクリーンショットよりも、HTMLで作ったモックアップのほうが、たいてい良い結果を生みます。

まずは「削る」ことから

システムプロンプト、Skills、CLAUDE.mdファイルの全体にわたって、私たちがやったのと同じように、皆さんも簡素化が必要かもしれません。私たちは新コマンドclaude doctorをリリースしました。これを使えば、この簡素化を自動的に行う手助けが受けられます。より高度なモデルへのプロンプトの詳細については、Fableフィールドガイドもご覧ください。