先日、チームメンバーから「Claudeに同じ指示を毎回繰り返している気がする」と相談を受けました。Xを開けば毎日のようにClaude Codeの新しい使い方が流れてきますが、しっかり腰を据えて勉強する時間はなかなか取れないですよね。
私自身、Claude Codeを使い始めた頃は「TypeScriptのstrict modeを守って」「anyを使わないで」と毎セッション言い続けて疲弊していました。しかし CLAUDE.md の設計パターンを整えてからは、ほとんど指示を繰り返すことなく、自分の規約通りのコードが返ってくるようになりました。
本記事では、CLAUDE.md の階層構造の使い分けからモジュール分割、Why付きルールの書き方まで、実プロジェクトで効いた設計パターンを具体例とともに公開します。
記事末尾には「これだけ送ればOK」なコピペ用プロンプトも置いているので、忙しい方はそれを送るだけでも大丈夫です。
図: CLAUDE.mdの3階層
。
1. CLAUDE.mdの階層構造を理解する
CLAUDE.md は、Claude Codeがセッション開始時に自動で読み込むマークダウン形式の指示書です。読み込まれる優先順位は以下のとおりです。
~/.claude/CLAUDE.md— ユーザーグローバル（全プロジェクト共通）- プロジェクトルートの
CLAUDE.md— チーム共有 - サブディレクトリの
CLAUDE.md— その配下で作業中のみ有効
この階層を意識せずに全部プロジェクトルートに書いてしまうのが、よくあるアンチパターンです。グローバルには言語や好みなど普遍的なルールを、プロジェクトには技術スタックや命名規則を、サブディレクトリにはモジュール固有の注意点を置くのが基本パターンとされています。
私の場合、~/.claude/CLAUDE.md には「日本語で応答する」「不明点は推測せず確認する」など全プロジェクト共通のルールだけを置き、プロジェクトごとの具体ルールはルート配下の CLAUDE.md に分けています。
2. トークン効率を意識した記述
CLAUDE.md の中身はすべて毎回コンテキストに乗ります。冗長な説明はトークンを浪費し、重要な指示が薄まる原因になります。推奨されているのは**「箇条書き中心・命令形・1行1ルール」**のスタイルです。
悪い例:
このプロジェクトではTypeScriptを使っているのですが、
なるべくstrict modeを有効にしておきたいと考えています。
また、anyを使うのはできれば避けてほしいです。
良い例:
## TypeScript
- strict mode必須
- `any`禁止（やむを得ない場合は`unknown`+型ガード）
- 型インポートは`import type`を使用
後者は約1/3のトークンで同じ情報を伝えられます。500行を超える CLAUDE.md はアンチパターンとされており、肥大化した場合は次のセクションのモジュール分割が有効です。
図: CLAUDE.mdの書き方ビフォーアフター
3. モジュール分割パターン
大規模プロジェクトでは、ルールをカテゴリごとに分割し、CLAUDE.md から参照する方法が一般的です。
# MyProject
## Stack
- Next.js 16 (App Router) / TypeScript / Tailwind v4
- Supabase (DB + RLS)
- Vercel (Deploy + Cron)
## Rules
詳細ルールは以下を参照:
- `docs/rules/typescript.md`
- `docs/rules/testing.md`
- `docs/rules/security.md`
## Architecture
- `lib/fetchers/` — 外部データ収集
- `lib/ai/` — Claude API呼び出し
- `app/api/cron/` — Vercel Cronエンドポイント
Claude Codeは必要に応じて参照先ファイルを Read ツールで開きにいきます。常時ロードする情報は最小限にし、詳細はオンデマンドで読ませる設計が、トークン効率と網羅性を両立させるコツです。
4. 命令の粒度と「Why」の明示
中級者がやりがちな失敗が、ルールを書くだけで「なぜそうするか」を書かないことです。理由を添えると、Claudeは想定外のエッジケースでも適切に判断できます。
## DBアクセス
- 生SQLは禁止、Supabaseクエリビルダーを使用
- 理由: SQLインジェクション対策とRLSの確実な適用
- joinの型キャストは `as unknown as { ... }` パターンを使用
- 理由: Supabase型生成器がjoin結果を正しく推論できないため
「禁止」「必須」だけでは、Claudeが例外判断を求められた際にユーザーへの確認が増えます。理由まで書くと自律性が上がり、結果的にやり取り回数が減ります。
図: CLAUDE.md設計の手順
5. 実践テンプレート
以下は実プロジェクトでそのまま使えるテンプレートです。
# プロジェクト名
一行で何のプロジェクトか説明する。
## Stack
- 言語/フレームワーク（バージョン明記）
- DB / 認証 / デプロイ先
- 主要な外部API
## Architecture
- ディレクトリ構造を3-7行で
- 各ディレクトリの責務
## Conventions
- 命名規則（ファイル/変数/型）
- インポートパス規約
- エラーハンドリング方針
## Commands
- `npm run dev` — 開発サーバー
- `npm run test` — テスト実行
- `npm run lint` — Lint
## Don'ts
- してほしくないこと（理由付き）
- 過去にハマった罠
## Notes
- 進行中の移行作業
- 既知の技術的負債
この構造の強みは、新しくチームに入ったメンバーがオンボーディング資料としても読める点です。AI向けと人間向けのドキュメントを兼用できるのが、よく設計された CLAUDE.md の特徴と言えます。
6. メンテナンスとアンチパターン
CLAUDE.md は「書いて終わり」ではなく、プロジェクトの成長に合わせて更新が必要です。私の場合、週次の振り返りで「今週Claudeに何回同じ指示をしたか」を見直し、3回以上繰り返した指示は CLAUDE.md に追加するルールにしています。
アンチパターンとしてよく見るのは以下です。
- ポエム化: 思想や背景を長文で書き、ルールが埋もれる
- 重複: グローバルとプロジェクトに同じルールが書かれている
- 古い情報: 既に廃止したライブラリの注意書きが残っている
- 過剰な禁止: 「〜は使わない」だけが並び、代替案がない
これらを避けるだけでも、Claudeの応答品質は目に見えて変わります。
🎁 特典: コピペ用プロンプト集
既存プロジェクトの CLAUDE.md をClaude自身に作らせるプロンプトです。プロジェクトルートで Claude Code を起動し、そのまま貼り付けてください。
あなたはClaude Code向けのCLAUDE.md設計の専門家です。
以下の手順でこのプロジェクト用の最適なCLAUDE.mdを設計してください。
1. プロジェクトルートのpackage.json, tsconfig.json, README, 主要ディレクトリ構成を読む
2. 技術スタック・ディレクトリ責務・命名規則・スクリプトコマンドを抽出する
3. 以下のテンプレート構造でCLAUDE.mdを生成する:
- # プロジェクト名 + 一行説明
- ## Stack（バージョン明記）
- ## Architecture（ディレクトリ責務）
- ## Conventions（命名・インポート・エラー処理）
- ## Commands（dev/test/lint等）
- ## Don'ts（禁止事項 + 理由）
- ## Notes（進行中の移行・技術的負債）
4. 1行1ルール・命令形・箇条書き中心で記述する
5. 各禁止/必須ルールには必ず「理由:」を添える
6. 全体で200行以内に収める。超える場合はdocs/rules/配下に分割案を提示する
7. 既存CLAUDE.mdがある場合は差分のみ提示し、上書き前に確認を求める
📚 参考リファレンス
- awesome-claude-code — Claude Codeエコシステム全体の定番キュレーション
- Claude Code 公式ベストプラクティス — Anthropic公式のCLAUDE.md推奨パターン
- Claude Code Memory ドキュメント — メモリファイルの階層と読み込み順序の公式解説
