Claude 5 の文脈エンジニアリング新ルール

過去と現在

以前から存在した文脈エンジニアリングのベストプラクティスには、すでに誤解されているものも数多くありました。以下にその一例を示します。

過去：Claude にルールを与える

現在：Claude の判断に任せる

Claude Code を初めて導入した際、ファイル削除といった最悪の事態を避けるために、Claude が確実に従うよう厳格なガイドラインを提供する必要がありました。そのため、必ずしも常に正しいとは限らない強力な指示を出すこともありました。例えば、システムプロンプトには以下のように記述していました。

*コードではデフォルトでコメントを書かないこと。複数行のドキュメントストリングや複数行のコメントブロックは書かないこと。短い 1 行が上限です。ユーザーから要求がない限り、計画・判断・分析に関する文書を作成しないこと。中間ファイルではなく、会話のコンテキストに基づいて作業してください。

しかし、特定の種類のプロンプトにおいては、このガイドラインが誤りとなる場合があります。ドキュメント作成の場合、ユーザーには独自の好みがあるかもしれませんし、非常に複雑なコードの一部では複数行のコメントブロックが必要になることもあります。

それでも、以前のモデルではこれらのガードレール（安全装置）がなければ、Claude が生成するコメントは多くの場合不適切となり、私たちはこのトレードオフを受け入れざるを得ませんでした。しかし、新しいモデルは判断力が向上しており、明示的なルールがなくてもこうした意思決定を適切に処理できるようになっています。

新しいシステムプロンプトでは、以下のように記述しています：*周囲のコードに合わせて読みやすく書くこと：コメント密度、命名規則、慣習に合わせてください。

過去：Claude に例を与える

今：インターフェースを設計する

ツールの利用における最大のルールは、Claude に使用例を示すことでした。しかし最新のモデルでは、例を与えることが逆に探索範囲を制限してしまうことが判明しました。

例示に頼るのではなく、ツールやスクリプト、ファイルの設計自体をより意識しましょう。Claude が扱えるパラメータは何か、どうすればより表現力豊かにできるかを考えるのです。

例えば Todo ツールの例では、「pending（保留中）」「in_progress（進行中）」「completed（完了）」という列挙体として status を定義するだけで、Claude に使い方を暗黙的に伝達できます。また「進行中のアイテムは 1 つだけにする」という指示も、期待される動作を明確に定義しています。

次に：すべてを冒頭に配置する

今：段階的開示を活用する

Claude Code はコーディングに特化していたため、システムプロンプトにはコードレビューや検証の方法に関する詳細な情報が含まれていました。これらは常に必要なわけではありませんが、必要となった際には極めて重要な情報でした。

その後、Claude Code は段階的開示の活用において非常に熟練しました。つまり、必要なタイミングで適切なコンテキストを読み込む能力です。具体的には、検証やコードレビューを独立したスキルとして切り出し、Claude Code が状況に応じて選択的に呼び出せるように変更しました。

プログレッシブ・ディスクロージャー（段階的開示）はスキルだけでなく、ツールに対しても活用しています。一部のツールは「遅延読み込み」方式を採用しており、エージェントが実際に使用する前に ToolSearch で完全な定義を検索する必要があります。これにより、必要な時までコンテキストを占有しない Task ツールなど、より多くのツールを追加できます。

このアプローチは、CLAUDE.md や Skill.md ファイルにも適用可能です。「Claude がそれを見つけられないと困るから」という理由で、遭遇しうるあらゆるプラクティスを網羅した中央リポジトリ化すべきだという考えはよくある誤解です。むしろ、必要なタイミングで読み込めるファイルのツリー構造を構築することを検討してください。

以前：繰り返しの記述

現在：シンプルなツール説明

以前の Claude モデルでは、同じ指示が繰り返し必要になったり、コンテキストウィンドウの末尾にある指示の方が先頭の指示よりも重視されたりすることがありました。そのため、システムプロンプトにツールの参照を含める一方で、ツール説明内にも使用手順を記述するという重複が生じていました。

その結果、これらの重複部分を削除し、ツールの使用方法に関する指示はシステムプロンプトではなく、ツール説明自体に記載するだけで十分であることがわかりました。

