CLAUDE.md完全ガイド:役割と書き方(テンプレート付き・2026年版)

Jasmine(Claude Codeを毎日使い、実プロジェクト向けにCLAUDE.mdを書いて調整している開発者)。

CLAUDE.mdとは?

Claude Codeがこのプロジェクトはnpmではなくpnpmを使うことを何度も「忘れる」、あるいは既存ファイルを編集せずに新しいファイルを作ってしまう——そんなことにイライラした経験があるなら、CLAUDE.mdこそがまさに足りていなかったものです。

CLAUDE.mdは、プロジェクトのルートに置くMarkdownファイルで、セッションが始まった瞬間にClaude Codeが自動でコンテキストへ読み込み、プロジェクト全体に効く永続的なシステム指示として機能します。つまり、新しいセッションを開くたびに「このプロジェクトはTypeScriptを使う、テストはコマンドXで実行する、ディレクトリYには触るな」と打ち直す代わりに、その規約を一度だけCLAUDE.mdに書いておくのです。エージェントは、すでにコードベースを把握しているチームメイトからのブリーフィングを読むように、それを読みます。

重要な区別:CLAUDE.mdは、毎回貼り付けるのを覚えておかなければならないプロンプトではありませんし、人間の読者向けのドキュメントでもありません。それはエージェントのためのコンテキストであり、短く、命令形で、Claudeが正しい判断を下すのに役立つことに絞って書かれます。具体的で的を射ているほど、エージェントはぶれなくなります。そもそもClaude Codeが何なのかまだよく分からない場合は、先にClaude Codeとは何かを読んでから、ここに戻ってきてください。

別の見方をすると、新しい開発者をオンボーディングするとき、毎朝すべてを説明し直したくはないはずです。オンボーディング用のページを1枚書き、相手はそれを読んで、あとは自分で動けるようになります。CLAUDE.mdはそのオンボーディングページ——ただしエージェント向けで、しかもすべてのセッションで自動的に読み直されます。だからこそこのファイルは投資する価値があります。一度きちんと書けば、その後に続く何百ものセッションを通じて効果が積み上がっていくからです。Anthropicのベストプラクティスガイドによれば、最初の一発で完璧に書こうとするより、CLAUDE.mdを時間をかけて少しずつ磨いていく(生きたプロンプトのように扱う)ほうが、明らかにうまくいきます。

CLAUDE.mdはどう動く?(なぜエージェントは従うのか)

仕組みは実にシンプルです。プロジェクトディレクトリ内でセッションを開くと、Claude CodeはCLAUDE.mdファイルを探し、あなたの最初のプロンプトより前にコンテキストの先頭へ読み込みます。複数の層が同時に読み込まれます。

• プロジェクトルート - ./CLAUDE.md。リポジトリ全体で共有する規約(プロジェクトに関わる全員に読み込まれる)。
• 個人用ファイル - ~/.claude/CLAUDE.md。すべてのプロジェクトに適用される、あなた自身の設定。
• 親/子ディレクトリ - Claude Codeはディレクトリツリーを上へたどり、作業中のサブディレクトリ内にあるCLAUDE.mdも読み込みます。そのため、特定のモジュールに固有の規約を、そのモジュールのすぐそばに置いておけます。

この内容はコンテキストの先頭に位置するため、初頭効果(primacy bias)の影響を受けます。モデルは早く現れたものほど強く「耳を傾ける」傾向があるのです。だからこそ、最も重要な制約(「してはいけない」境界)はファイルの先頭に置くべきで、長い段落の途中に埋もれさせてはいけません。

正直な注意点も一つ。CLAUDE.mdは強力なClaude Codeのコンテキストを作り出しますが、破れない絶対法則ではありません。コンテキストがいっぱいになったり、ファイルが長くなりすぎたりすると、信号が薄まり、エージェントが見落とすこともあります。エージェントが本当に読んだかを確かめる一番早い方法は、直接聞くことです。「CLAUDE.mdによると、テストを実行するコマンドは?」——正しく答えられれば、あなたのプロジェクトメモリはコンテキストに入っています。

CLAUDE.mdの3種類と置き場所

ファイルは一つだけだと思い込んでいる人が多いですが、実際にはスコープが3つあり、それぞれの置き場所を知っておけば、何もかも一つのファイルに詰め込まずに済みます。

