CLAUDE.mdとは何か
Claude Codeには、プロジェクトごとに「AIへの指示書」を作成できる仕組みがある。それがCLAUDE.mdだ。
CLAUDE.mdはプロジェクトのルートディレクトリに配置するMarkdownファイルで、Claude Codeが毎セッション開始時に自動で読み込む。コーディング規約、プロジェクト構成、よく使うコマンド、禁止事項などを書いておけば、毎回同じ指示を繰り返す必要がなくなる。
2026年現在、CLAUDE.mdの活用度合いがClaude Codeの生産性を大きく左右すると言われている。この記事では、効果的なCLAUDE.mdの書き方をゼロから解説する。
なぜCLAUDE.mdが重要なのか
CLAUDE.mdがないと、Claude Codeは毎回「まっさらな状態」からスタートする。プロジェクトのファイル構造は自動で把握するが、コーディングスタイル、命名規則、テスト方針といった「暗黙のルール」までは読み取れない。
結果として、毎回「TypeScriptのstrictモードで書いて」「テストはVitestを使って」「コンポーネント名はPascalCaseで」と指示する羽目になる。CLAUDE.mdに一度書いておけば、この手間がすべて消える。
CLAUDE.mdの基本構成
効果的なCLAUDE.mdは20〜30行に収めるのがベストプラクティスだ。長すぎるとコンテキストウィンドウを圧迫し、本来の作業に使えるトークンが減ってしまう。
| セクション | 内容 | 例 |
|---|---|---|
| プロジェクト概要 | 何のプロジェクトか1〜2行で | 「Next.js 14 + TypeScriptのSaaSアプリ」 |
| 技術スタック | 使用フレームワーク・ライブラリ | 「React, Tailwind CSS, Prisma, PostgreSQL」 |
| コマンド | ビルド・テスト・デプロイ | 「npm run dev / npm test / npm run build」 |
| コーディング規約 | 命名規則・スタイル | 「関数はcamelCase、型はPascalCase」 |
| 禁止事項 | やってはいけないこと | 「any禁止、console.log残さない」 |
| ディレクトリ説明 | 主要フォルダの役割 | 「src/lib/にユーティリティ関数」 |
実践テンプレート：コピペして使える
以下は、一般的なNext.jsプロジェクト用のCLAUDE.mdテンプレートだ。
# プロジェクト概要
Next.js 14 + TypeScript + Tailwind CSSのブログプラットフォーム。
# 技術スタック
- フロント: Next.js 14 (App Router), React 18, Tailwind CSS
- バックエンド: Next.js API Routes, Prisma ORM
- DB: PostgreSQL (Supabase)
- テスト: Vitest + Testing Library
# コマンド
- dev: npm run dev
- build: npm run build
- test: npm test
- lint: npm run lint
# コーディング規約
- TypeScript strictモード必須
- 関数コンポーネントのみ使用（クラスコンポーネント禁止）
- 命名: コンポーネント=PascalCase, 関数=camelCase, 定数=UPPER_SNAKE_CASE
- インポート順: React → 外部ライブラリ → 内部モジュール → 型
# 禁止事項
- any型の使用禁止
- console.logをコミットに含めない
- インラインスタイル禁止（Tailwindを使う）
# ディレクトリ構造
- src/app/ : ページ・レイアウト
- src/components/ : 共通UIコンポーネント
- src/lib/ : ユーティリティ・ヘルパー
- src/types/ : TypeScript型定義
- prisma/ : スキーマ・マイグレーション上級テクニック：サブディレクトリCLAUDE.md
プロジェクトのルートだけでなく、サブディレクトリにもCLAUDE.mdを配置できる。たとえば、src/components/にCLAUDE.mdを置けば、コンポーネント作成時だけ適用される特別なルールを定義できる。
APIエンドポイントのフォルダには「レスポンス形式は必ず{success, data, error}の統一フォーマットで」、テストフォルダには「各テストファイルにdescribeブロックを必ず含める」といった具合だ。
よくある失敗パターン
| 失敗 | 問題 | 解決策 |
|---|---|---|
| 100行以上書く | コンテキストウィンドウを圧迫 | 20〜30行に凝縮する |
| 曖昧な表現 | Claude Codeが解釈に迷う | 具体的なルールを明記 |
| 更新しない | プロジェクトの変化に追随しない | 月1回は見直す |
| すべてを書く | 当然のことまで書いて冗長に | 例外ルールや独自ルールだけ書く |
チーム開発でのCLAUDE.md運用
チーム開発では、CLAUDE.mdをGitリポジトリに含めて共有するのがおすすめだ。チーム全員が同じルールでClaude Codeを使えるため、コードの一貫性が保たれる。
また、個人的な設定は~/.claude/CLAUDE.md（ホームディレクトリのCLAUDE.md）に書ける。こちらはすべてのプロジェクトに適用されるグローバル設定だ。「日本語で応答して」「コミットメッセージは英語で」といった個人の好みはここに書くと良い。
まとめ：CLAUDE.mdは最初に作る「投資」
CLAUDE.mdの作成には10分もかからない。しかし、この10分の投資が、その後の数十時間の開発体験を劇的に改善する。Claude Codeを使い始めたら、コードを書く前にまずCLAUDE.mdを作成しよう。