Claude CodeのCLAUDE.md、置き場所と書き方を完全ガイド

CLAUDE.mdはどこに置けばいいのか

Claude Codeを使い始めると最初につまずくのが「このファイルを一体どこに置けばいいのか」問題だ。結論から言うと、CLAUDE.mdはスコープによって置く場所が異なり、Claude Codeはこれらのファイルをすべて読み込んで一つのコンテキストにまとめる。場所ごとに整理するとこうなる。

グローバル（ユーザー）設定: ~/.claude/CLAUDE.md。どのプロジェクトでClaude Codeを実行しても常に読み込まれるファイルだ。コーディングスタイルの好みや個人的に好きなツールの使い方など、プロジェクトに関係なく常に適用したいルールをここに書く。例えば「コミットメッセージは必ず日本語で書く」「パッケージマネージャーはnpmではなくpnpmを使う」といった個人の習慣がこれに当たる。

プロジェクト設定: プロジェクトルートの./CLAUDE.mdまたは./.claude/CLAUDE.md。チーム全体で共有するルールなのでgitでコミットしてバージョン管理する。ビルドコマンド、アーキテクチャの説明、コーディング規約など、このプロジェクトで作業する人なら誰もが知っておくべき内容を書く。

ローカル（個人）設定: ./CLAUDE.local.md。プロジェクトルートに置くが.gitignoreに追加して自分だけが見るファイルにする。ローカル開発サーバーのアドレスや個人のテストデータのパスなど、チームと共有する必要のない情報を書く。

サブディレクトリのCLAUDE.md: モノレポのような大きなプロジェクトではsrc/api/CLAUDE.md、packages/web/CLAUDE.mdのようにサブディレクトリごとにCLAUDE.mdを個別に置くこともできる。これはセッション開始時に無条件で読み込まれるのではなく、Claudeがそのディレクトリ内のファイルを実際に読むときにオンデマンドで読み込まれる。つまりsrc/api/配下で作業するときだけsrc/api/CLAUDE.mdがコンテキストに入ってくる。

組織管理ポリシー: macOSは/Library/Application Support/ClaudeCode/CLAUDE.md、Linuxは/etc/claude-code/CLAUDE.md、WindowsはC:\Program Files\ClaudeCode\CLAUDE.md。IT/DevOpsチームがMDMのようなツールで配布する組織全体のポリシーなので、個人でオフにすることはできない。

読み込み順序とマージ方式

ここで重要な誤解が一つある。複数のCLAUDE.mdファイルがあると「一番近いもの一つだけ」が適用されると思われがちだが、実際は見つかったファイルがすべてコンテキストに連結（concatenate）される。読み込み順序はスコープが広いものから狭いものへ、という順だ。

  1. 組織管理ポリシー（managed policy）
  2. ユーザーグローバル ~/.claude/CLAUDE.md
  3. プロジェクト ./CLAUDE.md または ./.claude/CLAUDE.md
  4. ローカル ./CLAUDE.local.md

Claude Codeは現在の作業ディレクトリから上へたどりながら、各ディレクトリのCLAUDE.mdとCLAUDE.local.mdをすべて探す。foo/bar/で実行した場合、foo/CLAUDE.mdが先に、foo/bar/CLAUDE.mdがその後に配置される。つまり実行位置に近い指示ほど後で読まれるため優先度が高くなる構造だ。同じディレクトリ内ではCLAUDE.local.mdがCLAUDE.mdの後に続く。

実際にどのファイルが読み込まれたか確認するには、セッションで/contextを実行してMemory filesの一覧を見ればいい。ファイルを作ったのにここに表示されない場合は、パスが間違っているか読み込み対象外の場所にある。

サブディレクトリのCLAUDE.md、こう活用すると良い

モノレポでフロントエンドとバックエンドの規約がまったく違うなら、ルートのCLAUDE.md一つに全部詰め込むよりこう分けたほうがいい。

project-root/
├── CLAUDE.md              # 전체 아키텍처, 공통 규칙
├── frontend/
│   └── CLAUDE.md          # React 컨벤션, 컴포넌트 구조
└── backend/
    └── CLAUDE.md          # API 설계 규칙, DB 마이그레이션 방법