CLAUDE.local.mdについては、プロジェクトごとの個人的なメモ用の、非公開で未コミットのファイルです——自分だけが必要なサンドボックスURLやローカルのテストデータを入れます。本稿執筆時点(2026-08-20)の公式ドキュメントによれば、このファイルは一部の古いガイドが主張するように非推奨になっているわけではなく、今も完全にサポートされています——CLAUDE.mdと並んで読み込まれ、同じように扱われます。あなたは.gitignoreに追加するだけです。同じプロジェクトの複数のワークツリーをまたいで作業し、それらの間で個人的なメモを共有したい場合、ドキュメントは各ワークツリーで内容を複製する代わりに、ホームディレクトリから@~/.claude/my-project-instructions.mdのようにインポートすることを勧めています——この構文はバージョンによって変わることがあるので、頼る前に再確認してください。「CLAUDE.mdはどこに置く?」への手短な答えが欲しいなら:チームの規約はリポジトリのルートに、個人設定はユーザーファイルに、未コミットのメモはCLAUDE.local.mdに、モジュール固有の例外はサブディレクトリに、です。

CLAUDE.mdには何を入れる?(6つのコアセクション)

これが最も重要な問いです——そして弱いファイルの多くは、間違ったものを詰め込むせいで失敗します。ROIの高い順に並べた、持っておく価値のある6セクションは次のとおりです。

1. コマンド(最もROIが高い)。テスト、ビルド、lint、開発サーバーの実行方法。エージェントが最も頻繁にコマンドを取り違えるので、ここが一番時間を節約できる場所です。例:pnpm test、pnpm build、pnpm lint。
2. 技術スタック+バージョン。言語、フレームワーク、パッケージマネージャー、DB。例:「Next.js 15(App Router)、TypeScript strict、pnpm、PostgreSQL + Prisma」。エージェントが古いAPIに手を伸ばすのを防ぎます。
3. ディレクトリ構成 - 1項目につき1行。例:「app/ ルート、components/ UI、lib/ 共有ヘルパー」。新しいファイルをどこに置くべきかをエージェントが分かる程度で十分です。
4. コード規約。命名、import順、エラー処理、テストのスタイル。間違えやすいところを明示し、スタイルガイド全体をコピーしないこと。
5. 「してはいけない(do NOT)」境界。これが最も大きな差を生むセクションで、先頭近くに置くべきです。例:「既存ファイルを編集できるのに新しいファイルを作らない」「頼まれない限りコミットしない」「すでに適用済みのmigrations/フォルダには触らない」。
6. 詳細ドキュメントへの@pathインポート。長い文書をそのまま貼り付ける代わりに、そこを指し示します:@docs/architecture.md。こうすればメインファイルを軽く保ちつつ、必要なときにエージェントが詳細へたどり着く道を残せます(段階的な開示)。人がよく間違える点をいくつか:相対パスはインポートしているファイルを基準に解決され、あなたのcwdではありません。インポートのネストは4階層までで、それより深いものは無視されます。パスをインポートさせずに文字どおり書きたいときは、バッククォートで囲みます。例:`@README`。

取捨選択のルール:ある行がエージェントに異なる判断をさせるのに役立たないなら、削りましょう。CLAUDE.mdはREADMEではありません。READMEはプロジェクトを人間の読者に説明するもの、CLAUDE.mdはエージェントにどう振る舞うかを伝えるもの。目的が2つ異なるので、混ぜてはいけません。混ぜると、エージェントが何をするか決めるときに実際には使わない内容でファイルが膨れ上がります。

標準的なCLAUDE.mdテンプレート(コピペ)

以下は、典型的なNext.js + TypeScriptプロジェクト向けの完成した、動くテンプレートです。これこそ多くのガイドが省いているもの、つまりそのまま貼ってすぐ使え、あとは自分のプロジェクトに合わせて削っていけるファイルです。

このテンプレートをコピーして、自分のプロジェクトに合わせて調整してください:技術スタック、コマンド、ディレクトリ構成を自分のものに置き換えましょう。「してはいけない」セクションは先頭のままにしておくこと。

# CLAUDE.md

Web app for managing clinic appointment scheduling. Priority: correct business logic > coding speed.

## Do NOT (read first)
- Do NOT create a new file if you can edit an existing one.
- Do NOT commit/push unless explicitly asked.
- Do NOT edit files in `prisma/migrations/` that already ran - create a new migration.
- Do NOT use `any` in TypeScript. Do NOT disable lint to get past errors.

## Tech stack
- Next.js 15 (App Router) + TypeScript (strict)
- pnpm (do NOT use npm/yarn)
- PostgreSQL + Prisma
- Tailwind CSS + shadcn/ui
- Vitest (unit) + Playwright (e2e)