以前：CLAUDE.md ファイル内のメモリ管理

今：自動メモ機能

以前は、# キーボードショートカットを使って CLAUDE.md に自動的に書き込むことで、ユーザーに情報を保存するよう促していました。しかし現在は、作業やあなたに関連する記憶を Claude が自動的に保存するようになりました。

昔：シンプルな仕様書

今：豊富な参照機能

プランモードにおいて、Claude Code はこれまで計画を記した Markdown ファイルに大きく依存してきました。これらのファイルを計画として保存しておくことで、必要な時に参照できるようにしていました。また、長期的なプロジェクトで作業する際に Claude が参照できるよう、コードベース内に仕様書を保存しておくことも同様に推奨されるベストプラクティスでした。

しかし私たちは、Claude がより複雑な参照を処理できることがわかってきました。単純な Markdown ファイルの代わりに、新しいアーティファクト機能で作成された HTML アーティファクトを参照できるようになりました。

また、コード形式で Claude に参照情報を渡すことも可能です。仕様書は詳細なテストスイートであったり、Claude が移植する必要がある別のコードベース内の関数であったりします。

ルブリックも参照の一種です。ルブリックを使えば、動的ワークフロー を活用して検証エージェントを起動し、特定の分野におけるあなたの嗜好（例えば「良い API デザインとはどのようなものか」など）を試行・検証させることができます。

これらをコンテキストに適用する

これらすべてを組み合わせて、コンテキストを構築するとどうなるのか見てみましょう。

システムプロンプト

システムプロンプトは、その製品のコンテキストと密接に結びついています。これは Claude に、自分がどの製品の中で動作し、何を行っているのかを伝える役割を果たします。

Claude Code を利用する限り、この設定を変更する必要はほぼないでしょう。しかし、独自のエージェントハネス（実行環境）を構築している場合は、ここにお金をかけるべき重要なポイントです。

CLAUDE.md

CLAUDE.md は軽量に保ち、リポジトリの目的を簡潔に記述する程度に留めましょう。トークンの大半は、コードベース内の「落とし穴（gotchas）」や注意すべき点の説明に充てるのが効果的です。例えば、「型定義は単一の巨大なファイルに集約されており、他の場所には存在しない」といった具体的な構成ルールを明記できます。

Claude がファイルシステムやリポジトリ構造から容易に推測できる「自明のこと」を列挙するのは避けましょう。

また、プログレッシブ・ディスクロージャー（段階的な開示）の手法を積極的に活用してください。例えば、作業検証に関する複数の固有手順がある場合は、それらをまとめた「検証スキル」を作成し、CLAUDE.md からそれを参照するように設計します。

スキル

スキルは、Claude が必要な時に情報を検索するための軽量なガイドと捉えてください。ただし、極めて重要な領域を除き、過度に制約を設けることは避けてください。

長文になるスキルについては、可能な限りプログレッシブ・ディスクロージャーを活用し、複数のファイルに分割して記述するのが望ましいです。

最も効果的なのは、特定の意見や知識、あるいは自社チームや製品固有のベストプラクティスをスキルとしてエンコードすることです。

リファレンス

@ 記号を使ってファイルをメンション（言及）することで、リファレンスとして含めることができます。これにより、Claude は現在の計画に関する詳細な情報を参照できるようになります。

これは仕様書やモックアップ、あるいはコードベース全体に含まれている可能性があります。一般的には、Claude が非常に得意とする言語で記されたファイルを選ぶべきです。例えば、デザインの HTML モックアップは、その説明やスクリーンショットよりも、Claude に対して明確で高忠実度の指示を提供するため、より良い結果を生む傾向があります。

シンプル化を試す

システムプロンプト、スキル定義、CLAUDE.md ファイル全体を通じて、私たちが行ったようにシンプル化が必要になる場合があります。これを手動で行うだけでなく、新しいコマンド claude doctor を導入しました。このコマンドが自動的に支援します。特に高度なモデルに対するプロンプトの作成については、Fable フィールドガイドをご覧ください。

*この記事は、Anthropic の技術スタッフである Thariq Shihipar によって執筆されました。*