CLAUDE.mdの書き方と運用 — Claude Codeにプロジェクトの文脈を渡す

本記事では、Claude Codeにプロジェクトのルールや文脈を伝えるための設定ファイル「CLAUDE.md」について、公式ドキュメントが示す内容を整理しつつ、書き方と運用のポイントを解説します。読み終えると、自分のプロジェクトに合わせたCLAUDE.mdを書き、運用していくための判断基準が得られることを目指しています。

Claude Code自体のインストールや起動方法については、当サイトの「Claude Code CLIの導入と基本操作（Windows）」を参照してください。本記事はClaude Codeのインストールと初回起動が完了している前提で進めます。

公式ドキュメントは How Claude remembers your project および Best practices for Claude Code にあります。

目次

• CLAUDE.md とは
  • CLAUDE.md の役割
  • CLAUDE.mdはコンテキストとして扱われる
• 配置場所と読み込みの仕組み
• 配置場所ごとの記述例
  • ./CLAUDE.md（プロジェクト指示・チーム共有）
  • ~/.claude/CLAUDE.md（ユーザーグローバル）
  • ./CLAUDE.local.md（プロジェクトローカル・個人用）
• CLAUDE.mdの注入とコンテキスト消費
  • タスクと無関係と判断された指示は無視
  • 行数の上限
• CLAUDE.mdを作成する
  • /initコマンドでたたき台を生成する
  • /memoryコマンドで読み込み状況を確認する
• 書き方のポイント
  • サイズは短く保つ
  • 構造をヘッダーと箇条書きでまとめる
  • 具体的に検証できるレベルまで書く
  • 矛盾する指示を残さない
  • 強調は本当に重要な箇所に絞る
  • 禁止だけでなく代替を示す
• CLAUDE.mdに書かないもの
• 段階的開示で分割する
  • .claude/rules/ でパス指定する
  • @インポートで他ファイルを参照する
  • ポインタで参照する
• 公開リポジトリから学ぶ
• 運用のヒント
  • チーム共有と定期的な見直し
• 補足：Hookについて
• まとめ

CLAUDE.md とは

CLAUDE.md の役割

CLAUDE.mdは、Claude Codeが毎セッションの開始時に自動で読み込むMarkdownファイルです。プロジェクトのルール、技術スタック、よく使うコマンド、注意点などをこのファイルに記述しておくと、Claude Codeはそれをコンテキストとして読み込みます。

LLMはセッション間の記憶を持たないため、CLAUDE.mdがないと毎回ゼロから説明する必要があります。CLAUDE.mdは、新しくチームに加わったエンジニアに最低限知っておいてほしい情報を渡すのと同じです。

CLAUDE.md の有無で、Claude Code の振る舞いが大きく変わります。特に複数人で開発する場合や長期間メンテナンスするプロジェクトでは重要です。

CLAUDE.mdはコンテキストとして扱われる

公式ドキュメントは、CLAUDE.mdを「強制設定ではなくコンテキストとして扱う」と明記しています。つまり、CLAUDE.mdに書いたルールにClaudeが必ず従うとは限りません。「指示が具体的で簡潔であるほど一貫して従う」傾向があるとも述べています。このため、次のように使い分けます。

ガイドルールとして与えたい場合には、簡潔かつ具体的に、評価指標を明確にする形でCLAUDE.mdに記述します。

特定の時点で必ず実行する必要がある指示（例えば、すべてのコミット前またはファイル編集後）の場合は、Hookとして記述します。HookはシェルコマンドやHTTPエンドポイント等で必ず実行されます。

配置場所と読み込みの仕組み

CLAUDE.mdは、用途に応じて4つの場所に配置できます。

Claude Codeを起動すると、作業ディレクトリから親ディレクトリをたどってCLAUDE.mdが探索され、見つかったものはすべて結合されてコンテキストに渡されます。上書きされるわけではなく、すべての内容がClaudeに見えている状態になります。 各ディレクトリ内では CLAUDE.local.md が CLAUDE.md の後に追記されます。

作業ディレクトリより下のサブディレクトリにあるCLAUDE.mdは、 起動時には読み込まれません。Claudeがそのサブディレクトリ内のファイルを読むタイミングで読み込まれます。

複数のCLAUDE.md間で指示が矛盾していると、Claudeはどちらを採用するか保証されません。公式ドキュメントは「矛盾する2つのルールがあると、Claudeはどちらかを恣意的に選ぶことがある」と述べています。同じトピックの指示は1ヶ所にまとめ、矛盾を残さないように書くのが基本です。

