CLAUDE.mdの書き方 — Claude Codeで守られる10のパターン

要点

CLAUDE.mdの書き方の基本は3つです。守れたか確かめられる具体的な指示にする、1ファイル200行未満に収める、見出しと箇条書きで区切る。保守者向けのメモは <!-- --> で書けばコンテキストに入りません。

Claude Codeが起動時に読み込む CLAUDE.md は、セッションをまたいで残る指示書です。毎回のセッションは新しいコンテキストウィンドウで始まるため、同じ注意を毎回打ち直す代わりにここへ書いておきます。ただしClaudeはこれを「強制される設定」ではなく文脈として扱います。

CLAUDE.md が果たす役割の前提や、settings.json などほかの設定との位置関係はClaude Code完全ガイド・Claude Code設定の全体像に独立した記事があります。本稿はその上に乗る「中身の書き方」を10パターンに絞った内容です。空ファイルの状態から/initを実行すればコードベースを分析した初期版を自動生成でき、環境変数CLAUDE_CODE_NEW_INIT=1を立てるとSkillsやHooksまで対話式に選べる複数フェーズの初期化に変わります。挙動の詳細はClaude Code initコマンドの挙動にまとめました。Astroのような新規プロジェクトで/initを使う具体例はClaude CodeでAstroブログを作るで扱っています。

CLAUDE.mdをコメントアウトするには

CLAUDE.mdに書いた <!-- メモ --> のブロックレベルHTMLコメントは、Claudeのコンテキストに注入される前に取り除かれます。人間の保守者向けの注記を、トークンを使わずに残せます。コードブロックの中のコメントは取り除かれず、そのまま読まれます。Readツールでファイルを直接開いたときは、コメントも見えます。

指示そのものを一時的に無効にしたいときも、行を <!-- --> で囲めば読まれなくなります。

CLAUDE.mdで決まることと、決まらないこと

Claude Codeは起動時に、カレントディレクトリとその上位ディレクトリの CLAUDE.md をすべて連結して読み込みます。上書き関係ではなく連結で、ファイルシステムのルート側から作業ディレクトリに向かう順に並びます。作業ディレクトリより下にある CLAUDE.md は、Claudeがそのディレクトリのファイルを読んだ時点で追加されます。

置き場所は4種類あります。

書いた内容の効き方には限界があります。

以下の10パターンは、前者の「文脈として効かせる」側を強くするための書き方です。

パターン1: ペルソナ / 役割の固定

Claudeに "誰として振る舞うか" を最初に宣言するパターン。漠然と書くと効果が薄いので、プロジェクトの特殊事情を含めるのがコツです。

## 役割
 
あなたはこの Next.js 16 プロジェクトの開発パートナーです。以下の前提で動作してください:
 
- コード規約は既存ファイルに従う(新しい流儀を勝手に持ち込まない)
- Next.js 16 は App Router + Server Components 主体。`pages/` は使わない
- 返答は日本語の敬体。技術用語は英語のままでよい

ポイント: 役割名だけでなく、「pages/ は使わない」のように後から検証できる前提を並べます。「優秀な〜」のような形容は、守れたかどうかを確かめられないので足しません。

パターン2: タスク型別のガイドライン

"実装・レビュー・調査・質問応答" でモードを切り替えたい場合、タスク型ごとに指示を書くパターン。

## タスクタイプ別の振る舞い
 
### 実装タスク
- まず該当ファイルを読み、既存パターンを把握してから変更する
- テストがあれば同時に更新する
- 1コミット 1目的。混ざりそうなら分割する
 
### レビュー・調査タスク
- コードを変更しない
- 質問がある場合は変更前に確認
- `Agent` サブエージェントを優先的に使って context を汚さない
 
### 質問応答
- コードの引用は `path/to/file.ts:12` 形式で
- 不明点は "わからない" と明言

ポイント: モードごとに分けて書いておくと、何を守るべきかを後から確かめやすくなります。

パターン3: 禁則事項の明文化

"やってほしくないこと" をリスト化するパターン。やってほしくない行為を先に書いておく型です。

## 禁則事項
 
1. **勝手にコメントを書かない**: 既存の非コメントコードを保ちつつ、意味不明な WHY のない説明コメントを足さない
2. **デッドコードを残さない**: 置換した古いコードをコメントアウトで残さない
3. **暗黙の仕様変更を避ける**: リファクタの際に関数シグネチャを変えない(破壊的変更は必ず宣言)
4. **パッケージを勝手に追加しない**: package.json への追加は必ず相談
5. **環境変数の新規追加前に `.env.example` を更新**

ポイント: 公式の例にあるとおり、「ファイルを整理して」のような曖昧な指示より「APIハンドラは src/api/handlers/ に置く」のように確かめられる形が守られやすくなります。禁則も「勝手に追加しない」ではなく、何を相談するかまで書きます。

