Claude CodeのCLAUDE.mdを実用に引き上げる10のパターン

要点

Claude Codeが起動時に読み込む CLAUDE.md は、対話セッション全体の "憲法" です。空のまま放置するか、一行 "日本語で答えて" だけ書いているユーザーが大半ですが、10のパターンのうち効きそうなものから入れるだけで、プロジェクト固有の面倒な指示を毎回打つ手間が消え、回答品質も体感レベルで上がります。以下、実プロジェクト由来のサンプル付きで紹介します。

CLAUDE.md が果たす役割の前提や、settings.json などほかの設定との位置関係はClaude Code完全ガイド・Claude Code設定の全体像に独立した記事があります。本稿はその上に乗る「中身の書き方」を10パターンに絞った内容です。

なぜCLAUDE.mdが重要か

Claude Codeは起動時に、カレントディレクトリ + 親ディレクトリに置かれた CLAUDE.md を自動で読み込みます(グローバルな ~/.claude/CLAUDE.md も併用)。これは単なるシステムプロンプト的ファイルではありません。

• すべてのツール呼び出しに影響する: Bash / Edit / Writeなどの全ツール使用時の判断基準
• すべての応答に影響する: 文体・詳しさ・確認の頻度まで変わる
• 人間側の負担を消せる: 毎回同じ注意書きを書かなくてよい

一方で、CLAUDE.mdが薄い/ぶれている/矛盾している と、以下のような症状が出ます:

• 毎回「日本語で答えて」「コメント書かないで」と言い直す羽目になる
• 同じコマンドを毎回承認させられる(もしくは、承認せず勝手に動いて驚く)
• プロジェクト固有の規約を知らずに冗長コードを生成される

以下に紹介する10パターンは、すべてこれらの症状を減らすためのものです。

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

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

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

ポイント: 「開発パートナー」「チームメイト」「コードレビュアー」など、Claudeが既に持っている既定振る舞いを上書きする語を使うと効きやすい。「優秀な〜」のような褒め言葉は無意味(既に振る舞っている)。

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

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

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

ポイント: Claudeは "暗黙的に何タスクか" を判断しがちですが、明示されたモード分岐 のほうが安定します。

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

"やってほしくないこと" をリスト化するパターン。性能改善効果が最も大きいと言えそうなのがこの型です。

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

ポイント: "避けるべきこと" は肯定文("〜する")よりも否定文("〜しない")で書いたほうが伝わりやすい傾向があります(対話ログで観察される現象)。

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

Claudeはテストを走らせるべきタイミングを知りません。プロジェクトの規約を書くとぶれが消えます。

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

ポイント: どのコマンドを・どのタイミングで走らせるかが曖昧だと、Claudeは走らせずに「動くはず」と提出してきます。具体的な動詞で書く。

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

1行書くだけで大きな効果があるパターン。

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

ポイント: プレフィックスは形式だけなのでClaudeは守れる。「本文(2行目以降)は長い説明のみ」等を明記するとなお良し。

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

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

## ディレクトリ構成
 
- `app/` — Next.js App Router(pages/ は使わない)
- `components/` — React コンポーネント(ページ直下のコンポーネントは co-located 可)
- `lib/` — 汎用ユーティリティ。ページ固有のものは `app/<route>/_lib/` に置く
- `content/` — MDX 記事(frontmatter 必須、スキーマは別項参照)

ポイント: 「この規則に従って」ではなく、具体的な境界線(ページ固有は app/<route>/_lib/) を引くと迷いが消えます。

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

コメントに対する姿勢を定義しないと、Claudeは過剰に書いたり全く書かなかったりします。

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

ポイント: 書く/書かないの境目を "WHYかWHATか" で一貫させるとClaudeも守れます。

パターン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: リマインダ戦略(長文対策)

CLAUDE.mdが長くなるほど、後半のルールが忘れられる傾向があります。その対策。

## リマインダ
**毎ターン思い出してください:**
1. コメントは "WHY" のみ(パターン7)
2. Claude 署名を付けない(パターン5)
3. デッドコードを残さない(パターン3)
4. `npm run build` を変更後に走らせる(パターン4)
 
この4点は**優先度最高**です。

ポイント: CLAUDE.mdの末尾に再掲するセクションを置くと、対話が長くなったときの劣化を抑制できます。"毎ターン思い出してください" という明示的なフレーズが効く(経験則)。

使い分け早見表

よくある落とし穴

落とし穴1: 冗長すぎてClaudeが最後まで読まない

CLAUDE.mdを500行超にすると、後半のパターンが軽視されやすい傾向があります。同一内容を2重で書かず、200〜300行以内に収めるのが経験上の目安です。

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

~/.claude/CLAUDE.md のグローバル設定と、プロジェクトの CLAUDE.md が矛盾していると、どちらが優先されるかで挙動がぶれます。プロジェクト側を優先する運用にして、グローバルには最小限(日本語指定・コミット署名禁止など)だけ置くのが扱いやすいです。

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

"コメントを書くな" だけだと、Claudeは判断に迷ったときにルールから外れがちです。"なぜ" を一行添えると守ってくれます(例: "コメントが多いと差分レビューの負担が上がるため")。

落とし穴4: 更新しない

プロジェクト初期に書いたCLAUDE.mdを放置すると、現実のコードとルールがずれてClaudeが混乱します。月1程度の見直しをおすすめします。

まとめ

CLAUDE.mdは "起動時に自動で読まれるプロンプト" ではなく、プロジェクトの憲法として設計する価値があります。上記の10パターンのうち、自分のプロジェクトで効きそうなもの3〜5個から始め、対話で不満が出た箇所を追加していく形が現実的な運用です。

短い改善を積み重ねるだけで、「Claudeに毎回同じことを言っている」という摩擦が消えていきます。CLAUDE.mdの外側で組み合わせるパーツとして、定型タスクの切り出しはSkillsで使える5つの設計パターン、自動承認とフックでの強制はClaude Code Hooksのはじめ方、複数モードを束ねる運用はClaude Codeワークフロー集が近い距離の関連記事です。