📝

Tech

CLAUDE.mdの書き方完全ガイド【テンプレート付き】

Daiki React Dev 2026年2月5日 3,063 views

CLAUDE.mdとは

CLAUDE.mdは、Claude Codeがプロジェクトを理解するための設定ファイルです。プロジェクトのルートディレクトリに配置することで、Claude Codeが起動時に自動で読み込み、プロジェクトの文脈を把握します。

なぜCLAUDE.mdが重要なのか

CLAUDE.mdがないと、Claude Codeは毎回ゼロからプロジェクトを理解しようとします。これには以下の問題があります：

時間の無駄: 毎回「このプロジェクトはReactで...」と説明が必要
一貫性の欠如: セッションごとに異なる理解をされる
トークンの浪費: 同じ説明を繰り返すことでコストが増加
ルール違反: コーディング規約を守らないコードが生成される

CLAUDE.mdを適切に設定することで、これらの問題を解決できます。

CLAUDE.mdの読み込み優先順位

Claude Codeは複数のCLAUDE.mdを読み込むことができます。

| 場所 | スコープ | 優先度 |
|------|----------|--------|
| ~/.claude/CLAUDE.md | 全プロジェクト共通 | 低 |
| プロジェクトルート /CLAUDE.md | プロジェクト全体 | 中 |
| サブディレクトリ /src/CLAUDE.md | そのディレクトリ以下 | 高 |

複数のCLAUDE.mdがある場合、すべてが読み込まれ、より具体的な（サブディレクトリの）設定が優先されます。

基本テンプレート

まずは最小限のCLAUDE.mdから始めましょう。

最小構成（コピペOK）

# プロジェクト名

## 概要
このプロジェクトは〇〇のためのアプリケーションです。

## 技術スタック
- 言語: TypeScript
- フレームワーク: React 18
- スタイル: Tailwind CSS

## よく使うコマンド
- `npm run dev` - 開発サーバー起動
- `npm run build` - ビルド
- `npm test` - テスト実行

標準構成（推奨）

# プロジェクト名

## 概要
このプロジェクトは〇〇のためのWebアプリケーションです。
主な機能は□□と△△です。

## 技術スタック
- フロントエンド: React 18 + TypeScript
- バックエンド: Node.js + Express
- データベース: PostgreSQL
- インフラ: AWS (ECS, RDS, S3)

## ディレクトリ構造

src/
├── components/ # UIコンポーネント
├── pages/ # ページコンポーネント
├── hooks/ # カスタムフック
├── api/ # API呼び出し
├── types/ # 型定義
└── utils/ # ユーティリティ関数


## コーディング規約
- 関数はアロー関数で統一
- コンポーネントは関数コンポーネントのみ
- 状態管理はReact Queryを優先
- スタイルはTailwind CSSのユーティリティクラスを使用

## 禁止事項
- console.logを本番コードに残さない
- any型は使用禁止
- インラインスタイルは使わない
- classコンポーネントは使わない

## よく使うコマンド
- `npm run dev` - 開発サーバー起動（http://localhost:3000）
- `npm run build` - 本番ビルド
- `npm test` - テスト実行
- `npm run lint` - リント実行

効果的なCLAUDE.mdの書き方

ポイント1: 短く具体的に

CLAUDE.mdが長すぎると、重要な情報が埋もれてしまいます。必要最小限の情報に絞りましょう。

悪い例:

## 概要
このプロジェクトは、2024年1月に開始された、ユーザーが商品を検索して購入できる
Eコマースプラットフォームです。創業者のビジョンは...（中略）...
技術選定の経緯としては、最初はVueを検討していましたが...

良い例:

## 概要
ECサイト。商品検索・購入・決済機能を提供。

ポイント2: 例を添える

「〇〇にして」という抽象的な指示より、具体例を示す方が効果的です。

悪い例:

## コーディング規約
- 適切な命名規則を使う

良い例:

## コーディング規約
- 変数名: camelCase（例: `userName`, `isLoggedIn`）
- 関数名: camelCase（例: `fetchUserData`, `handleClick`）
- コンポーネント名: PascalCase（例: `UserProfile`, `LoginForm`）
- 定数: UPPER_SNAKE_CASE（例: `API_BASE_URL`, `MAX_RETRY_COUNT`）

ポイント3: 禁止事項を明記

「〇〇しないで」という禁止事項は特に効果的です。Claude Codeは禁止事項を尊重します。

## 禁止事項
- console.logは本番コードに残さない
- any型は使用禁止（unknownを使う）
- インラインスタイルは使わない（Tailwindクラスを使う）
- 日本語のコメントは書かない（英語で書く）
- jQuery関連のコードは書かない
- classコンポーネントは使わない

ポイント4: コマンドを記載

よく使うコマンドを記載しておくと、Claude Codeが適切なタイミングで実行してくれます。

