Claudeにコンテキストを与える: CLAUDE.mdとより良いプロンプト

Claude Codeはそのままでもよく機能しますが、プロジェクトの規約を理解し、いくつかのプロンプト習慣を採用すると、著しく効果的になります。このガイドはその両方をカバーしています。

CLAUDE.mdは、Claudeがそのディレクトリ内のすべてのセッションの開始時に自動的に読む平文のマークダウンファイルです。初日の朝に有能な新しいチームメイトに与えるブリーフィングのようなものと考えてください: チームがどのようにやることをするのか、何を避けるべきか、そして重要な部分がどこにあるのか。

プロンプトで参照したり、手動で添付したりする必要はありません。ファイルが存在する場合、Claudeはすでにそれを読んでいます。

Claudeはいくつかの場所を探し、見つけたものを広いものから具体的なものへとマージします:

ほとんどのチームはプロジェクトルートファイルのみが必要です。gitにコミットして、チーム全体が利益を得られるようにしてください。

作業ディレクトリ以上のファイルはセッション開始時に読み込まれ、システムプロンプトの直後にユーザーメッセージとしてClaudeに配信されます(システムプロンプト内に埋め込まれません)。サブディレクトリのCLAUDE.mdファイルは後でオンデマンドで読み込まれます。Claudeがそのサブディレクトリ内のファイルを読むときです。要約や切り詰めはなく、各ターンでディスクから再度読み込まれません。セッション中にファイルを編集した場合、/compactを実行するか/memory経由で開くときに変更が取得されます。それ以外の場合は、次のセッションで有効になります。

Claude for Enterpriseの顧客の場合、コスト図は「すべてのリクエストで読み込まれる」が示唆するよりも優れています。Claude CodeはAnthropicのプロンプトキャッシングをCLAUDE.mdに適用します。セッション内の最初のリクエストはファイルの完全な入力トークン価格を支払います。その後のリクエストは約5分以内に互いに続き、キャッシュにヒットし、はるかに低いキャッシュ読み取り率で請求されます。キャッシュはコンテンツアドレス指定されるため、CLAUDE.mdへの変更はそれを無効にし、次のリクエストは再び完全な価格を支払います。

実際には、サイズの大きいCLAUDE.mdはセッションごとに1回の完全なトークンと、キャッシュの有効期限が切れるのに十分な長さのアイドルギャップの後に1回、メッセージごとに1回ではなく、コストがかかります。ファイルをコンテキストウィンドウスペースとシグナルノイズのために精力的に保つことは依然として価値がありますが、メッセージごとの支出を制御するためだけに行を制限する必要はありません。エンタープライズ使用ダッシュボードでは、ファイルのフットプリントはほぼ完全にキャッシュ読み取りトークンとして表示され、標準入力トークンではなく表示されます。

任意のプロジェクトで、/initを入力します。Claudeはコードベースを探索し、CLAUDE.mdをドラフトします。ビルドコマンド、テストコマンド、構造概要、および検出された規約をカバーします。ドラフトを確認し、不正確なものを削除し、コミットします。これには約5分かかり、永続的に報酬を得られます。

短くシグナル密度の高いファイルを目指してください — 大体200行以下。すべてのリクエストでコンテキストに読み込まれるため、各行はそのコストの価値があるべきです。

含める価値があるもの:

含める価値がないもの:

仕様ではなく、生きたオンボーディングドキュメントのように扱ってください。

セッション中に追加することもできます: /memoryを開いてファイルを直接編集するか、Claudeに「覚える」ルールを求めるだけで、適切なCLAUDE.mdに追加されます。

これらは一般的なプロンプトエンジニアリングのヒントではありません。Claudeが実際のコードベースを読み書きしているときに最も重要な習慣です。

Claudeはコードベース自体を探索できます。何を望んでいるのか、そしてなぜなのかを伝え、どこなのかを理解させてください。

❌ 「userService.tsを開き、validate関数を見つけ、42行目にnullチェックを追加します。」

✅ 「メールのないユーザーは検証ステップをクラッシュさせています。それを優雅に処理し、テストを追加してください。」

要約するのではなく、完全なスタックトレースを貼り付けます。正確なファイル名、行番号、およびメッセージは、Claudeが正しい場所をすばやく見つけることができます。

複数のファイルに触れるもの場合、Shift+Tabを2回押してプランモードにサイクルします(最初のプレスはacceptEditsに入ります)そして尋ねます:

「公開APIにレート制限を追加する方法を計画してください。まだ何も変更しないでください。」

計画を確認し、会話で調整してから、モードを切り替えて「ステップ1を実行してください」と言います。これは、誤解が12ファイルのdiffに変わる前にそれをキャッチします。

Claudeはコードベースを独自に検索できますが、関連するファイルをすでに知っている場合は、そう言ってください — それはより速く、より少ないトークンを使用します。@を使用してパスを参照します。例えば@src/auth/login.ts。

例には「テストが合格する」、「他のハンドラーのスタイルと一致する」、または「新しい依存関係がない」が含まれます。受け入れ基準を事前に述べることは、複数の修正ラウンドよりも効率的です。

長いセッションはノイズを蓄積します。「ログインバグを修正する」から「請求モジュールをリファクタリングする」に切り替えるときは、/clearを実行して新しく開始します。CLAUDE.mdは耐久性のあるコンテキストを前に進めるため、チャット履歴は必要ありません。

最初の答えがオフの場合、リクエスト全体を言い換える必要はありません。単に何が間違っているかを言ってください — 例えば、「それは公開APIを変更します。署名を同じに保ってください。」Claudeはすべてを保持し、その点だけを調整します。