配置場所ごとの記述例

ここまでで配置場所ごとの役割を説明しました。実際に何を書くかは個人やチームによって異なりますが、よくある分け方の一例を示します。

./CLAUDE.md（プロジェクト指示・チーム共有）

このプロジェクトに関わる全員に従ってほしい内容を書きます。最も使用頻度が高いファイルです。

# プロジェクト概要
社内向け勤怠管理API。Python 3.12 + FastAPI で実装。
フロントエンドは別リポジトリ（kintai-frontend）。

# よく使うコマンド
- 開発サーバー: `uv run uvicorn app.main:app --reload`
- テスト: `uv run pytest`
- マイグレーション作成: `uv run alembic revision --autogenerate -m "メッセージ"`
- マイグレーション適用: `uv run alembic upgrade head`

# ディレクトリ構造
- `app/api/`: APIエンドポイント
- `app/models/`: SQLAlchemyモデル
- `app/services/`: ビジネスロジック
- `tests/`: pytest用テストコード（`app/` 配下にミラー配置）

# 規約
- 日時はUTCで保持し、表示時のみJSTに変換する
- DBマイグレーションは必ずダウングレード処理も実装する
- 新規エンドポイントには統合テストを追加する

# 注意点
- IMPORTANT: `config/secrets.yml` は編集しない
- 外部API（決済XYZ）はサンドボックスと本番でレスポンス構造が異なる

~/.claude/CLAUDE.md（ユーザーグローバル）

すべてのプロジェクトに共通して適用したい、自分の標準スタイルを書きます。セキュリティの防壁、コミュニケーションの好み、コミット規約など、プロジェクト横断で一貫させたい内容が中心です。

# セキュリティ
- `.env` などの環境変数ファイルや秘密キー（.pem等）の内容を、
  絶対にコンテキストに露出・コミットしないこと
- 秘密情報を扱う必要がある場合は、プレースホルダーを提案し、
  最終編集はユーザーに委ねること

# コミュニケーション基本姿勢
- 回答およびコード内のコメント、ドキュメントは、
  一貫して日本語で出力する
- 技術的な解説は「理由（なぜ）」から述べ、
  その後に具体的な「手順（どうやるか）」を簡潔に示す
- 3ステップを超える複雑な作業を行う場合は、
  実装前に必ず `tasks/todo.md` に計画を記述し、
  ユーザーの合意を求めること

# コミットメッセージ規約
- コミット時は以下の接頭辞（Angular形式）を使用する
  - `feat:` 新機能の追加
  - `fix:` バグの修正
  - `docs:` ドキュメントのみの変更
  - `refactor:` リファクタリング（機能変更なし）

ここに書いた内容はすべてのプロジェクトに適用されます。プロジェクト固有のルールはこちらではなく ./CLAUDE.md に書きます。

./CLAUDE.local.md（プロジェクトローカル・個人用）

このプロジェクトのみ、かつチームに共有したくない個人メモを書きます。.gitignore に追加してリポジトリには含めません。

# 個人メモ

## ローカル環境
- ローカルDB: `postgresql://localhost:5433/myapp_dev`
- ホストのスペック都合でテスト並列数は2に制限（pytest -n 2）

## 試行中の指示
- 試験的にBunを使う作業ブランチでは npm test ではなく bun test を実行する
- 安定したらチーム用 CLAUDE.md に移す

## TODO
- リファクタリング待ちのファイル: `src/legacy/*`
- 動作確認が必要なエンドポイント: `/api/v2/reports`

実験的な指示や個人用メモを試したい場合、まず CLAUDE.local.md に書いて運用してみて、有用だと判断できたものをチーム用の CLAUDE.md に昇格させる、という使い方ができます。

CLAUDE.mdの注入とコンテキスト消費

タスクと無関係と判断された指示は無視

CLAUDE.mdを使い始めると「書いた指示が無視される」という経験をすることが多いです。Claudeは「CLAUDE.mdの内容が現在のタスクに関連する場合だけ参照する」という前提で動いていると考えられます。タスクに無関係と判断された指示は無視されることがあります。

CLAUDE.mdに特定タスクでしか使わない指示を大量に詰め込むと、ファイル全体が「関連性の低いコンテキスト」と見なされ、本来守ってほしい指示まで埋もれてしまいます。これがCLAUDE.mdを短く・普遍的な内容に絞るべき大きな理由です。

行数の上限

