CLAUDE.md 設定のススメ — Claude Codeを10倍使いこなすプロジェクト設定術
CLAUDE.mdとは
CLAUDE.mdは、Claude Codeに「このプロジェクトではこう動いてほしい」と伝えるための設定ファイルです。プロジェクトのルートに置くだけで、Claudeが毎回自動的に読み込みます。
私の体験談
筆者は5つのプロジェクトを並行運用していますが、CLAUDE.mdを整備してからClaude Codeの「的外れな回答」が激減しました。体感で作業効率が2〜3倍になっています。
この記事でわかること:
- CLAUDE.mdの基本的な書き方
- 実運用で効果の高い設定パターン
- プロジェクト規模別のテンプレート
- やりがちな失敗と対策
CLAUDE.mdの基本構成
最低限、以下の3つを書けばすぐに効果が出ます。
# プロジェクト名
## 技術スタック
- Next.js 16 (App Router) + TypeScript
- Supabase (Auth, DB)
- Stripe (決済)
## 重要ルール
- 〇〇のクライアントは既存ユーティリティを使う（新規作成しない）
- 環境変数は `.env.local` 参照（コミット禁止）
## ディレクトリ構成の要点
- `app/[locale]/` — ページ
- `app/api/` — APIルート
- `lib/` — ユーティリティ
これだけで、Claudeは技術スタックを把握し、既存の設計パターンを尊重してくれます。
効果の高い設定パターン5選
パターン1：読み取り禁止ディレクトリ
Claudeが node_modules/ を探索し始めると、数万トークンが一瞬で消えます。
### 読み取り禁止ディレクトリ
- node_modules/
- .next/
- dist/
- build/
- coverage/
効果：トークン消費を大幅に削減
パターン2：探索→実装のワークフロー制御
### 探索フェーズ
- まずディレクトリ構造とimport関係から推測する
- ファイル全文は必要になるまで読まない
- 候補は最大5ファイルまで
- 有力な1ファイルが見つかった時点で停止
### 実装フェーズ
- 原則1ファイルのみ変更
- 他ファイル参照は最大1つまで
- リファクタ禁止・横展開禁止
- 最小差分で解決する
パターン3：出力フォーマットの制御
Claudeはデフォルトで丁寧すぎる回答をします。短く的確にしてもらいましょう。
### 出力ルール
- 長文説明禁止
- 出力は以下を優先: 対象ファイル、理由、次の1アクション
- コード修正は diff 形式を優先
パターン4：既存ユーティリティの明示
「なぜか新しいファイルを作られる」問題の解決策です。
## Supabase クライアント（重要）
新規にクライアントを作成しないこと。以下の既存ユーティリティを使う：
| ファイル | 用途 |
|---------|------|
| `lib/supabase/client.ts` | ブラウザ用 |
| `lib/supabase/server.ts` | サーバー用 |
パターン5：停止ルール
Claudeが暴走して大量のコードを書き換えるのを防ぎます。
### 停止ルール
- 有力候補が見つかったらそれ以上探索しない
- 指示されていない範囲に広げない
- 不確実でも一旦止まってユーザーに確認する
プロジェクト規模別テンプレート
小規模（個人プロジェクト・スクリプト）
# プロジェクト名
## 概要
[1行で何をするプロジェクトか]
## 技術スタック
- [言語/フレームワーク]
## ルール
- 日本語でコミュニケーション
- 最小差分で解決する
中規模（SaaS・Webアプリ）
# プロジェクト名
## 技術スタック
[使用技術一覧]
## 重要ルール
[やってはいけないこと、使うべき既存コードの指定]
## ディレクトリ構成の要点
[主要ディレクトリの説明]
## 節約運用ルール
[探索・実装・出力のルール]
## 読み取り禁止ディレクトリ
[除外リスト]
大規模（モノレポ・チーム開発）
モノレポの場合、ルートと各サブプロジェクトの両方にCLAUDE.mdを配置します。
repo/
├── CLAUDE.md ← 共通ルール
├── frontend/
│ └── CLAUDE.md ← フロント固有ルール
├── backend/
│ └── CLAUDE.md ← バックエンド固有ルール
ルートのCLAUDE.mdから各サブプロジェクトを参照することもできます。
AGENTS.mdとの使い分け
Claude Codeには AGENTS.md という別の設定ファイルもあります。
| ファイル | 役割 |
|---|---|
| CLAUDE.md | プロジェクト全般のルール・構成・制約 |
| AGENTS.md | アーキテクチャ詳細・API仕様・技術的注意事項 |
筆者の場合、CLAUDE.mdに「何を使うか」、AGENTS.mdに「どう使うか」を書いています。
よくある失敗パターン
❌ 設定が長すぎる
CLAUDE.md自体が巨大だと、それを読むだけでトークンを消費します。100行以内を目安にしましょう。
❌ 抽象的すぎるルール
# 悪い例
- きれいなコードを書くこと
- ベストプラクティスに従うこと
# 良い例
- Supabaseクライアントは lib/supabase/client.ts を使う
- APIルートは app/api/ 配下に作る
❌ 設定を更新しない
プロジェクトが進化してもCLAUDE.mdが古いままだと、Claudeが間違った前提で動きます。大きな構成変更の後は必ず更新しましょう。
まとめ
| やること | 効果 | 優先度 |
|---|---|---|
| 技術スタック記載 | Claudeが正しい技術で書く | ★★★ |
| 読み取り禁止設定 | トークン大幅削減 | ★★★ |
| 既存ユーティリティ明示 | 不要なファイル作成防止 | ★★★ |
| 探索ワークフロー制御 | 効率的な作業進行 | ★★☆ |
| 出力ルール | 回答の簡潔化 | ★★☆ |
| 停止ルール | 暴走防止 | ★★☆ |
CLAUDE.mdは「Claudeへのオンボーディング資料」です。新しいメンバーに渡すつもりで書くと、自然と良い設定になります。
次に読む
→ Claude Code Hooks で事故を防ぐ — git secrets / 本番 DB 保護の実装 (¥500)
CLAUDE.md でプロジェクト設定を整えたら、次は「うっかり事故」の防止です。Hooks を使った 9 つの安全装置で、Claude Code 運用を本番事故ゼロにする実装を有料記事で全公開しています。