## Commands
- Dev: `pnpm dev`
- Test: `pnpm test` # single file: `pnpm test path/to/file`
- Build: `pnpm build`
- Lint: `pnpm lint`
- DB: `pnpm prisma migrate dev`

## Directory structure
- `app/` - routes (App Router)
- `components/` - reusable UI
- `lib/` - shared helpers, no JSX
- `server/` - server-side logic, DB queries
- `prisma/` - schema + migrations

## Code conventions
- Components: PascalCase; functions/variables: camelCase; constants: UPPER_SNAKE.
- Prefer named exports; absolute imports via the `@/` alias.
- Error handling: throw `AppError` (see `lib/errors.ts`), never swallow errors silently.
- Every new feature ships with a test.

## Workflow
- Before calling anything done: run `pnpm lint` and `pnpm test`, fix all errors.
- Large changes: describe a short plan before editing many files.

## Detailed docs (import when needed)
@docs/architecture.md
@docs/api-conventions.md

やること・やらないこと——誤り → 正しい例

エージェントが従うファイルと無視するファイルの違いは、たいてい長さではなく言い回しにあります。実際のビフォー/アフターをいくつか。

黄金律:プロジェクトについてまだ何も知らない、優秀な新人開発者に説明するつもりで書くこと——具体的に、命令形で、短く。曖昧な行(「きれいなコードを書く」「ベストプラクティスに従う」)はどれもほぼ役に立ちません。エージェントには測りようがないからです。「きれいなコードを書く」を「関数は最大40行、超えたら分割」に、「エラーを丁寧に扱う」を「AppErrorをthrowする、空のtry/catchは禁止」に置き換えましょう。測れるものこそ、エージェントが従えるものです。ファイルで参照したいClaude Codeのコマンド一式を見るには、Claude Codeコマンドチートシートを確認してください。

CLAUDE.mdは無駄なく、トークン効率よく保つ

よくある誤解:ファイルが長いほど、エージェントはプロジェクトを「理解する」というものです。実際は逆です。CLAUDE.mdはすべてのセッションのコンテキストウィンドウを消費し、膨らむほど、重要な1行が何十ものノイズに埋もれていきます——信号は薄まり、あなたが最も必要としたまさにその点を、エージェントは見落としやすくなります。これは単なる直感ではありません。その根拠については、AGENTS.md/CLAUDE.mdのコンテキストファイルが本当に機能するのかを参照してください。

実務上の経験則:目安はおよそ200行、大規模プロジェクトでも上限はだいたい300〜500行です。そこを大きく超えるなら、切り出すべきサインです。CLAUDE.mdを最適に保つ方法:

• インポートによる段階的な開示。メインファイルは「判断のための目次」として保ち、長い詳細(アーキテクチャ、API規約)は別ファイルに追い出して@docs/...で指し示します。
• 振る舞いを変えないものは削る。プロジェクトの経緯、宣伝文句、くどい説明——すべて落としましょう。
• 重複をまとめる。技術スタックですでに「pnpmを使う」と言ったなら、ほかの3か所で繰り返す必要はありません。
• ROIで優先順位を付ける。コマンドと境界は先頭に、「知っておくと良い」程度の内容は末尾か、インポートへ移します。

.claude/rules/でパスごとにルールを分割する

プロジェクトが大きくなると、あらゆる規約を一つのどんどん長くなるCLAUDE.mdに詰め込むやり方は行き詰まります。代わりにClaude Codeでは、指示を.claude/rules/配下のいくつかの小さなファイルに分割でき、それぞれが一領域を担います。

.claude/rules/
├── code-style.md
├── testing.md
└── security.md

各ルールファイルはYAMLフロントマターを付けて、paths:フィールドで読み込まれる条件を絞れます。

---
paths:
  - "src/api/**/*.ts"
---
Validate all input with Zod before writing to the DB.

paths:のないルール(スコープなし)は、./CLAUDE.mdと同じ優先度で毎セッション読み込まれます。paths:付きのルールは、Claudeがそのグロブに一致するファイルを開いたときにだけ読み込まれます——これこそコンテキストを節約する理由です。CSSを編集している間、APIルートの規約にトークンを払わずに済むのです。~/.claude/rules/は個人用で、あなたのすべてのプロジェクトに適用され、プロジェクトレベルのルールより先に読み込まれます。

これはより広いトークン管理戦略につながります——.claude/rules/がより大きなトークン予算の全体像のどこに位置するかは、Claude Codeにおけるコンテキストとメモリの管理を参照してください。