公式は1ファイルあたり200行以下を目安として推奨しています。長くなるほどコンテキストを消費し、遵守率も下がるとされています。注意すべき点として、行数が増えると後に追加した指示だけが無視されるのではなく、すべての指示の遵守率が一様に低下します。一つ指示を増やすことは、既存の指示の効きも弱める行為です。

さらにClaude Code自身のシステムプロンプトにも内部的な命令が含まれており、CLAUDE.mdに使える予算はその分だけ少なくなります。これらの事情から、CLAUDE.mdは「書ける量」ではなく「書くべき最小量」を目指すのが現実的です。

CLAUDE.mdを作成する

/initコマンドでたたき台を生成する

CLAUDE.mdを一から書くのは大変なので、まずはClaude Codeに自動生成させるのが効率的です。プロジェクトのルートディレクトリでClaude Codeを起動し、対話モードで /init を実行します。

cd ~/my-project
claude

起動後のプロンプトで以下を入力します。

/init

Claude Codeはプロジェクトのコードベースを分析し、ビルドシステム、テストフレームワーク、コードパターンを検出してCLAUDE.mdのたたき台を生成します。CLAUDE.mdが既に存在する場合、/init は上書きせずに改善案を提案します。

ただし /init の出力をそのまま使うのは避けてください。自動生成された内容には、Claudeがコードから自力で読み取れる自明な情報や、冗長な記述が含まれることが多いです。前述の通りCLAUDE.mdの肥大化は遵守率の低下に直結するため、生成された内容は一行ずつ精査し、不要なものを削る作業が必須です。

/initが生成するのは出発点です。Claudeがコードから読み取れない情報（プロジェクト固有の慣習や運用上の注意点など）を、運用しながら手で追記して育てていくのが基本です。

/memoryコマンドで読み込み状況を確認する

セッション中に読み込まれているCLAUDE.md、CLAUDE.local.md、ルールファイルを確認したいときは、対話モードで /memory を実行します。

/memory

読み込まれているファイルが一覧表示されるので、選択するとエディタで開けます。意図したファイルが読まれているかの確認や、その場で編集したい場合に便利です。/memory では自動メモリのオン・オフの切り替えや、自動メモリフォルダへのアクセスもできます。

書き方のポイント

CLAUDE.mdは通常のドキュメントと違い、AIが読んで動作するためのファイルです。公式ドキュメントが挙げている観点を中心に、押さえておきたいポイントを紹介します。

サイズは短く保つ

CLAUDE.mdは毎セッションでコンテキストウィンドウに読み込まれます。公式は 1ファイルあたり200行以下を目安とすることを推奨しています。長すぎるファイルはコンテキストを消費するだけでなく、遵守率が下がるとされています。

肥大化を防ぐコツとして、公式は「この行を削除したらClaudeが間違えるか？」と自問する方法を紹介しています。答えがノーなら削除して構いません。ファイルが大きくなってきた場合は、@インポートや.claude/rules/を使った分割を検討します。

構造をヘッダーと箇条書きでまとめる

公式は、CLAUDE.mdを書く際にMarkdownのヘッダーと箇条書きで関連する指示をグループ化することを推奨しています。Claudeは構造化されたセクションのほうが、長い段落よりも読み取りやすくなります。

# コードスタイル
- ES Modules（import/export）構文を使う。CommonJS（require）は使わない
- import は分割代入で書く

# ワークフロー
- 一連のコード変更が終わったら必ず型チェックを実行する
- パフォーマンスのため、テストスイート全体ではなく個別テストの実行を優先する

見出しはREADMEの慣習に沿ったもの（Commands、Structure、Conventions、Testingなど）を使うと、Claudeが期待通りに解釈しやすくなります。

具体的に検証できるレベルまで書く

抽象的な指示はAIに伝わりません。コマンド名、パス、数値など、検証可能な具体性を持たせます。公式が挙げている対比例は以下の通りです。

理由を併記すると、より一般化された判断ができるようになります。「force pushはしない」だけより「force pushはしない。共有履歴を書き換え、他のメンバーに復旧できない影響を与えるため」と書くほうが、Claudeは類似のリスクのある操作（共有ブランチでの git reset --hard など）にも慎重になります。

矛盾する指示を残さない

「フォーマッタはruffを使う」と書いた後、別の場所で「blackを使う」と書いてあると、Claudeはどちらかを恣意的に選びます。CLAUDE.md内、サブディレクトリのCLAUDE.md、.claude/rules/ などを横断して、定期的に矛盾や古い指示を取り除きます。

強調は本当に重要な箇所に絞る

特に守ってほしい指示には「IMPORTANT」「YOU MUST」のような強調語を加えると遵守率を高められます。