frontend/内のファイルを触るときだけfrontend/CLAUDE.mdが読み込まれるので、バックエンド作業中に不要なコンテキストが混ざらない。もっと細かく分けたいなら、.claude/rules/ディレクトリにpathsフロントマターでスコープを指定したルールファイルを置く方法もある。

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

# API 개발 규칙

- 모든 엔드포인트는 입력 검증을 거쳐야 한다
- 에러 응답은 표준 포맷을 따른다

この方式ではsrc/api/配下のTypeScriptファイルを扱うときだけルールがコンテキストに入るため、CLAUDE.md一つにあらゆるルールを詰め込んで毎セッションのコンテキストを無駄にするのを防げる。

CLAUDE.mdに何を書くべきか

核心となる基準は一つだ。「毎回また説明し直しているもの」を書く。Claudeが同じミスを二度繰り返したとき、コードレビューでClaudeが知らなかったこのプロジェクト特有の慣習が明らかになったとき、新しいチームメンバーにも同じように伝えなければならない内容があるときにCLAUDE.mdへ追加する。

書くべきこと:

  • ビルド/テスト/リントのコマンド（npm run build、pytest -x、make lintなど実際に実行するコマンド）
  • プロジェクトアーキテクチャの概要 — ディレクトリ構造が何を意味するか
  • コーディング規約 — インデント、命名、importの順序などツールのデフォルトと異なるもの
  • Claudeがよく間違える部分についての明示的な指示
  • 絶対にやってはいけないこと（例: 特定ファイルの直接編集禁止、特定ライブラリの使用禁止）

書くべきでないこと:

  • コードベースを読めば自動的にわかるディレクトリ構造の羅列
  • package.jsonを見ればわかる依存関係リスト
  • 冗長すぎる背景説明

文書自体も「良いコードを書け」のような漠然とした文よりも、「インデントは2スペースを使う」「コミット前にnpm testを実行する」「APIハンドラーはsrc/api/handlers/にある」のように検証可能な具体的な文のほうがはるかに守られやすい。CLAUDE.mdはシステムプロンプトではなく、セッション開始時にユーザーメッセージの形で注入されるコンテキストなので、強制ルールではなく参考指針として扱われる点も覚えておくといい。必ず守らなければならない動作（コミット直前の実行など）はCLAUDE.mdではなくフック（hook）で強制するのが正しい。

ファイルサイズにも気を配る必要がある。200行を超えるとコンテキスト消費も増え、指示の遵守率も下がるというのが公式ガイドだ。内容が長くなる場合は.claude/rules/に分割するか、@パスインポート構文で別のファイルを参照する方式を使う。ただし、インポートしたファイルもセッション開始時に同じように読み込まれるため、コンテキスト節約目的ではなく純粋にファイル構成を整理する用途としてのみ有効だ。インポートは最大4段階まで再帰的にたどられる。

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

ホームディレクトリの外を指すインポート（例: @~/.claude/my-project-instructions.md）は、プロジェクトのCLAUDE.mdにある場合「external import」として分類され、初めて検出されたときに承認ダイアログが表示される。他の人がコミットしたプロジェクトファイルが自分のホームディレクトリのファイルをこっそり引き込むのを防ぐための安全装置だ。

AGENTS.mdと併用する方法

すでに他のAIコーディングツール向けにAGENTS.mdを使っているなら、Claude CodeはAGENTS.mdを直接読まないという点を知っておく必要がある。代わりにCLAUDE.mdを作ってインポートすれば、重複なく両方のツールが同じ指示を共有できる。

@AGENTS.md

## Claude Code

`src/billing/` 하위 변경은 항상 plan mode를 사용한다.

あるいはシンボリックリンクで処理してもいい。

ln -s AGENTS.md CLAUDE.md

Windowsではシンボリックリンクの作成に管理者権限が必要なので、@AGENTS.mdインポート方式を使うほうが楽だ。

/initで自動生成する