手早いコツ:/initと#キー

CLAUDE.mdをゼロから書く必要はありません。2つの組み込みツールが、作業をずっと速くしてくれます。

• /init - このコマンドをプロジェクトで実行すると、Claude Codeがリポジトリをスキャンして、あなたのために出発点となるCLAUDE.mdを生成します(技術スタック、コマンド、構成を推測して)。そのまま鵜呑みにせず、下書きとして扱い、上記の6つのコアセクションまで削り込みましょう。
• #キー - 作業中に#に続けてメモを打つと、Claude CodeがそれをCLAUDE.mdに保存するか提案します(プロジェクトファイルかユーザーファイルを選べます)。これは、記録する価値のある規約に気づいた瞬間に、セッションの途中でプロジェクトメモリを追加する方法です——エディタを開くために手を止める必要はありません。

始めたばかりなら、いちばん無駄のない流れはこうです:/initを実行 → 上記のテンプレートまでファイルを削る → #キーで時間をかけて育てる。Claude Codeを始めるための10ステップが、この一連の流れを解説しています。

キットに用意されたCLAUDE.md標準(AgentKit)

良いCLAUDE.mdを自分で書くには、何度か試行錯誤が必要です。近道が欲しいなら、AgentKitバンドル(標準のCLAUDE.md規約付き)のような一部のキットは、CLAUDE.mdの規約をルールやスキルと一緒に一貫した標準としてまとめてくれるので、白紙から始めずに済みます。自分のプロジェクトのコマンドや境界を宣言する作業を肩代わりするものではありませんが、足場作りや、プロジェクト間で繰り返される規約は省けます——AgentKitを試して(リンク経由で20%オフ)、サンプル構成を見て、自分に合う部分だけ取り入れてください。

よくある質問(FAQ)

CLAUDE.mdというファイル名は大文字・小文字を区別しますか?

はい。名前の部分をすべて大文字にして、正確にCLAUDE.mdと付けてください。大文字・小文字を区別するシステム(Linux。CIでよくあります)では、claude.mdのような誤った名前だと、Claude Codeがファイルを認識できないことがあります。

CLAUDE.mdはgitにコミットすべきですか?

プロジェクトルートのファイルは、はい——共有の規約なので、コミットすればチーム全員が同じコンテキストで作業できます。一方、~/.claude/CLAUDE.mdは個人用で、リポジトリには入れません。プロジェクトごとの個人的なメモは、コミットではなく、ユーザーファイルかインポートに置くべきです。

ClaudeがCLAUDE.mdに従わないときは?

たいていは3つの原因のどれかです:ファイルが長すぎて信号が薄まっている、重要なルールが途中に埋もれている、あるいはコンテキストがすでにいっぱい。対処法:ファイルを短くする、「してはいけない」制約を先頭に移す、そして特定のルールについてエージェントに尋ねて正しく答えるか確かめる。

CLAUDE.mdはCursorや他のツールでも使えますか?

CLAUDE.mdはClaude Codeの規約です。他のツールは独自のコンテキストファイル(たとえばAGENTS.mdや、そのツールのルールファイル)を使います。書いた内容は再利用できることが多いですが、ファイル名や読み込みの仕組みはツールごとに異なります。

CLAUDE.mdはどのくらいの長さにすべき?

目安はおよそ200行、大規模プロジェクトでは上限300〜500行です。行数より信号の質を優先しましょう:エージェントの判断を変えるものだけを残し、あとはインポートするファイルへ追い出します。

プロジェクトファイルは~/.claude/CLAUDE.mdとどう違う?

プロジェクトファイル(./CLAUDE.md)はリポジトリとチーム全体に適用される規約を持ち、gitにコミットします。ユーザーファイル(~/.claude/CLAUDE.md)はあなたの個人設定を持ち、すべてのプロジェクトに適用され、リポジトリの外にとどまります。両方が存在する場合、Claude Codeは両方を同時に読み込みます。

まとめと次のステップ

CLAUDE.mdは、Claude Codeでできる最も小さく、最もリターンの高い投資です:一度書けば、エージェントは毎セッションであなたの規約に従います。上記のテンプレートをコピーし、自分のプロジェクトに合わせて削り、「してはいけない」制約を先頭に置き、ファイルを無駄なく保ちましょう。始めたばかりなら初心者向けの10ステップを読んでください。手早いコマンド参照が欲しいなら、Claude Codeコマンドチートシートをキーボードのそばに置いておきましょう。