## コマンド
| コマンド | 説明 |
|----------|------|
| `npm run dev` | 開発サーバー起動 |
| `npm run build` | 本番ビルド |
| `npm test` | テスト実行 |
| `npm run test:watch` | テストをウォッチモードで実行 |
| `npm run lint` | ESLintでコードチェック |
| `npm run lint:fix` | ESLintで自動修正 |
| `npm run typecheck` | TypeScript型チェック |

用途別テンプレート集

Reactプロジェクト用

# React Project

## 技術スタック
- React 18 + TypeScript
- Vite
- Tailwind CSS
- React Query (TanStack Query)
- React Router v6

## ディレクトリ構造

src/
├── components/ # 再利用可能なUIコンポーネント
│ ├── ui/ # ボタン、入力欄などの基本UI
│ └── features/ # 機能別コンポーネント
├── pages/ # ルーティング対象のページ
├── hooks/ # カスタムフック
├── api/ # API呼び出し関数
├── types/ # 型定義
├── utils/ # ユーティリティ関数
└── constants/ # 定数


## コンポーネント設計
- 関数コンポーネントのみ使用
- Propsの型は`type`で定義（interfaceは使わない）
- 状態管理: ローカル→Context→React Query→Zustandの順で検討

## 禁止事項
- classコンポーネント
- any型
- インラインスタイル
- useEffectでのデータフェッチ（React Queryを使う）

Next.js（App Router）プロジェクト用

# Next.js Project (App Router)

## 技術スタック
- Next.js 14 (App Router)
- TypeScript
- Tailwind CSS
- Prisma (ORM)
- PostgreSQL

## ディレクトリ構造

app/
├── (auth)/ # 認証関連ルート
├── (dashboard)/ # ダッシュボード関連
├── api/ # APIルート
├── layout.tsx # ルートレイアウト
└── page.tsx # ホームページ

components/
├── ui/ # shadcn/uiコンポーネント
└── features/ # 機能別コンポーネント

lib/
├── db.ts # Prismaクライアント
└── utils.ts # ユーティリティ


## App Router規約
- Server Componentsがデフォルト
- Client Componentsには'use client'を明記
- データフェッチはServer Componentsで行う
- ルートグループは()で囲む

## 禁止事項
- pages/ディレクトリの使用（App Routerのみ）
- getServerSideProps/getStaticProps（Server Componentsを使う）

Node.js APIプロジェクト用

# Node.js API

## 技術スタック
- Node.js 20 + TypeScript
- Express
- Prisma
- PostgreSQL
- Jest

## ディレクトリ構造

src/
├── controllers/ # リクエストハンドラ
├── services/ # ビジネスロジック
├── repositories/ # データアクセス層
├── middlewares/ # Expressミドルウェア
├── routes/ # ルート定義
├── types/ # 型定義
├── utils/ # ユーティリティ
└── index.ts # エントリーポイント


## アーキテクチャ
- Controller → Service → Repository の3層構造
- ControllerはHTTPのみを扱う
- Serviceはビジネスロジックを扱う
- Repositoryはデータアクセスのみ

## エラーハンドリング
- カスタムエラークラスを使用
- グローバルエラーハンドラーで一括処理
- 本番環境ではスタックトレースを隠す

Pythonプロジェクト用

# Python Project

## 技術スタック
- Python 3.11
- FastAPI
- SQLAlchemy
- PostgreSQL
- pytest

## ディレクトリ構造

app/
├── api/ # APIエンドポイント
│ └── v1/ # バージョン1のAPI
├── core/ # 設定、セキュリティ
├── models/ # SQLAlchemyモデル
├── schemas/ # Pydanticスキーマ
├── services/ # ビジネスロジック
└── main.py # エントリーポイント

tests/
├── unit/ # ユニットテスト
└── integration/ # 統合テスト


## コーディング規約
- 型ヒントは必須
- docstringはGoogle形式
- フォーマッタ: Black
- リンタ: Ruff

## 禁止事項
- グローバル変数の使用
- print文でのデバッグ（loggingを使う）
- except Exception:（具体的な例外を指定）

よくある間違いと対処法

間違い1: 長すぎるCLAUDE.md

数千文字のCLAUDE.mdは逆効果です。Claude Codeが重要な情報を見落としやすくなります。

対処法: 500〜1000文字程度に収める。詳細は別ドキュメントに分ける。

間違い2: 矛盾する指示

## コーディング規約
- 関数はアロー関数で統一
- クラスメソッドは通常のfunction宣言を使用  ← 矛盾

対処法: 指示は一貫させる。例外がある場合は明記する。

間違い3: 曖昧な指示

- 適切なエラーハンドリングをする
- きれいなコードを書く

対処法: 具体的に書く。

- エラーはtry-catchで捕捉し、カスタムエラークラスを投げる
- 1関数20行以内、1ファイル200行以内を目安にする

間違い4: 古い情報を放置

プロジェクトの技術スタックが変わったのに、CLAUDE.mdを更新しないと、古い技術でコードが生成されます。

対処法: 技術スタックを変更したらCLAUDE.mdも更新する。

サブディレクトリ別CLAUDE.md

大規模プロジェクトでは、ディレクトリごとにCLAUDE.mdを配置できます。

