CLAUDE.mdの書き方｜何を書くか・置き場所・育て方【テンプレートつき】

CLAUDE.mdとは、Claude Codeが毎回の作業の最初に読み込む、プロジェクトの説明書です。ビルドやテストのコマンド、コーディングの規約、ディレクトリの構成など、「毎回説明し直していること」を書いておくと、AIが最初からプロジェクトのルールに沿って作業できるようになります。

ただし、長く書けばよいわけではありません。公式ドキュメントでは、1ファイルあたり200行以内を目安にしています。この記事では、何を書き、何を書かないか、置き場所と読み込まれる順番、長くなったときの分け方、スキル・フック・設定との使い分けまで、公式ドキュメントに沿って解説します。記事の最後に、そのまま使えるテンプレートも紹介します。

CLAUDE.mdの早見表

CLAUDE.mdに書くこと

公式ドキュメントでは、次のようなときにCLAUDE.mdに追記するよう勧めています。

• Claudeが同じ間違いを2回したとき
• コードレビューで、このプロジェクトなら知っておくべきことを指摘されたとき
• 前回のセッションと同じ訂正を、また入力したとき
• 新しく参加したメンバーにも同じ説明が必要なとき

つまり、CLAUDE.mdは「毎回説明し直していること」を書き留める場所です。具体的には、次の5つが中心になります。

CLAUDE.mdに書かない方がいいこと

迷ったときは、「この1行がなかったら、Claudeは間違えるか」を考えます。答えが「いいえ」なら、その行は削除して構いません。

書き方のコツ：具体的に、確認できる形で

CLAUDE.mdは、強制される設定ではなく、Claudeが読んで従おうとする指示です。そのため、書き方で守られやすさが変わります。公式ドキュメントでは、確認できるくらい具体的に書くことを勧めています。

ほかにも、次の点を意識します。

• 見出しと箇条書きで整理する：長い文章より、まとまりごとに区切った方が読み取られやすい
• 矛盾する指示を書かない：2つのルールが食い違うと、どちらに従うかが定まらない
• 定期的に見直す：古くなった指示や、複数のファイルで食い違う指示を削除する

置き場所と読み込まれる順番

CLAUDE.mdは、置き場所によって適用される範囲が変わります。

読み込みのルールは次のとおりです。

• 作業ディレクトリと、その上の階層にある CLAUDE.md・CLAUDE.local.md は、起動時に読み込まれる
• 下の階層（サブディレクトリ）にある CLAUDE.md は、Claudeがそのディレクトリのファイルを読んだときに読み込まれる
• 見つかったファイルは、上書きではなく、すべてつなげて読み込まれる。作業ディレクトリに近いものほど後に読まれる

たとえば、フロントエンドとバックエンドが1つのリポジトリにある場合は、次のように分けられます。

my-app/
├── CLAUDE.md              # 全体の構成、共通のコマンド
├── frontend/
│   └── CLAUDE.md          # Reactの規約（frontendのファイルを読んだときに読み込まれる）
└── backend/
    └── CLAUDE.md          # APIとDBの規約（backendのファイルを読んだときに読み込まれる）

最初の作り方：/init から始める

Claude Codeで /init を実行すると、Claudeがコードを調べ、ビルドのコマンド、テストの方法、見つかった規約をもとにCLAUDE.mdのひな形を作ります。すでにCLAUDE.mdがある場合は、上書きせずに改善案を提案します。

ひな形ができたら、Claudeがコードから読み取れない情報を追記していきます。

• なぜその設計にしたのか（「在庫の計算は、必ず InventoryService を通す。直接DBを更新すると、履歴が残らないため」）
• 過去に起きた問題と、その対策
• チームの作業の進め方

長くなったときの分け方

@ で別のファイルを読み込む

@ファイルのパス と書くと、そのファイルの内容を読み込めます。

プロジェクトの概要は @README.md 、使えるコマンドは @package.json を参照。

# 追加の指示
- Gitの運用ルール @docs/git-instructions.md

• パスは、そのCLAUDE.mdがある場所から見た相対パスでも、絶対パスでも書ける
• 読み込まれたファイルが、さらに別のファイルを読み込むこともできる（最大4階層まで）
• @ で読み込んだファイルも起動時にすべて読み込まれるため、分けても量は減らない。整理のための機能と考える
• 読み込ませずにパスを書きたいときは、`@README` のようにバッククォートで囲む

.claude/rules/ でテーマごとに分ける

規約が増えてきたら、.claude/rules/ にテーマごとのファイルを置きます。

my-app/
└── .claude/
    ├── CLAUDE.md
    └── rules/
        ├── code-style.md    # コードの書き方
        ├── testing.md       # テストの規約
        └── security.md      # セキュリティの要件

さらに、ファイルの先頭に paths を書くと、対象のファイルを扱うときだけ読み込まれるようになります。

---
paths:
  - "src/api/**/*.ts"
---
# APIの開発ルール
- すべてのエンドポイントで入力値を検証する
- エラーは共通のエラー形式で返す
- OpenAPIのコメントを書く

paths がないルールは、CLAUDE.mdと同じく毎回読み込まれます。特定の領域だけに関係するルールは paths で絞ると、ほかの作業のときに余計な指示が混ざりません。

