CLAUDE.md 完全ガイド

CLAUDE.md とは何か

CLAUDE.md は、Claude Code がプロジェクトを理解するための「文脈ファイル」だ。プロジェクトの概要、コーディング規約、使用ライブラリ、テストコマンドなどを記述することで、Claude Code がそのプロジェクト固有の知識を持った状態で作業できるようになる。

CLAUDE.md がない場合、Claude Code は一般的な知識のみで動作する。プロジェクトで Biome をリンターとして使っていても ESLint の設定を提案したり、pnpm プロジェクトなのに npm コマンドを実行したりする可能性がある。CLAUDE.md はこの「認識のズレ」を防ぐ。

---

なぜ CLAUDE.md が重要か

Claude Code はセッションを開始するたびに CLAUDE.md を読み込む。つまり、CLAUDE.md に書かれた内容は 毎回のセッションで自動的に反映 される。手動でプロジェクトの前提条件を説明する必要がなくなる。

CLAUDE.md がない場合の問題

ユーザー: テストを実行して
Claude: npm test を実行します
→ 失敗（このプロジェクトは pnpm を使用している）

ユーザー: リントして
Claude: eslint src/ を実行します
→ 失敗（このプロジェクトは Biome を使用している）

CLAUDE.md がある場合

Claude: pnpm test を実行します（CLAUDE.md に記載済み）
→ 成功

Claude: biome check src/ を実行します（CLAUDE.md に記載済み）
→ 成功

---

基本構造

CLAUDE.md は Markdown 形式で記述する。必須の項目はないが、以下の構造を推奨する。

# プロジェクト名

## 概要
プロジェクトの簡潔な説明（1-3文）

## 技術スタック
- 言語: TypeScript
- フレームワーク: Next.js 15 (App Router)
- スタイリング: Tailwind CSS
- テスト: Vitest + Playwright
- パッケージマネージャ: pnpm

## コマンド
- 開発サーバー: `pnpm dev`
- ビルド: `pnpm build`
- テスト: `pnpm test`
- リント: `pnpm lint`
- 型チェック: `pnpm typecheck`

## コーディング規約
- ファイルは機能単位で整理する
- コンポーネントは named export
- テストは co-located（対象ファイルの隣に配置）

## 注意事項
- Node.js 20以上が必要
- 環境変数は .env.local に設定

---

ファイル配置の階層

CLAUDE.md は複数レベルで設定でき、より具体的な設定が優先される。

~/.claude/CLAUDE.md          # ユーザー共通設定（全プロジェクト）
./CLAUDE.md                  # プロジェクト指示（チーム共有、Git管理推奨）
./CLAUDE.local.md            # 個人設定（Git管理外）
.claude/rules/               # パススコープルール（特定パスにのみ適用）

各ファイルの使い分け

ファイル	用途	Git管理	例
~/.claude/CLAUDE.md	個人の好み・全プロジェクト共通	なし	「回答は日本語で」「常にTypeScript strict」
./CLAUDE.md	プロジェクト固有の規約	あり	「pnpmを使用」「Biomeでリント」
./CLAUDE.local.md	個人のプロジェクト固有設定	なし	「ローカルDBの接続先」
.claude/rules/*.md	特定パスのルール	あり	「src/api/ ではZodでバリデーション」

---

実践的な書き方

良い例: 具体的で実行可能

# My App

## 概要
在庫管理のSPA。Next.js App Router + Prisma + Supabase。

## コマンド
- `pnpm dev` - 開発サーバー起動（ポート3001）
- `pnpm build` - 本番ビルド
- `pnpm test` - Vitestユニットテスト
- `pnpm test:e2e` - Playwright E2Eテスト
- `pnpm db:migrate` - マイグレーション実行
- `pnpm db:seed` - シードデータ投入

## 規約
- APIルートは `app/api/` に配置
- Server Componentsをデフォルトとし、"use client"は必要な場合のみ
- DBアクセスはPrismaクライアント経由（直接SQLは避ける）
- エラーレスポンスは `{ success: false, error: string }` の形式

## 注意
- SupabaseのRLSは必ず有効化
- テナントIDでのフィルタリングを全クエリに含める
- 環境変数は `.env.local` に設定（`.env` はGit管理外）

悪い例: 曖昧で実行不可能

# My App

このアプリは在庫管理をやっています。
普通に開発してください。
コードは綺麗に書いてください。

悪い理由:

• コマンドが書かれていない（Claudeがどのコマンドを使うべきか分からない）
• 技術スタックが書かれていない
• 規約が主観的（「綺麗に」の基準が不明）
• 注意事項がない

---

.claude/ ディレクトリの活用

.claude/ ディレクトリには CLAUDE.md 以外にも便利な設定が置ける。

rules/ - パススコープルール

特定のディレクトリやファイルパターンに対してのみ適用されるルール。

<!-- .claude/rules/api-routes.md -->
このディレクトリ内のAPIルートでは:
- 入力はZodスキーマでバリデーション
- レスポンスは `{ success: boolean, data?: T, error?: string }` の形式
- エラーは Error クラスのインスタンスを投げる

commands/ - カスタムコマンド

よく使うプロンプトをコマンド化する。

<!-- .claude/commands/review.md -->
---
description: "コードレビューを実行"
allowed-tools: ["Read", "Grep", "Glob", "Bash"]
---

以下の観点でコードをレビューしてください:
1. バグの有無
2. セキュリティ問題
3. パフォーマンス改善点
4. 可読性

$ARGUMENTS

settings.json - ツール権限設定

{
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": []
  }
}

---

チーム開発での CLAUDE.md 運用

基本方針

1. プロジェクトの CLAUDE.md は Git管理する - チーム全員が同じ文脈を共有
2. 個人設定は CLAUDE.local.md に - ローカル環境の差異はここに隔離
3. CLAUDE.md は README と重複させない - README は人間向け、CLAUDE.md は Claude 向けと割り切り、Claude が読むべき情報に絞る

チーム導入のステップ

1. /init で初期 CLAUDE.md を生成
2. プロジェクトの規約・コマンド・技術スタックを追記
3. レビュー後に Git にコミット
4. .claude/rules/ にパス固有のルールを追加
5. 定期的に更新（月1回程度）

CLAUDE.md のメンテナンス

CLAUDE.md は放置すると古くなり、かえって誤った指示になる。以下のタイミングで見直す:

• 新しいライブラリを導入したとき
• ビルドコマンドが変わったとき
• コーディング規約を更新したとき
• プロジェクトの構成が大きく変わったとき

---

まとめ

CLAUDE.md は「Claude Code にプロジェクトのことを理解してもらう」ための最も重要なファイルだ。適切に設定すれば、セッションごとの前提説明が不要になり、Claude Code の精度と効率が大幅に向上する。

CLAUDE.md の基本とクイックメモリの活用については、CLAUDE.md基本とクイックメモリ・ハッシュで詳しく解説しています。

次に読むべきガイド: Hooks で作業を自動化する では、CLAUDE.md に書いた規約を自動的に実行するフックの設定方法を学べる。

リファレンス

• 初心者向け学習パス - Step 4 で CLAUDE.md の基本を学ぶ
• Claude Code 公式ドキュメント

---

すぐ試したい方へ

基本的な設定だけ素早く試したい場合は、CLAUDE.md基本Tips で5分で始められます。