CLAUDE.mdの書き方｜Claude Codeが化ける7つのルールと実例テンプレート

Claude Codeに同じ指摘を毎回している気がする。「テストはpnpmで」「コミットメッセージは日本語で」と何度も打っていませんか。

その繰り返しを消すのがCLAUDE.mdです。一度書けば、以後すべてのセッションでClaude Codeが最初から守ってくれます。しかも書き方に少しコツを入れるだけで、出てくるコードの質が目に見えて変わります。

ただし、何でも書けばいいわけではありません。長すぎるCLAUDE.mdはむしろ精度を下げます。書くべき7項目と、書いてはいけないもの、そのまま使えるテンプレートまで順番に解説します。

この記事のポイント CLAUDE.mdとは、Claude Codeが毎セッション自動で読み込む指示書ファイルです。まず/initで自動生成し、「コマンド・規約・地雷」の3種を短く足すのが基本形。1行でも減らす意識で書くほど効きます。逆に、コードを読めばわかる情報を書くのは逆効果です。

CLAUDE.mdとは？何のためのファイルか

CLAUDE.mdとは、Claude Codeが起動時に自動で読み込む、プロジェクト専用の指示書ファイルです。中身はただのMarkdownファイルで、リポジトリの直下にCLAUDE.mdという名前で置くだけで機能します。

役割を一言で言えば「新しく入ったメンバーに渡す申し送り」。Claude Codeは毎回まっさらな状態で起動するので、プロジェクトの約束事を毎回口頭で伝えるか、CLAUDE.mdに書いておくかの二択になります。

チャットでの指示との違いは持続性です。

  • チャットでの指示: そのセッション限り。翌日にはゼロから
  • CLAUDE.mdの指示: 全セッション・チーム全員に毎回適用される

つまり「2回以上言ったことはCLAUDE.mdに書く」が運用の基本。Claude Code自体をまだ触っていない人は、先にClaude Codeの使い方ガイドでセットアップを済ませてから戻ってくると話が早いです。

ファイルの正体がわかったところで、どこに置くと何に効くのかを整理します。

置き場所は3種類。優先順位を理解する

CLAUDE.mdは複数の場所に置けて、それぞれ効く範囲が違います。

置き場所効く範囲書く内容
~/.claude/CLAUDE.md自分の全プロジェクト個人の好み(言語、口調、共通ルール)
リポジトリ直下そのプロジェクト全体ビルドコマンド、設計方針、規約
サブディレクトリその配下を触るときモジュール固有の注意点

要するに「個人 → プロジェクト → ディレクトリ」の入れ子構造。会社の規約はリポジトリ直下に、自分だけの好みは~/.claude/に書くと、チームで共有するリポジトリを汚さずに済みます。

なお、リポジトリ直下のCLAUDE.mdはGitにコミットして共有するのが定石です。チーム全員のClaude Codeが同じルールで動くようになり、レビュー指摘が目に見えて減ります。個人検証用に共有したくない指示はCLAUDE.local.mdという名前にすれば、自分のマシンだけで読み込まれます。

置き場所が決まったら、次は中身。ゼロから書く必要はありません。

何から書き始める？まず/initで自動生成

Claude Codeには/initというコマンドがあり、実行するとプロジェクトを解析してCLAUDE.mdの下書きを自動生成してくれます。ビルドコマンドやディレクトリ構成はこれでほぼ埋まるので、ゼロから手書きするのは時間の無駄です。CLAUDE.mdを含むメモリ機能の公式仕様はClaude Codeの公式ドキュメントにまとまっています。

ただし自動生成は「無難な下書き」止まり。効くCLAUDE.mdにするには、あなたしか知らない情報を足す必要があります。それが次の7項目です。

書くべき7項目。効くCLAUDE.mdの中身

数百のプロジェクトで使われている型を集約すると、書く価値がある情報は7種類に絞られます。

1. よく使うコマンド

ビルド、テスト、リント、デプロイ。AIが推測でnpm testを打って外すのを防ぎます。

## コマンド
- テスト: pnpm test (単体は pnpm test -- path/to/file)
- 型チェック: pnpm typecheck
- ビルド: pnpm build

2. コーディング規約のうち「機械チェックされないもの」

リンターが検出できる規約を書くのは無駄です。書くべきは、ツールが拾えない約束事だけ。

- エラーメッセージはユーザー向けは日本語、ログは英語
- 日付処理は必ず src/lib/date.ts を経由する(直接dayjsを触らない)

3. アーキテクチャの「なぜ」

コードを読めば「何をしているか」はAIにもわかります。わからないのは「なぜそうしたか」。

- DBアクセスはRepositoryクラス経由。過去にORM直叩きで N+1 が多発したため

4. 地雷リスト

そのプロジェクト特有のハマりどころ。これが一番効きます。

- config.ts の並び順は自動生成due。手で並べ替えるとCIが落ちる
- users テーブルへのmigrationは必ずDBAレビューを通す

5. テストと検証の手順

「変更したら何を実行して確認するか」を書くと、Claude Codeが自走して検証まで済ませてくれます。

6. 触ってはいけないファイル・操作

認証情報、自動生成ファイル、本番設定。禁止事項は明示しないと守られません。より強制力が必要なら、CLAUDE.mdでの注意書きよりもhooksで機械的にブロックする方法が確実です。

7. 外部ツールの接続情報

MCPサーバーや社内APIなど、プロジェクトが依存する外部ツールの使い方。接続の仕組み自体はMCPのセットアップガイドにまとめています。

7項目に共通するのは、「コードを読んでもわからないことだけを書く」という原則。これを外すと、次に説明する「太りすぎ問題」が始まります。

