> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bettertoken.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code の CLAUDE.md とは？どのように書けばよいですか？

> Claude Code における CLAUDE.md の役割、記載内容、避けるべき内容、フックと MCP との違いを説明します。

## 短い答え

`CLAUDE.md` は、Claude Code がコンテキストとして読み込めるプロジェクト指示ファイルです。プロジェクト構成、コマンド、コーディング規約、テストの期待値、セキュリティ境界、共同作業ルールの記載に適しています。

これは強制実行の仕組みではありません。Claude Code はガイダンスとして読み取ります。特定の時点でルールを実行する必要がある場合は、`CLAUDE.md` だけに頼らず、フックまたはツール設定を使用してください。

有用な `CLAUDE.md` は短く、具体的で、継続的に更新されています。各セッションで繰り返し伝えることになるプロジェクトの事実を記載してください。

## この情報が役立つ場面

* Claude Code が同じプロジェクト構成やコマンドについて繰り返し質問するとき
* チームで共有するテスト、スタイル、安全性のルールが必要なとき
* 繰り返し渡すコンテキストと Token 使用量を減らしたいとき
* Claude Code がリポジトリ固有の規約を見落とし続けるとき
* 他のエージェントやチームメイトをより早くオンボーディングしたいとき

## 主な概念

| 概念                  | 意味                                  |
| ------------------- | ----------------------------------- |
| プロジェクトの `CLAUDE.md` | 共有するプロジェクト指示。通常はリポジトリとともにコミットします    |
| 個人ルール               | 常にコミットすべきではないユーザー固有の設定              |
| ローカルルール             | マシン固有のメモまたは一時的な設定                   |
| フック                 | ツール使用の前後に実行されるコマンド。動作を強制する場合に適しています |
| MCP                 | 外部ツールとデータソース。プロジェクトルールファイルではありません   |

## 推奨する内容

`CLAUDE.md` をコンパクトなプロジェクトハンドブックとして記述します。

* プロジェクトの概要と重要なディレクトリの場所
* よく使うビルド、テスト、フォーマットのコマンド
* 編集前に守るべきアーキテクチャ上の境界
* 完了前に実行する最も速いチェック
* 露出させてはいけないシークレット、ログ、非公開設定
* ドキュメント、テスト、命名、エラーハンドリングの規約

長いチュートリアル、一時的な計画、単発タスクのメモは避けてください。ルールが 1 つの領域だけに適用される場合は、より狭くスコープを設定します。動作を強制する必要がある場合は、フックを使用してください。

## よくある間違い

* `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 とは？どのように動作しますか？](/ja/faq/claude-code/what-is-claude-code)
* [Claude Code で API Key と Base URL を設定する方法](/ja/faq/claude-code/api-key-base-url)
* [Claude Code が多くの Token を使用する理由とコストを減らす方法](/ja/faq/token-cost/claude-code-token-usage)
* [Claude Code 設定ガイド](/ja/ai-tools/claude-code)

## 参照

* [Claude がプロジェクトを記憶する方法](https://docs.anthropic.com/en/docs/claude-code/memory)
* [Claude Code フックリファレンス](https://docs.anthropic.com/en/docs/claude-code/hooks)
* [Claude Code のコスト](https://docs.anthropic.com/en/docs/claude-code/costs)