人向けのメモはHTMLコメントで

<!-- 2026年9月 決済APIの移行が終わったら、この項目を削除 --> のようなHTMLのコメントは、Claudeに渡される前に取り除かれます。保守する人向けのメモを残しても、AIの読み込む量は増えません。

スキル・フック・設定との使い分け

CLAUDE.mdだけですべてを管理しようとすると、長くなり、守られにくくなります。目的に応じて使い分けます。

CLAUDE.mdは「お願い」、フックと設定は「仕組み」と考えるとわかりやすくなります。「絶対に守らせたいこと」をCLAUDE.mdに書いて守られなかった、という場合は、フックや設定に移すのが確実です。

そのまま使えるテンプレート

# プロジェクト概要
- 社内の受発注を管理するWebアプリ（Next.js + NestJS + PostgreSQL）
- 詳細は @README.md

# コマンド
- 開発サーバー：`pnpm dev`
- 単体テスト：`pnpm test:unit`（変更したファイルに関係するテストだけでよい）
- E2Eテスト：`pnpm test:e2e`（コミット前に必ず実行）
- 型チェック：`pnpm typecheck`

# 構成
- `apps/web/` 画面（Next.js App Router）
- `apps/api/` API（NestJS）
- `packages/shared/` 画面とAPIで共有する型

# 規約
- exportはnamed exportを使う（default exportは使わない）
- 日付は `dayjs` で扱い、DBにはUTCで保存する
- 金額は整数（円）で扱い、浮動小数点を使わない

# 注意点
- 在庫の更新は必ず `InventoryService` を通す（直接更新すると履歴が残らない）
- `packages/shared/` の型を変えたら、webとapiの両方で型チェックを実行する
- 外部APIの呼び出しには必ずタイムアウトを指定する

# 作業の進め方
- ブランチ名：`feature/チケット番号-内容`
- コミットメッセージ：Conventional Commits（feat: / fix: など）
- 1つのプルリクエストは1つの目的に絞る

ポイントは、Claudeがコードを読むだけではわからないことに絞っている点です。このテンプレートでも50行程度で、200行の目安には十分な余裕があります。

指示が守られないときの確認方法

また、会話の中で伝えた指示は、長い会話を要約する /compact の後に失われることがあります。プロジェクトのルートにあるCLAUDE.mdは、/compact の後にも読み込み直されます。繰り返し使う指示は、会話ではなくCLAUDE.mdに書いておきます。

チームで育てる運用のコツ

• Gitで管理し、レビューを通す：CLAUDE.mdの変更も、コードと同じくプルリクエストで確認する
• 「2回目の訂正」を追記のきっかけにする：同じ指摘を2回したら、CLAUDE.mdに1行足す
• 定期的に削る：半年に一度など時期を決め、使われなくなった指示を削除する
• 個人の好みは分ける：チームのルールは CLAUDE.md、個人の好みは ~/.claude/CLAUDE.md や CLAUDE.local.md に書く
• 他のAIツールと共有する：リポジトリに AGENTS.md がある場合は、CLAUDE.mdから @AGENTS.md で読み込むと、同じ規約を複数のツールで使える

よくある質問

Q. CLAUDE.mdは英語で書くべきですか？ A. 日本語で問題ありません。チームのメンバーが読みやすい言語で書くことが大切です。コマンドやパスなどは、そのままの表記で書きます。

Q. 自動メモリー（auto memory）との違いは何ですか？ A. CLAUDE.mdは人が書く指示、自動メモリーはClaudeが作業の中で学んだことを自分で書き留めるメモです。チームで共有したいルールはCLAUDE.mdに書き、個人の作業の中での細かな好みは自動メモリーに任せる、という使い分けができます。

Q. 200行を超えるとどうなりますか？ A. 読み込み自体はされますが、読み込む量が増え、指示が守られにくくなります。.claude/rules/ への分割や、スキルへの移動を検討します。

Q. 秘密の情報を書いてもいいですか？ A. 書かないでください。プロジェクトのCLAUDE.mdはGitで共有されます。APIキーなどは環境変数で管理し、CLAUDE.mdには「.env.example を参照」のように書き方だけを示します。

まとめ

• CLAUDE.mdは、毎回説明し直していることを書き留める、プロジェクトの説明書
• 書くのはコマンド・規約・構成・固有の注意点・作業の進め方。コードからわかることは書かない
• 1ファイル200行以内を目安に、確認できるくらい具体的に書く
• 置き場所で範囲が変わる。チームは ./CLAUDE.md、個人は ~/.claude/CLAUDE.md や CLAUDE.local.md
• 長くなったら @ の読み込みや .claude/rules/（paths つき）で分ける
• 必ず実行させたいことはフック、禁止したいことは設定で管理する
• 守られないときは /context で読み込みを確認し、指示を具体的に書き直す

株式会社RJCでは、AIを使った開発の進め方を、実際のプロジェクトの中で仲間と工夫しながら磨いています。こうした知識を共有しながら、一緒に成長を楽しんでいます。

株式会社RJC ― SI事業・SES事業・AI駆動開発。未経験からエンジニアに育てるのが得意な会社です。