書いてはいけないもの。長いCLAUDE.mdは逆効果

CLAUDE.mdは長いほど親切に見えて、実際は逆です。指示書はAIが一度に読む文章(コンテキスト)の一部を毎回占有するので、無駄な行はそのぶん本題への集中力を削ります。指示が増えるほど1つあたりの遵守率も下がります。Anthropic公式のClaude Codeベストプラクティスでも、CLAUDE.mdは簡潔に保ち、繰り返し磨き込むことが推奨されています。

この「渡す情報を絞るほど精度が上がる」という原理はCLAUDE.mdに限らない話で、体系的にはコンテキストエンジニアリングの解説記事で扱っています。

削除の目安になる「書きがちな無駄」は4つ。

  • コードを読めばわかる情報: ディレクトリ一覧、関数の説明。AIは自分で読めます
  • 一般論: 「クリーンなコードを書く」「適切にエラー処理する」。何も変わりません
  • 滅多に使わない手順: 年1回のリリース手順は別ファイルにして、必要なときだけ参照させます
  • 古くなった情報: 移行済みの旧構成の説明など。嘘の指示書は無いより悪い

編集部の目安は「まず100行以内」。それを超えたら、セクションごとに別ファイルへ切り出して、CLAUDE.mdには要点と参照先だけを残すのがおすすめです。実際、優れたCLAUDE.mdほど短く、地雷リストの密度が高い傾向があります。

引き算の感覚がつかめたら、あとは日々の運用で育てるだけです。

CLAUDE.mdはどう育てる？運用の型

CLAUDE.mdは一度書いて終わりではなく、育てるファイルです。運用はシンプルで、Claude Codeに同じ指摘を2回したら、その場でCLAUDE.mdに1行足す。これだけです。

セッション中に#で始まるメッセージを送ると、Claude Codeがその内容をCLAUDE.mdに追記してくれるので、エディタを開き直す必要もありません。

もう1つの型は定期的な棚卸しです。月に1回、CLAUDE.mdを見直して「もう守られなくなった指示」「古くなった情報」を削ります。足す一方だと必ず太るので、追加と削除をセットにするのが長持ちのコツ。

ここまでの内容を1枚にまとめた、コピペ用のテンプレートを置いておきます。

# CLAUDE.md

## プロジェクト概要
(1〜2行。何のサービスで、何の技術スタックか)

## コマンド
- テスト:
- 型チェック:
- ビルド:

## 規約(機械チェックされないもの)
-

## 設計の「なぜ」
-

## 地雷リスト
-

## 禁止事項
-

空欄を埋めれば最低限の形になります。あとは運用しながら地雷リストを厚くしていってください。

AI PICKS編集部の判定

CLAUDE.mdまわりの論点を、率直に判定します。

  • 投資対効果: 圧倒的です。30分の整備で、以後の全セッションの精度が上がる。Claude Codeユーザーで書かない理由がありません
  • /init だけで放置: 正直もったいない。自動生成は土台であって、効くのは手で足した地雷リストのほうです
  • 長文CLAUDE.md: 微妙。読ませる量と精度はトレードオフなので、迷ったら削る一択
  • チーム開発: リポジトリにコミットして共有が正解。「AIへの指示書」は属人化させず、コードレビューの対象に含めるべきです

なお、CursorやGitHub Copilotにも同種の指示ファイル(ルールファイル)があり、考え方はそのまま流用できます。CursorやGitHub Copilotと併用しているチームは、内容を揃えておくと混乱がありません。ツール選び自体を迷っている段階なら、AIコーディングツールのカテゴリページから比較するのが早いです。

よくある質問

Q. CLAUDE.mdはどの言語で書くべきですか？

日本語で問題ありません。Claude Codeは日本語の指示を正確に解釈します。チームに英語話者がいる場合だけ英語に揃えれば十分です。

Q. CLAUDE.mdとREADME.mdの違いは何ですか？

読者が違います。READMEは人間の新規参加者向け、CLAUDE.mdはAI向けの申し送りです。内容の重複は多少あって構いませんが、READMEをそのままコピーするとAIには冗長すぎます。「コードから読み取れない約束事」だけを抜き出すのがCLAUDE.mdです。

Q. 指示を書いたのに守られないことがあります。なぜですか？

主因は指示の多さと曖昧さです。指示が増えるほど1つあたりの遵守率は下がるので、まず行数を減らしてください。また「適切に」「なるべく」のような曖昧語は効きません。「1ファイル300行を超えたら分割」のように、判定可能な形に書き直すと守られます。絶対に破られたくないルールは、CLAUDE.mdではなくhooksで機械的に強制します。

Q. サブディレクトリのCLAUDE.mdはいつ使いますか？

モノレポや大規模プロジェクトで、領域ごとにルールが違うときです。たとえばfrontend/とbackend/で規約が違うなら、それぞれの直下に置きます。小さなリポジトリなら直下の1枚で十分です。

Q. CLAUDE.mdを書けばAI社員のような自動運用もできますか？

CLAUDE.mdはその土台です。業務手順と判断基準をCLAUDE.mdに書き、定期実行と組み合わせると、決まった業務を毎日こなすAIが作れます。全体像はAI社員の作り方ガイドにまとめました。

CLAUDE.mdを整えたら、次はClaude Codeのサブエージェント設計へ。指示書で土台を固めた上で作業を並列化すると、開発速度がもう一段変わります。

各ツールの公式サイト（一次情報）

料金・機能・対応範囲は各社公式が一次情報です。本記事は公開時点の検証に基づきますが、最新かつ正確な条件は必ず各公式ページで確認してください。