短い答え
CLAUDE.md は、Claude Code がコンテキストとして読み込めるプロジェクト指示ファイルです。プロジェクト構成、コマンド、コーディング規約、テストの期待値、セキュリティ境界、共同作業ルールの記載に適しています。
これは強制実行の仕組みではありません。Claude Code はガイダンスとして読み取ります。特定の時点でルールを実行する必要がある場合は、CLAUDE.md だけに頼らず、フックまたはツール設定を使用してください。
有用な CLAUDE.md は短く、具体的で、継続的に更新されています。各セッションで繰り返し伝えることになるプロジェクトの事実を記載してください。
この情報が役立つ場面
- Claude Code が同じプロジェクト構成やコマンドについて繰り返し質問するとき
- チームで共有するテスト、スタイル、安全性のルールが必要なとき
- 繰り返し渡すコンテキストと Token 使用量を減らしたいとき
- Claude Code がリポジトリ固有の規約を見落とし続けるとき
- 他のエージェントやチームメイトをより早くオンボーディングしたいとき
主な概念
推奨する内容
CLAUDE.md をコンパクトなプロジェクトハンドブックとして記述します。
- プロジェクトの概要と重要なディレクトリの場所
- よく使うビルド、テスト、フォーマットのコマンド
- 編集前に守るべきアーキテクチャ上の境界
- 完了前に実行する最も速いチェック
- 露出させてはいけないシークレット、ログ、非公開設定
- ドキュメント、テスト、命名、エラーハンドリングの規約
よくある間違い
CLAUDE.mdをシステムプロンプトまたは厳格な権限レイヤーとして扱うこと。- 長くしすぎてコンテキストコストが増え、従いにくくすること。
- 古いデプロイメモ、一時的な TODO、期限切れの決定を永遠に追加し続けること。
- API Key、トークン、Cookie、非公開設定をファイルに書き込むこと。
CLAUDE.md、AGENTS.md、Cursor Rules に相互に矛盾する指示を維持すること。
BetterToken について
プロジェクトで BetterToken を使用する場合、CLAUDE.md には、Claude Code が Anthropic 互換の https://www.bettertoken.ai を使用し、Codex と外部ツールが OpenAI 互換の https://www.bettertoken.ai/v1 を使用することを Claude Code に伝えられます。
実際の API Key を CLAUDE.md に記載しないでください。ローカル環境変数、ローカル設定ファイル、または保護されたシークレットシステムに保存します。
関連ドキュメント
- Claude Code とは？どのように動作しますか？
- Claude Code で API Key と Base URL を設定する方法
- Claude Code が多くの Token を使用する理由とコストを減らす方法
- Claude Code 設定ガイド