パターン4: テスト・ビルドの走らせ方

テストをいつ走らせるかは、書いておくと守れたかを確かめやすくなります。公式の例にも「コミット前に npm test を実行する」があります。

## テスト・ビルド
 
### テスト
- ユニットテスト: `npm run test`
- 型チェック: `npm run typecheck`
- 機能追加・バグ修正時は **必ず該当テストを追加 or 修正してから変更**
 
### ビルド
- 変更後 `npm run build` を走らせて SSG が通ることを確認
- エラーが出たら原因特定後に再ビルド

ポイント: どのコマンドを・どのタイミングで走らせるかを書いておくと、守れたかどうかを検証できます。具体的な動詞で書きます。

パターン5: コミット規約

短く書きやすいパターンです。

## Git コミット
 
- プレフィックスルール: `add: / update: / fix: / remove: / refactor: / clean: / docs: / chore: / test: / perf:`
- 1コミット1目的
- Co-Authored-By 等の Claude 署名は付けない
- サブジェクトは日本語 50字以内

ポイント: プレフィックスは形式が決まっているので書きやすい項目です。「本文(2行目以降)は長い説明のみ」等を明記すると、さらに揃います。

パターン6: ファイル配置・命名規則

既存のディレクトリ構造をClaudeに伝える。

## 配置の境界線
 
- `pages/` は使わない(App Router のみ)
- ページ直下のコンポーネントは co-located 可
- `lib/` は汎用ユーティリティだけ。ページ固有のものは `app/<route>/_lib/` に置く

ポイント: 「この規則に従って」ではなく、具体的な境界線(ページ固有は app/<route>/_lib/) を引くと迷いが減ります。コードから導ける一覧は書かず、守られなかった境界線だけを書く形が向いています。/doctor の整理(v2.1.206以降)も、ディレクトリ構成や依存の一覧、アーキテクチャの概説を削る側に置いています。

パターン7: コメントポリシー

コメントに対する姿勢を定義しておくと、書く量の基準がそろいます。

## コメント
 
### 書く
- "なぜそうしているか" が非自明な箇所(隠れた制約・回避策の由来)
- 公開 API の使い方(JSDoc スタイル)
 
### 書かない
- コードが言語で自明なこと(`// increment counter`)
- 削除済みコードの痕跡(`// removed old implementation`)
- チーム内の TODO(代わりに Issue を立てる)

ポイント: 書く/書かないの境目を "WHYかWHATか" で一貫させると、迷う箇所が減ります。

パターン8: 危険操作ガード

rm -rf や git push --force など、破壊的コマンドへのガードを書くパターン。

## 危険操作
 
以下は **必ず事前承認** を取る:
 
- `rm -rf` を含むコマンド
- `git push --force` / `--force-with-lease`
- `git reset --hard`
- `git branch -D`
- 本番 DB へのマイグレーション / データ変更
- `.env*` ファイルの編集・削除

ポイント: .claude/settings.json の permissions と組み合わせると、CLAUDE.md側で意図を宣言 + settings側で機械的にdeny、という二重防御になります。settings.json の許可ルール設計そのものはClaude Code設定の全体像、運用面のリスク整理はClaude Codeセキュリティ運用ガイドに分けて書いています。

パターン9: Import / 呼び出し規約

@/ エイリアスの使い方、デフォルトエクスポート禁止、ライブラリ選定基準など。

## Import / 呼び出し規約
 
- 内部 import は `@/lib/...` の形式(相対パス `../../lib/...` は禁止)
- React コンポーネントは **named export** を使う(default export 禁止)
- 日付操作は `date-fns`。`moment` は追加しない(依存削減のため)
- HTTP クライアントは `fetch` を直接使う(`axios` は追加しない)

ポイント: これらは人間側のコードレビューでも毎回指摘していることが多く、CLAUDE.mdに書いておけば、レビューで繰り返す指摘を先に伝えられるパターンです。

パターン10: 守られない指示を絞って強調する

守られない指示が1つだけ残るなら、その行にだけ IMPORTANT のような強調を足します。多くの行を強調すると、どの行も目立たなくなります。

## 特に守ってほしいこと
- IMPORTANT: 公開 API のシグネチャを変える前に、必ず確認を取る

ポイント: 毎回確実に実行したい処理は、CLAUDE.mdではなくhookに置きます。

セッションが長くなると、会話の前半の指示が薄れることはあります。プロジェクト直下のCLAUDE.mdは、/compact の後もディスクから読み直されます。入れ子のCLAUDE.mdと paths 付きのrulesは、該当ファイルを再び読んだときに読み込み直されます。/compact の後に消える指示は、会話の中だけで出したものと、まだ読み込み直されていない入れ子のCLAUDE.mdや paths 付きのrulesです。会話だけで出した指示を残したいなら、CLAUDE.mdに書きます。

