CoreCodeドキュメント

CoreCode を使いこなす

CLAUDE.md の書き方

最終更新：

CLAUDE.md は、Claude Code がセッションの開始時に毎回読み込むプロジェクトの説明書です。うまく書けば同じ間違いを繰り返さなくなり、長くて散らかっていると毎ターンのコンテキストを無駄にします。このページは Anthropic の公式ガイドに沿って、料金への影響も合わせて説明します。

要点
  • CLAUDE.md は強制される設定ではなくコンテキストです。Claude は考慮しますが、すべてのルールが守られる保証はありません。絶対に起きてはならないことは hook で止めてください。
  • 個人のルールは ~/.claude/CLAUDE.md、プロジェクトのルールは ./CLAUDE.md または ./.claude/CLAUDE.md、自分用のプロジェクト設定は ./CLAUDE.local.md に書き、これは .gitignore に入れます。
  • 具体的で確認できるルールを書き、1 ファイルは 200 行以内に収め、見出しと箇条書きで整理します。
  • コードベースの一部にだけ当てはまるルールは、paths で範囲を絞って .claude/rules/ に置きます。複数手順の作業はスキルとして書きます。
  • 毎ターン送信されます。セッション中に編集した内容は、/clear、/compact、または再起動の後に反映されます。

CLAUDE.md とは

このプロジェクトで Claude に知っておいてほしいことを書いた、ただの Markdown ファイルです。ビルドとテストの方法、コードの規約、構成、「必ず X する」といったルールなどを書きます。Claude Code はセッションの開始時に、これをコンテキストとして毎回読み込みます。

強制される設定ではありません。ルールが具体的で簡潔なほど、Claude は一貫して従います。保護されたディレクトリを編集させないなど、絶対に起きてはならないことには PreToolUse hook を使ってください。

Claude Code には自動メモリもあります。与えた修正は ~/.claude/projects/<project>/memory/ に保存されます。CLAUDE.md は自分で書くルール、自動メモリは Claude が学んだ内容を保持し、どちらも毎セッション読み込まれます。

置き場所

範囲場所用途
ユーザー~/.claude/CLAUDE.mdすべてのプロジェクトに共通の好み。返答の言語や使うツールなど
プロジェクト./CLAUDE.md または ./.claude/CLAUDE.mdチームのルール。ビルドコマンド、コード規約、アーキテクチャなど。コミットします
ローカル./CLAUDE.local.mdこのプロジェクトでの自分用の設定。ローカルのテスト URL など。.gitignore に追加します

起動時に Claude Code は、作業ディレクトリとその上位のすべてのディレクトリにある CLAUDE.md を読み、上から順に連結します。そのため、起動した場所に最も近いファイルが最後に読まれます。サブディレクトリの CLAUDE.md は、Claude がそのサブディレクトリのファイルを読み書きするときに、あとから読み込まれます。

まず何をするか

プロジェクトで /init を実行します。Claude がコードベースを分析し、見つけたビルドコマンド、テスト手順、規約を CLAUDE.md にまとめます。すでにある場合は上書きせず、改善案を提案します。そのあとで、Claude が自分では見つけられなかったことを書き足してください。

何を書くか

あとで何度も説明し直すことになる内容を書く場所だと考えてください。次のようなときに 1 行追加します。

毎セッション必要な事実だけにとどめます。複数手順の作業は、必要なときだけ読み込まれるスキルとして書き、コードベースの一部だけに関わるルールは .claude/rules に置きます。

効くルールの書き方

漠然とした願いではなく、確認できるルールを書きます。

こう書くかわりにこう書く
コードを適切に整形するインデントは 2 スペースにする
変更をテストするコミットする前に npm test を実行する
ファイルを整理しておくAPI ハンドラは src/api/handlers/ に置く

短い例です。

# Project

## Commands
- Install: pnpm install (not npm)
- Test: pnpm test, must pass before committing
- Run locally: pnpm dev, port 3000

## Conventions
- TypeScript strict mode, no any
- API handlers in src/api/handlers/, one route per file
- Schema changes only through prisma migrate

ほかのファイルを取り込む

@path でほかのファイルを取り込めます。たとえば See @README and @docs/git-instructions.md のように書きます。相対パスはそれを含む CLAUDE.md を基準に解決され、取り込みは 4 階層までネストできます。バッククォートで囲んだ `@README` は取り込まれません。

取り込みはファイルを整理する手段であって、コンテキストのコストは減りません。取り込んだ内容も毎回読み込まれます。プロジェクトがそのディレクトリの外にあるファイルを初めて取り込むとき、Claude Code は承認を求めます。

.claude/rules で範囲ごとに分ける

大きなプロジェクトでは、指示を .claude/rules/ の下にトピックごとのファイルとして分けます。testing.md や api-design.md などです。paths のないルールは CLAUDE.md と同じく起動時に読み込まれ、paths のあるルールは、Claude が該当するファイルを扱うときだけ読み込まれます。

---
paths:
  - "src/api/**/*.ts"
---
# API rules
- Validate every endpoint's input
- Return errors as ApiError

CLAUDE.md の中で複数手順の作業にふくらんだ部分は、使うときだけ読み込まれるスキルにできます。スキルのガイドを参照してください。

すでに AGENTS.md がある場合

Claude Code v2.1.277 以降では、Claude は AGENTS.md を直接読みます。CLAUDE.md がなければ AGENTS.md を読み、CLAUDE.md があればそちらだけを読みます。複数のコーディングツールで 1 つのファイルを共有するには、CLAUDE.md に @AGENTS.md の 1 行を追加してください。

コストとキャッシュ

ほかの節約方法はClaude Code の費用を抑えるにあります。

読み込まれたか確認する

FAQ

CLAUDE.md はどのくらいの長さにすべきですか？

Anthropic は 1 ファイル 200 行以内を推奨しています。コードベースの一部にだけ関わるルールは paths 付きで .claude/rules/ に、複数手順の作業はスキルに移してください。

Claude が CLAUDE.md に従わないのはなぜですか？

たいていは、ルールが曖昧、ファイルが長い、ルール同士が矛盾している、またはセッション中の編集がまだ反映されていない、のいずれかです。/context でファイルが読み込まれているか確認し、ルールを具体的で確認できる形にして、強制したいことには hook を使ってください。

CLAUDE.md を編集したのに反映されないのはなぜですか？

実行中のセッションは読み直しません。/clear、/compact を実行するか、Claude Code を再起動してください。

CLAUDE.md と AGENTS.md を併用できますか？

CLAUDE.md があるときは、デフォルトでは CLAUDE.md だけが読まれます。CLAUDE.md に @AGENTS.md を追加すると、1 つの指示を共有できます。