Claude Codeって使うたびに毎回同じこと説明してるんですけど…なんとかなりませんか？
それ、CLAUDE.mdを書くだけで解決するよ。1回設定すれば、毎セッション自動で読み込んでくれるんだ
こんにちは！Renです！
Claude Codeを使っていて、「毎回同じプロジェクトの説明をするのが面倒」と感じたことはありませんか？
実は、たった1つのファイルを置くだけで、その問題は解決します。
それがCLAUDE.mdです。
今回は、CLAUDE.mdの書き方を公式ドキュメントの情報に基づいて完全解説します。何を書くべきか、どう育てるか、Skills・カスタムコマンドとの違いまで、この記事を読めばCLAUDE.mdを使いこなせるようになります。
Claude Codeの基本操作がまだ不安な方は、先にClaude Codeの使い方をゼロから解説｜動かしながら覚える最短ルートを読んでおくとスムーズです。
CLAUDE.mdとは？Claude Codeを「自分専用」にする設定ファイル
CLAUDE.mdを一言で説明すると、「Claude Codeに毎回自動で渡される引き継ぎメモ」です。
プロジェクトのルートディレクトリにCLAUDE.mdというMarkdownファイルを置くだけ。Claude Codeはセッション開始時にこのファイルを自動で読み込み、システムプロンプトの一部として扱います。
つまり、新しいメンバーに毎朝渡す「プロジェクトの基本ルール」みたいなもの？
まさにそう。しかもClaude Codeは毎セッション記憶がリセットされるから、CLAUDE.mdがないと毎回ゼロからの説明になる。逆に言えば、これさえ書いておけば説明不要になるんだ
・プロジェクトルートに置くだけで毎セッション自動読み込み
・Markdown形式だから誰でも書ける
・Gitで管理できるからチーム全員で共有可能
ファイル名は大文字のCLAUDE.mdです。claude.mdやClaude.mdではありません。大文字・小文字を間違えるとClaude Codeが認識しないので注意してください。
CLAUDE.mdに何を書くべき？5つの必須セクション
「何を書けばいいか分からない」。
これがCLAUDE.md最大のハードルです。
公式ドキュメントとベストプラクティスをもとに、書くべき5つのセクションを整理しました。
| ① | プロジェクト概要 技術スタック、ディレクトリ構成、主要ライブラリを1-2行で伝える |
| ② | よく使うコマンド ビルド、テスト、リント、デプロイのコマンドを正確に記載する |
| ③ | コーディング規約 リンターでは拾えない、プロジェクト固有のルールだけを書く |
| ④ | ワークフロー 計画→確認→実装→テストなど、Claudeに守らせたい作業手順を定義する |
| ⑤ | ドメイン知識・注意点 業界用語、ビジネスルール、触ってはいけないファイルなどを記載する |
順番に見ていきましょう。
① プロジェクト概要（Claudeに地図を渡す）
公式ドキュメントでは「Give Claude a map（Claudeに地図を渡せ）」と表現されています。
プロジェクトが何で、どういう技術で作られていて、ディレクトリ構成がどうなっているか。これを最初に伝えるだけで、Claudeの理解度が劇的に変わります。
# プロジェクト概要ユーザー認証用のFastAPI REST API。SQLAlchemy + Pydanticを使用。## ディレクトリ構成- app/models/ - データベースモデル- app/api/ - ルートハンドラー- app/core/ - 設定とユーティリティ
② よく使うコマンド
ビルドやテストのコマンドを書いておくと、Claudeがコマンドをハルシネーション（でっち上げ）しなくなります。
特にフレームワーク固有の引数やフラグがある場合は必須です。書いていないと、Claudeは存在しないフラグを勝手につけてコマンドを実行しようとします。
③ コーディング規約
ここで重要な注意点があります。
コードスタイルをCLAUDE.mdに書きすぎないこと。リンターに任せるべきことはリンターに任せましょう。LLMはリンターより高コストで低精度です。CLAUDE.mdに書くべきは、リンターでは拾えないプロジェクト固有の規約だけです。
たとえば「インデントは2スペース」はESLintに任せればいい話です。CLAUDE.mdに書くべきは、「新しいAPIエンドポイントを追加するときは必ず/api/v2/プレフィックスをつける」のような、コードの静的解析では検出できないルールです。
④ ワークフロー（考えてから動かす）
これ、意外と大事です。
ワークフローを定義しないと、Claudeはいきなりコードを書き始めます。そして、後から「あ、やっぱりこの設計じゃダメだった」と手戻りが発生します。
具体的にどう書けばいいんですか？
シンプルでいいんだ。「コード変更する前に、まず実装計画を立てて確認してね」っていう手順を書いておくだけで、Claudeの暴走がかなり減るよ
## ワークフロー1. コードを書く前に、まず実装計画を立てる2. 計画をユーザーに確認してもらう3. 変更を実装する4. テストを実行して検証する5. 分かりやすいコミットメッセージでコミットする
⑤ ドメイン知識・プロジェクト固有の注意点
業界用語やプロジェクト固有のルールは、Claudeには推測できません。
たとえば「Wrapsはユーザー向け年間まとめ動画のこと」「migrationsフォルダは直接触らない」のような情報です。これを書いておくだけで、Claudeがコードベースを正しくナビゲートできるようになります。
Claude Codeでの開発で「理解できていないまま進んでしまう」問題については、非エンジニアがClaude Codeを使うとなぜブラックボックス化するのかで詳しく解説しています。CLAUDE.mdで事前にルールを渡しておくことは、この問題の対策にもなります。
CLAUDE.mdを最速で作る方法：/initコマンド
「5つもセクション書くの大変そう…」って思いますよね。
安心してください。ゼロから書く必要はありません。
全部手書きじゃないんですか？
/initコマンドを実行するだけで、Claudeがプロジェクトを解析して自動生成してくれる。そこから不要な部分を削っていく方がずっと楽だよ
Claude Codeのセッションで/initを実行すると、Claudeがpackage.jsonや設定ファイル、コード構造を読み取って、CLAUDE.mdのたたき台を自動生成します。
・自動生成された内容の正確性を確認する
・ブランチ命名規則やデプロイ手順など、Claudeが推測できないプロジェクト固有のルールを追記する
・「これはTypeScriptプロジェクトです」のような当たり前の情報は削除する（package.jsonを見れば分かるので）
ポイントは「削ること」です。自動生成されたファイルはどうしても情報が多くなりがちですが、CLAUDE.mdの内容はすべてコンテキストウィンドウを消費します。不要な行があると、本当に大事な指示が埋もれてしまいます。
会話中に#キーを押すと、CLAUDE.mdに直接メモを追加できます。「あ、この規約も書いておくべきだな」と気づいたら、その場で記録する習慣をつけると、自然にCLAUDE.mdが育っていきます。
CLAUDE.mdの配置場所と優先順位
CLAUDE.mdは1箇所だけに置くものではありません。
実は複数の場所に配置でき、それぞれスコープ（適用範囲）が異なります。
| 配置場所 | スコープ | 読み込みタイミング | 用途 |
|---|---|---|---|
| ~/.claude/CLAUDE.md | 全プロジェクト共通 | 毎セッション自動 | 個人の好み・共通ルール |
| プロジェクトルート/CLAUDE.md | プロジェクト全体 | 毎セッション自動 | チーム共有の規約・構成 |
| CLAUDE.local.md | プロジェクト（個人用） | 毎セッション自動 | 個人メモ（自動gitignore） |
| サブディレクトリ/CLAUDE.md | そのディレクトリ内 | オンデマンド | モジュール固有の指示 |
CLAUDE.local.mdって何が違うんですか？
自動で.gitignoreに追加されるんだ。つまりチームには共有されない個人用のメモ帳。デバッグ用のTipsとか、自分だけの好みを書いておくのに便利だよ
優先順位は「より具体的な場所が勝つ」というルールです。サブディレクトリのCLAUDE.mdがプロジェクトルートのCLAUDE.mdより優先されます。
Auto Memory（MEMORY.md）との違い
Claude Codeにはもう一つ、Auto Memoryという仕組みがあります。これはCLAUDE.mdとは全く別物です。
| 項目 | CLAUDE.md | Auto Memory（MEMORY.md） |
|---|---|---|
| 誰が書くか | 人間が書く | Claude自身が書く |
| 中身 | 指示・ルール・規約 | 学習メモ・発見・パターン |
| 読み込み量 | 毎セッション全文 | 先頭200行のみ |
| 保存場所 | プロジェクト内 | ~/.claude/projects/配下 |
CLAUDE.mdは「あなたがClaudeに伝えたいこと」、Auto Memoryは「Claudeが自分で覚えたこと」です。両方を使い分けることで、セッションを重ねるごとにClaudeの理解が深まっていきます。
CLAUDE.mdとSkills・カスタムコマンド、何が違う？
Claude Codeには設定の仕組みが3つあります。
CLAUDE.md、Skills、カスタムコマンド。「全部似てない？」って思いますよね。
正直、どれに何を書けばいいか全然分かりません…
たとえで考えるとシンプルだよ。CLAUDE.mdは「社員ハンドブック」、Skillsは「専門書の棚」、カスタムコマンドは「レシピカード」。使われるタイミングが全然違うんだ
| 項目 | CLAUDE.md | Skills | カスタムコマンド |
|---|---|---|---|
| 読み込み | 毎セッション自動 | 必要時にオンデマンド | ユーザーが明示的に起動 |
| 書く内容 | プロジェクト規約・構成 | 特定タスクの専門知識 | 実行手順・ワークフロー |
| 配置場所 | プロジェクトルート | .claude/skills/ | .claude/commands/ |
| たとえ | 社員ハンドブック | 専門書の棚 | レシピカード |
・常に知っておくべきこと → CLAUDE.md（コーディング規約、ディレクトリ構成）
・特定の作業をするときだけ必要な知識 → Skills（ドキュメント生成、デザインレビュー）
・「このコマンドで実行して」と指示したいこと → カスタムコマンド（/review、/deploy）
Skillsの作り方はClaude Skillsの作り方｜初心者でも10分で自分専用AIアシスタントが作れるで、カスタムコマンドの作り方はClaude Codeカスタムコマンド完全ガイド｜定型タスクをワンコマンド化する手順と使い方でそれぞれ詳しく解説しています。
効果を最大化する3つのコツ
コツ①：短く・具体的に書く
これが最も大事なルールです。
CLAUDE.mdの内容はすべてコンテキストウィンドウを消費します。書けば書くほどClaude Codeが使える「作業スペース」が減るということです。
さらに、指示の数が増えると、遵守率が均一に下がるという構造的な問題があります。つまり新しい指示を追加すると、古い指示も含めてすべての指示が無視されやすくなるということです。
❌ 悪い例:「コードをきれいに書いてください」
✅ 良い例:「関数名はcamelCase、定数はUPPER_SNAKE_CASE」
「IMPORTANT」や「MUST」を乱用しないこと。全部が重要だと、何も重要じゃなくなります。本当に絶対守ってほしいルールだけに使いましょう。
コツ②：/clearでコンテキストをリセットする
タスクが変わったら、/clearコマンドで会話をリセットしましょう。
CLAUDE.mdの内容はリセットされずに残ったまま、前のタスクのゴミだけがきれいに消えます。デバッグ作業を終えて新機能開発に移るとき、認証周りのファイル内容がコンテキストに残っていると集中力が落ちます。
/compact focus on the API changesのように焦点を指定してコンテキストを圧縮できます。完全リセットの/clearと使い分けましょう。
コツ③：定期的に見直す
プロジェクトは進化します。CLAUDE.mdも一緒に進化させる必要があります。
おすすめは、コードレビューでルール違反を見つけたらすぐCLAUDE.mdに追記する習慣をつけること。あとは月1回くらいで棚卸しして、古くなった情報を消すといいよ
Claudeに直接「CLAUDE.mdを見直して改善点を提案して」とお願いすることもできます。重複している記述や矛盾しているルールを見つけてくれるので、メンテナンスが楽になります。
用途別CLAUDE.mdテンプレート
最後に、すぐ使えるテンプレートを2つ用意しました。コピペして、自分のプロジェクトに合わせてカスタマイズしてください。
テンプレート①：Webアプリ開発用
# プロジェクト概要Next.js 14のECサイト。Stripe決済とPostgreSQLを使用。# ディレクトリ構成- src/app/ - App Routerのページとレイアウト- src/components/ - 再利用可能なReactコンポーネント- src/lib/ - ユーティリティとDBクライアント- prisma/ - データベーススキーマとマイグレーション# コマンド- 開発サーバー: npm run dev- テスト: npm test -- --watch- 単体テスト: npm test -- path/to/file.test.ts- DBマイグレーション: npx prisma migrate dev# コーディング規約- TypeScript strictモード、anyは禁止- APIルートは { data, error } 形式で返す- 新しいエンドポイントには必ず結合テストを書く# ワークフロー1. コードを書く前に実装方針を立てる2. 変更を実装する3. テストを実行する4. Conventional Commit形式でコミットする# 注意点- prisma/migrations/ は絶対に直接編集しない- StripeのWebhookハンドラーは必ず署名検証を行う
テンプレート②：個人ブログ/コンテンツ制作用
# プロジェクト概要Cocoonテーマを使ったWordPressブログ。AIツールと副業がテーマ。# ディレクトリ構成- content/drafts/ - Markdownの下書き- content/published/ - 公開済み記事の記録- assets/images/ - ブログ用画像（アップロード前に圧縮すること）# 執筆ルール- トーン: 親しみやすく、実践的、です・ます調- 文字数: 1記事あたり3,000〜5,000文字- 必ず実体験を入れる。理論だけの記事にしない# ワークフロー1. まず記事の構成案を作成する2. 構成案の承認を得る3. HTML装飾付きで本文を執筆する4. SEOチェック（メタディスクリプション約120文字）# 注意点- 画像URLは /wp-content/uploads/YYYY/MM/ 形式- 内部リンクは必ず記事タイトルをフルで記載する
テンプレートはあくまで出発点。使いながら自分のプロジェクトに合わせて育てていくのが大事だよ
まとめ
CLAUDE.mdは、Claude Codeの出力品質を根本から変えるプロジェクト設定ファイルです。
思ったよりシンプルですね！/initで作って、削って、育てる
そう！完璧を目指して最初から書き込む必要はない。まずは/initで始めて、使いながら育てるのが一番の近道だよ
・毎回の説明が不要になり作業開始が一瞬に
・コーディング規約を守った一貫性のある出力に
・ワークフロー定義で手戻りが減る
・チーム全員が同じ品質でClaude Codeを使える
Claude Codeをもっと使いこなしたい方は、Claude Codeカスタムコマンド完全ガイド｜定型タスクをワンコマンド化する手順と使い方もぜひチェックしてみてください。CLAUDE.mdとカスタムコマンドを組み合わせると、開発効率がさらに上がります。
ではまた！
コメント