CLAUDE.md 設定のススメ — Claude Codeを10倍使いこなすプロジェクト設定術

CLAUDE.mdとは

CLAUDE.mdは、Claude Codeに「このプロジェクトではこう動いてほしい」と伝えるための設定ファイルです。プロジェクトのルートに置くだけで、Claudeが毎回自動的に読み込みます。

この記事でわかること:

• 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へのオンボーディング資料」です。新しいメンバーに渡すつもりで書くと、自然と良い設定になります。

---