空のプロジェクトにCLAUDE.mdを最初から手で書く必要はない。Claude Codeのセッションで/initを実行すると、コードベースを解析してビルドコマンド、テスト方法、プロジェクトの規約を自動で抽出しCLAUDE.mdを生成してくれる。すでにCLAUDE.mdがある場合は上書きせず改善案を提示する。その後はClaudeが自力で把握できない内容（チーム内部のルール、デプロイ手順など）を手で調整すればいい。

実践CLAUDE.md例

Next.js + tRPC + Prismaで構成された実際のプロジェクトなら、こんな形で書く。

# 프로젝트 개요

Next.js 15 App Router 기반 SaaS 대시보드. tRPC로 API를 구성하고
Prisma + PostgreSQL을 쓴다. 인증은 next-auth v5.

## 빌드 & 테스트

- 개발 서버: `pnpm dev`
- 타입 체크: `pnpm typecheck`
- 테스트: `pnpm test` (vitest, watch 모드는 `pnpm test:watch`)
- 커밋 전 반드시 `pnpm lint && pnpm typecheck` 통과 확인

## 아키텍처

- `src/server/routers/`: tRPC 라우터, 도메인별로 파일 분리
- `src/server/db/schema.prisma`: DB 스키마, 마이그레이션은
  `pnpm prisma migrate dev --name <설명>`으로 생성
- `src/app/`: App Router 페이지. 서버 컴포넌트가 기본값이며
  클라이언트 컴포넌트는 파일 최상단에 `"use client"` 명시

## 컨벤션

- 컴포넌트는 named export만 사용, default export 금지
- API 에러는 `TRPCError`로 던지고 절대 `throw new Error()` 직접 사용 금지
- import 순서: 외부 패키지 → `@/` 절대경로 → 상대경로

## 주의사항

- `src/legacy/` 디렉토리는 마이그레이션 대상이라 신규 코드 추가 금지
- 결제 관련 로직(`src/server/routers/billing.ts`)은 수정 전 반드시
  테스트 케이스부터 작성

この程度の分量なら200行制限にも余裕があり、Claudeが毎回また聞き直していたこと（ビルドコマンド、マイグレーション方法、エラー処理の規約）を一度に解決してくれる。

日本語で応答させる

Claude Codeが英語で答えるのが煩わしいなら、CLAUDE.mdに明示的に日本語使用を指示すればいい。

## 言語設定

- すべての応答、コミットメッセージ、コードコメントは日本語で書く。
- ただし変数名・関数名などのコード識別子は英語の慣習に従う。
- エラーメッセージやログ文字列も日本語で書く。

常にグローバルで適用したいなら~/.claude/CLAUDE.mdに、このプロジェクトだけに適用したいならプロジェクトルートのCLAUDE.mdに書けばいい。ただしCLAUDE.mdは強制ルールではなくコンテキストなので、100%の遵守を保証するわけではない。指示があいまいだったり他のCLAUDE.mdの内容と衝突すると、Claudeが任意にどちらかを選んでしまうことがあるので、「常に日本語で」のように具体的で明確な文で書くことで遵守率が上がる。

問題が起きたときのデバッグ方法

CLAUDE.mdを作ったのにClaudeが指示に従わない場合は、次の順番で確認する。

  1. /contextを実行してMemory filesの一覧に該当ファイルが実際に読み込まれているか確認する。
  2. ファイルの場所が正しいスコープにあるか再確認する。サブディレクトリのCLAUDE.mdは、そのディレクトリのファイルをClaudeが実際に読んで初めて読み込まれる点を見落としがちだ。
  3. 指示をより具体的に書き換える。「コードをきれいに書け」より「インデントは2スペース、セミコロンを使う」のほうがはるかに守られる。
  4. 複数のCLAUDE.mdファイルの間で矛盾するルールがないか点検する。
  5. /compactでコンテキストを圧縮したあとに指示が消えたように感じたら、プロジェクトルートのCLAUDE.mdは圧縮後にディスクから再度読み込まれて自動的に再注入されるが、サブディレクトリのCLAUDE.mdやpathsフロントマター付きのルールは自動で再注入されない。該当ディレクトリのファイルを再び読むときだけ再読み込みされる。