使い分け早見表

よくある落とし穴

落とし穴1: 長すぎると守られにくくなる

公式の目安は1ファイル200行未満で、長いほどコンテキストを消費して守られにくくなります。200行を超えたファイルには、起動時と /status に警告が出ます。各CLAUDE.md・rules・@ で取り込んだファイルは別ファイルとして数えられ、1ファイルずつは目安内でも、合計が上限を超えると起動時に警告されます。4 MiBを超えるファイルは読まれません。同一内容を2重で書かず、一部のコードにだけ関係する指示は、次節の .claude/rules/ に移します。

落とし穴2: グローバルと競合している

~/.claude/CLAUDE.md のユーザー指示は、プロジェクトの指示より前に読み込まれます。ただしどちらも他方を上書きしないので、矛盾する指示があると、Claudeがどちらに従うかは決まりません。ユーザー側には日本語指定やコミット署名の扱いのような、プロジェクトと衝突しない好みだけを置きます。モノレポで他チームの CLAUDE.md まで読み込まれてしまう場合は、設定の claudeMdExcludes にパスやglobを書くと除外できます。ただし管理ポリシーの CLAUDE.md は除外できません。

落とし穴3: "なぜ" が書かれていない

"コメントを書くな" だけだと、後から見直したときに残すか消すかを判断できません。"なぜ" を一行添えておくと判断しやすくなります(例: "コメントが多いと差分レビューの負担が上がるため")。

落とし穴4: 更新しない

プロジェクト初期に書いたCLAUDE.mdを放置すると、現実のコードとルールがずれてClaudeが混乱します。古い指示や存在しないコマンドへの参照を探すには、/doctor prompt-audit が使えます(v2.1.283以降)。指摘と修正案が返り、適用を頼むまでファイルは変わりません。点数付きの棚卸しが欲しいときは、claude-md-managementプラグインという手もあります。

長くなったCLAUDE.mdを分ける

200行を超えそうなときの逃がし先は3つあります。分け方は、「全セッションで要るか」「一部のファイルだけか」「複数手順の作業か」で決まります。

@path/to/file と書くと別ファイルを取り込めますが、取り込んだファイルも起動時に読まれるため、コンテキストの消費は減りません。整理のための機能です。コードスパンやコードブロックの中の @ は取り込まれないので、パスを文字のまま書くときはバッククォートで囲みます。

消費を減らすには、.claude/rules/ に1トピック1ファイルで置き、paths で対象を絞ります。次のルールは、src/api/ のTypeScriptをClaudeが読み書きしたときだけ読み込まれます。

---
paths:
  - "src/api/**/*.ts"
---
 
# API開発のルール
 
- すべてのエンドポイントで入力を検証する

複数手順の作業は、Skillsに移すと、本文は必要になったときに読み込まれます。人間の保守者向けのメモは、<!-- メモ --> のブロックコメントで書けば、コンテキストには入りません。

別ディレクトリを --add-dir で足した場合、そちらの CLAUDE.md は既定では読まれません。環境変数 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 を付けて起動すると読み込まれます。このとき読まれるのは CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md、CLAUDE.local.md で、AGENTS.md は対象外です。--setting-sources から local を外すと、CLAUDE.local.md は読まれません。

作業ディレクトリかその上位に CLAUDE.md も CLAUDE.local.md も無いとき、Claudeは AGENTS.md を読みます(v2.1.277以降)。.claude/CLAUDE.md も数えますが、~/.claude/CLAUDE.md、管理ポリシーの CLAUDE.md、rulesは数えません。どちらかがあると CLAUDE.md 系だけが読まれるので、CLAUDE.local.md だけを置くと AGENTS.md が読まれなくなります。共有したいときは CLAUDE.md の先頭に @AGENTS.md と書きます。併用のための設定 claude-md-and-agents-md もあり、読み込まれたファイルは /memory で確認できます。Bedrockなどでは、v2.1.281未満だと AGENTS.md が読めません。

まとめ

どのパターンから入るかは、早見表の「困り事」の列から選べます。ファイルが200行に近づいたら、一部のコードにだけ関わる指示を .claude/rules/ に移し、全セッションで要る指示だけを残します。

CLAUDE.mdの外側で組み合わせるパーツとして、定型タスクの切り出しはSkillsで使える5つの設計パターン、自動承認とフックでの強制はClaude Code Hooksのはじめ方、複数モードを束ねる運用はClaude Codeワークフロー集が近い距離の関連記事です。CLAUDE.mdが人間向けの規約だとすれば、JSDoc・README・変更ログのようなコード側のドキュメントを生成・更新する具体的な手順はClaude Codeドキュメント生成にまとめています。特定フレームワーク向けに環境構築から書き足す例はClaude CodeでReact Nativeアプリを実機ビルドまで作る手順にあります。