ディレクトリ構造例

project/
├── CLAUDE.md              # プロジェクト全体の設定
├── frontend/
│   ├── CLAUDE.md          # フロントエンド固有の設定
│   └── src/
└── backend/
    ├── CLAUDE.md          # バックエンド固有の設定
    └── src/

frontend/CLAUDE.md の例

# Frontend

## 親のCLAUDE.mdを補足
このディレクトリはReact + TypeScriptのフロントエンドです。

## 追加のコーディング規約
- コンポーネントは1ファイル1コンポーネント
- スタイルはTailwind CSSのみ（CSS Modulesは使わない）
- テストはReact Testing Libraryを使用

backend/CLAUDE.md の例

# Backend

## 親のCLAUDE.mdを補足
このディレクトリはNode.js + Expressのバックエンドです。

## 追加のコーディング規約
- APIレスポンスは必ず型定義する
- データベースアクセスはリポジトリパターン
- テストはJest + Supertestを使用

CLAUDE.mdの自動生成

Claude Code自体にCLAUDE.mdを生成してもらうこともできます。

claude

> このプロジェクトを分析して、最適なCLAUDE.mdを作成して

Claude Codeがプロジェクトの構造を分析し、適切なCLAUDE.mdを提案してくれます。その後、必要に応じて手動で調整しましょう。

まとめ

CLAUDE.mdを適切に設定することで、Claude Codeの効果を最大限に引き出せます。

CLAUDE.md設定のチェックリスト

[ ] プロジェクトの概要を1〜2文で記載
[ ] 技術スタックを列挙
[ ] ディレクトリ構造を記載
[ ] コーディング規約を具体的に記載
[ ] 禁止事項を明記
[ ] よく使うコマンドを記載
[ ] 500〜1000文字程度に収まっている

[Claude Codeとは？使い方・始め方・料金を徹底解説](/posts/what-is-claude-code/)
[Claude Codeの始め方【インストールから初回実行まで】](/posts/getting-started/)
[MCPサーバーとは？Claude Codeを拡張する方法](/posts/mcp-introduction/)
[Claude Codeの料金プラン徹底比較](/posts/pricing-guide/)

Daiki React Dev

CLAUDE.mdの書き方完全ガイド【テンプレート付き】

CLAUDE.mdとは

なぜCLAUDE.mdが重要なのか

CLAUDE.mdの読み込み優先順位

基本テンプレート

最小構成（コピペOK）

標準構成（推奨）

効果的なCLAUDE.mdの書き方

ポイント1: 短く具体的に

ポイント2: 例を添える

ポイント3: 禁止事項を明記

ポイント4: コマンドを記載

用途別テンプレート集

Reactプロジェクト用

Next.js（App Router）プロジェクト用

Node.js APIプロジェクト用

Pythonプロジェクト用

よくある間違いと対処法

間違い1: 長すぎるCLAUDE.md

間違い2: 矛盾する指示

間違い3: 曖昧な指示

間違い4: 古い情報を放置

サブディレクトリ別CLAUDE.md

ディレクトリ構造例

frontend/CLAUDE.md の例

backend/CLAUDE.md の例

CLAUDE.mdの自動生成

まとめ

CLAUDE.md設定のチェックリスト

関連記事

Discussion

Read next

Claude Code を TypeScript / Next.js プロジェクトで使う実践ガイド — 型チェック・ESLint・規約の伝え方

Claude Code を Python プロジェクトで使う実践ガイド — CLAUDE.md への test/lint 指定とフック活用

Claude Code のスラッシュコマンド入門 — 組み込みコマンドとカスタムコマンド（スキル）の作り方

CLAUDE.mdとは

なぜCLAUDE.mdが重要なのか

CLAUDE.mdの読み込み優先順位

基本テンプレート

最小構成（コピペOK）

標準構成（推奨）

効果的なCLAUDE.mdの書き方

ポイント1: 短く具体的に

ポイント2: 例を添える

ポイント3: 禁止事項を明記

ポイント4: コマンドを記載

用途別テンプレート集

Reactプロジェクト用

Next.js（App Router）プロジェクト用

Node.js APIプロジェクト用

Pythonプロジェクト用

よくある間違いと対処法

間違い1: 長すぎるCLAUDE.md

間違い2: 矛盾する指示

間違い3: 曖昧な指示

間違い4: 古い情報を放置

サブディレクトリ別CLAUDE.md

ディレクトリ構造例

frontend/CLAUDE.md の例

backend/CLAUDE.md の例

CLAUDE.mdの自動生成

まとめ

CLAUDE.md設定のチェックリスト

関連記事

Discussion

Read next

Claude Code を TypeScript / Next.js プロジェクトで使う実践ガイド — 型チェック・ESLint・規約の伝え方

Claude Code を Python プロジェクトで使う実践ガイド — CLAUDE.md への test/lint 指定とフック活用

Claude Code のスラッシュコマンド入門 — 組み込みコマンドとカスタムコマンド（スキル）の作り方

この記事を通報

パスワードをリセット