特定のタイミングで必ず実行されるべき動作（例: コミット前に必ず特定のスクリプトを実行する）は、CLAUDE.mdで指示するのではなくフックで強制するのが正しい。CLAUDE.mdはあくまでClaudeの判断を助けるコンテキストであり、クライアントレベルで強制される設定ではないからだ。

このように場所ごとの役割を正確に分け、ファイルを短く具体的に保ち、必要なときだけ読み込まれるサブディレクトリ/rules構造を活用すれば、CLAUDE.mdは毎セッションの繰り返し説明をなくしてくれる最も効率的な仕組みになる。

CLAUDE.mdとauto memoryは別物だ

CLAUDE.mdだけを使っていると見落としがちな部分がauto memoryだ。どちらも毎セッションのコンテキストに読み込まれる点は同じだが、役割はまったく異なる。CLAUDE.mdは人が直接書くルールで、auto memoryはClaudeが作業中に自ら把握した事実を保存しておく自動メモだ。例えばセッション中に「ビルドコマンドが実はpnpm build:prodだった」とClaudeが自分で突き止めた場合、その情報はauto memoryに自動的に保存されることがある。

auto memoryはリポジトリごとに~/.claude/projects/<project>/memory/以下に蓄積される。このディレクトリ内のMEMORY.mdが索引の役割を果たし、セッション開始時にこのファイルの先頭部分（最大200行または25KB）だけが読み込まれる。詳細な内容はdebugging.md、api-conventions.mdのようにテーマ別ファイルに分けられ、これらのファイルは必要なときだけオンデマンドで読まれる。/memoryコマンドでこのフォルダを開いて、Claudeが何を覚えているかを直接確認・編集することもできる。

CLAUDE.mdに書くかauto memoryに任せるか迷ったら、基準はこうだ。チーム全体が常に知っておくべきで、コードレビューで文書化すべきルールならCLAUDE.mdに手で書く。逆にセッション中にClaudeが試行錯誤の末に見つけた些細なコツならauto memoryに任せても構わない。「常にpnpmを使う」のようなチームの規約はCLAUDE.mdに、「このリポジトリのテストはローカルのRedisが立っていないと通らない」のような環境固有の事情はauto memoryに自然に蓄積させる、という具合だ。

よくある間違いいくつか

CLAUDE.mdを使っていると繰り返し出てくるミスのパターンがある。

すべてを一つのファイルに詰め込む。 プロジェクトが大きくなるほどCLAUDE.md一つにフロントエンド、バックエンド、インフラのルールを全部書きたくなるが、そうすると200行の推奨上限をすぐに超えてしまう。サブディレクトリのCLAUDE.mdや.claude/rules/に分けるほうが長期的にメンテナンスしやすい。

抽象的な指示だけを書く。 「良いコードを書け」「一貫性を保て」といった文はClaudeの立場からすると検証する基準がなく、事実上無視されやすい。「関数は30行を超えない」「エラーは必ずカスタムのAppErrorクラスで投げる」のように判断基準が明確な文に変えてこそ実際に守られる。

更新を怠る。 プロジェクト構造が変わったのにCLAUDE.mdが昔のまま残っていると、Claudeが存在しないディレクトリを参照したり、すでに廃止された規約に従ってしまったりする。コードレビューのときにCLAUDE.mdも更新対象に含める習慣が必要だ。/doctorチェックアップを実行すると、コードベースから推測できる不要な記述（ディレクトリ構造の羅列など）を整理するよう提案してくれることもある。

機密情報をプロジェクトのCLAUDE.mdに書く。 内部サーバーのアドレスや個人のAPIキーのようにチーム全体に共有してはいけない情報は、gitでコミットされるプロジェクトのCLAUDE.mdではなく、.gitignoreに登録されたCLAUDE.local.mdに書くべきだ。

この4つさえ避ければ、CLAUDE.mdはもっと長く、もっと安定してその役割を果たしてくれる。

関連記事