# データベース
- IMPORTANT: 必ずパラメータ化クエリを使う。SQL文字列を結合しない
- YOU MUST マイグレーションはトランザクション内で実行する

ただし、すべてを強調すると効果が薄れます。本当に重要な数項目に絞ってください。どうしても守らせたい処理は、CLAUDE.mdの指示ではなくHookで自動化するほうが確実です。

禁止だけでなく代替を示す

否定だけの制約は避けます。「--foo は使うな」だけでは、Claudeはその場面で何をすれば良いか分からなくなります。何をすべきかを示した上で、ついでに禁止を明示する構造にします。

悪い例: --legacy-peer-deps フラグは使わないこと

良い例: パッケージを互換性のあるバージョンに更新して依存関係の競合を解決すること
       （--legacy-peer-deps は使わない）

CLAUDE.mdに書かないもの

公式ドキュメントは、CLAUDE.mdに書くべきでないものも明示しています。CLAUDE.mdには「Claudeが自力では分からないこと」を書きます。

特に避けたいのは コードスタイルの詳細ルール です。フォーマット・インデント・import順序のような決定的な処理は、ESLint、Prettier、Ruff、Biomeなどのリンター・フォーマッタに任せるほうが速く、安く、100%の一貫性で処理できます。命令予算をスタイルルールで消費するのは無駄が大きいです。Claude CodeのHookを使うと、編集後やコミット前に自動でフォーマッタを実行できます。

機密情報（APIキー、パスワード、トークン、データベース接続文字列など）も書いてはいけません。CLAUDE.mdはGitにコミットされる前提のファイルなので、機密情報を含めるとリポジトリ経由で流出するリスクがあります。

必ず実行させたい処理もCLAUDE.mdではなくHookに書きます。CLAUDE.mdは助言として扱われますが、Hookは決定論的に動作します。

段階的開示で分割する

ルートのCLAUDE.mdを短く保ちつつ、必要な情報をClaudeに渡すには、「常に必要な情報」と「必要なときだけ読み込む情報」を分離します。

.claude/rules/ でパス指定する

.claude/rules/ 配下のMarkdownファイルは、関心ごとに分けてルールを記述できます。Markdownファイルは配置するだけで自動的に読み込まれます。YAMLフロントマターでパス指定（paths）を行うと、特定のファイルを扱うときだけそのルールが適用されます。

---
paths:
  - "src/api/**/*.ts"
---

# APIエンドポイントの規約

- すべてのエンドポイントで入力バリデーションを実施する
- エラーレスポンスは統一フォーマット（`lib/api-error.ts`）を使用する
- ページネーション対応のリストには `limit` と `offset` を含める

パス指定することにより、APIに関する作業中だけそのルールが読み込まれ、フロントエンド作業時には命令予算を消費しません。複数のパスをカンマ区切りで指定することもできます。これにより、そのファイルを触るとき以外は無駄にLLMのコンテキスト予算を消費させることがないため、節約できます。後述の/memoryを使用することで、読み込まれているかどうかを確認できます。

@インポートで他ファイルを参照する

CLAUDE.mdから @ 構文でファイルを参照できます。相対パス・絶対パスに対応し、最大5階層まで再帰的にインポートが解決されます。

プロジェクトの概要は @README.md を、利用可能なnpmコマンドは @package.json を参照する。

# 追加の指示
- Gitワークフロー: @docs/git-instructions.md
- 個人設定の上書き: @~/.claude/my-project-instructions.md

ここで重要な注意点があります。@でインポートしたファイルは起動時にすべてコンテキストに展開されます。@インポートはファイルを整理する手段であって、コンテキスト消費を減らす効果はありません。

500行のアーキテクチャ文書を @ で取り込めば、毎セッション500行分の予算を消費します。大きいファイルは @ でインポートせず、次に紹介するポインタ方式を使うべきです。

コンテキスト消費を減らしたい場合は、.claude/rules/ にルールとして配置し、関連ファイルを開いたときだけ読み込まれるようにします。

ポインタで参照する

公式の @ 構文を使わず、文章で参照先を伝える方法もあります。

## テスト
テストを書く際は ./docs/testing.md を参照すること。

このように書いておくと、Claudeがテストを書こうとしたタイミングで自発的にファイルを読みに行くことが期待できます。.claude/rules/ のパス指定がファイルパスで判断するのに対し、こちらは「やろうとしていること」で判断する形になります。

ポインタ方式のメリットは、起動時にはコンテキストを消費せず、必要なときだけ読み込まれることです。デメリットは「Claudeが読みに行ってくれる保証はない」ことです。確実性を優先するなら .claude/rules/ のパス指定、コンテキスト効率を優先するならポインタ、と使い分けます。

公開リポジトリから学ぶ

優れたCLAUDE.mdの書き方を学ぶには、実際の公開プロジェクトを見るのが実践的です。GitHubで公開されている awesome-claude-md は、各種言語・規模のプロジェクトから良質なCLAUDE.mdを厳選し、それぞれに分析を加えたリポジトリです。自分のプロジェクトに似たタイプを選んで参考にすると、書き始めるハードルが下がります。

運用のヒント

CLAUDE.mdは一度書いて終わりではなく、プロジェクトの成長に合わせて育てていくものです。

チーム共有と定期的な見直し

プロジェクトルートのCLAUDE.mdは、Gitにコミットしてチームで共有することが推奨されます。一方、CLAUDE.local.md は個人用なので .gitignore に追加してリポジトリには含めません。

# .gitignore
CLAUDE.local.md
.claude/settings.local.json

CLAUDE.mdの変更はPRレビューの対象に含めると、ルールの追加・変更がチームで合意される文化が作れます。公式も「CLAUDE.mdをコードのように扱い、問題が起きたらレビューし、定期的に剪定する」ことを推奨しています。

公式が挙げる見直しのタイミングは以下の通りです。

• Claudeがルールに反する動作を繰り返す（ファイルが長すぎてルールが埋もれている可能性）
• CLAUDE.mdに書いてある内容についてClaudeが質問してくる（表現が曖昧）
• 200行を大きく超えてきた

見直しの観点としては以下の通りです。

• 古い指示や解決済みの注意書きを削除する
• Claudeが自然に正しく動作する指示は削除して構わない
• 矛盾する指示や重複を整理する
• 必ず実行させたい処理はHookに移す
• 新しく増えた技術スタックや規約を追加する

補足：Hookについて

本記事ではCLAUDE.mdの代わりにHookを使うべき場面が何度か出てきました。Hookについて簡単に補足しておきます。

Hookは、Claude Codeの特定のライフサイクルイベントに対して、シェルコマンドを自動実行する仕組みです。CLAUDE.mdの指示と違い、Claudeの判断を介さず決定論的に実行されます。「コミット前にフォーマッタを必ず走らせたい」「ファイル編集後に必ずlintを通したい」といった、確実性が必要な処理に向いています。

Hookの設定ファイルはJSONファイルで.claude/settings.jsonに記述します。チームで共有しない個人用設定は.claude/settings.local.json（.gitignoreに追加）に書きます。

主なイベント（実行のトリガー）は以下の通りです。

最もよく使われるのは PostToolUse で、ファイル編集後の自動フォーマット・lintに利用されます。Pythonプロジェクトで ruff format を自動実行する例は以下のようになります。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs -r ruff format"
          }
        ]
      }
    ]
  }
}

matcher で対象ツール（ここではEditとWrite）を指定し、command で実行するシェルコマンドを記述します。Edit|Write は「Claudeがファイルを書き換えたときだけ動かす」という条件で、条件を満たしたときに書き換えたファイルのパスがJSONで渡ってきます。jq でそのパスを取り出して、ruff format 書き換えられたファイル を実行しています。

Hookの詳細な仕様、利用可能なすべてのイベント、環境変数の一覧、セキュリティ上の注意点については、公式ドキュメントの Hook を参照してください。

まとめ

本記事では、CLAUDE.mdの役割・書き方・運用について、公式ドキュメントに基づいて整理しました。要点を以下にまとめます。

• CLAUDE.mdはClaude Codeへの持続的な指示。ただし強制ではなくコンテキストとして扱われる
• 配置場所は4種類（管理ポリシー・ユーザーグローバル・プロジェクト指示・ローカル指示）
• 行数は短く保つ（公式は1ファイルあたり200行以下を目安）
• 各行は「削除したらClaudeが間違えるか？」テストに合格するもののみ残す
• スタイルルールはリンター・フォーマッタに、必ず実行させたい処理はHookに委譲する
• 段階的開示（.claude/rules/ のパス指定、ポインタ参照）でコンテキストを節約する
• フィードバックループで実問題から学び、定期的に改定する

CLAUDE.md自体の書き方も、Claudeを使いこなすための重要なスキルの一つです。完璧を目指さず、小さく始めて運用しながら育てていくのがおすすめです。

実例から学びたい場合は、awesome-claude-md の各プロジェクトのCLAUDE.mdを読むのが近道です。