💻 Claude Code入門 📖 約20分で読めます

CLAUDE.mdの書き方完全ガイド ― プロジェクト指示書のベストプラクティス

プロジェクトの文脈をAIに正確に伝える設定ファイルの書き方

クロガイド｜Claude＆Claude Codeを無料で学ぼう

AI基礎からプロンプト術、Claude Codeの使い方まで。知識レッスンとクイズ式トレーニングで、AIスキルを段階的にアップ。ユーザー登録不要、すべて無料で今すぐ始められます。

CLAUDE.mdとは何か ― プロジェクトの「取扱説明書」

CLAUDE.mdは、Claude Codeがリポジトリで作業する際に最初に読み込むプロジェクト指示書です。人間の開発者に「このプロジェクトのREADMEを読んでおいて」と言うように、AIにプロジェクトの全体像・ルール・慣習を伝えるためのファイルです。

このファイルが適切に書かれていれば、Claude Codeは文脈を理解した上でコードを生成・修正でき、作業精度が飛躍的に向上します。逆に、CLAUDE.mdがなければ毎回同じ説明を繰り返す必要があり、非効率です。

CLAUDE.mdが解決する3つの問題

文脈の喪失: 新しい会話のたびにプロジェクト情報を説明し直す手間がなくなる
一貫性の欠如: コーディング規約やプロジェクトルールを毎回守らせる必要がなくなる
非効率な試行錯誤: 技術スタックや構成を理解した上で最適な提案をしてくれる

CLAUDE.mdに書くべき項目 ― 7つの必須セクション

効果的なCLAUDE.mdには、以下の7つのセクションを含めることを推奨します。すべてが必須ではありませんが、含めるほどClaude Codeの理解精度が上がります。

セクション	内容	重要度
プロジェクト概要	何を作っているか、目的は何か	★★★
技術スタック	使用言語・フレームワーク・DB等	★★★
ファイル構成	ディレクトリ構造の説明	★★★
コーディング規約	命名規則・フォーマット・スタイル	★★☆
ビルド・テストコマンド	開発・テスト・デプロイ手順	★★☆
データベーススキーマ	テーブル定義・リレーション	★★☆
デプロイ・運用	本番環境・CI/CD・注意事項	★☆☆

セクション別の書き方詳細

1. プロジェクト概要

プロジェクトが何であるか、誰のためのものか、主要な機能は何かを簡潔に記述します。

良い例

# プロジェクト概要
**TaskFlow** - 中小企業向けタスク管理SaaS
- マルチテナント対応のタスク管理ツール
- チーム単位でプロジェクト・タスクを管理
- カンバンボードとガントチャートの2種類の表示
- Slack/Teams連携による通知機能

悪い例

# 概要
Webアプリです。

→ 情報が少なすぎてClaude Codeが適切な判断を下せません。

2. 技術スタック

バージョン情報も含めて具体的に記述します。Claude Codeはバージョンに応じて適切なAPI・構文を選択します。

## 技術スタック
- **言語**: TypeScript 5.3
- **フロントエンド**: React 18 + Next.js 14 (App Router)
- **状態管理**: Zustand 4.x
- **スタイリング**: Tailwind CSS 3.4
- **バックエンド**: Next.js API Routes
- **DB**: PostgreSQL 16 + Prisma ORM 5.x
- **認証**: NextAuth.js v5
- **テスト**: Vitest + React Testing Library
- **CI/CD**: GitHub Actions
- **ホスティング**: Vercel

3. ファイル構成

主要なディレクトリとファイルの役割を説明します。ツリー構造で視覚的に示すと効果的です。

## プロジェクト構成
```
src/
├── app/                    # Next.js App Router
│   ├── (auth)/            # 認証関連ページ
│   ├── (dashboard)/       # ダッシュボード
│   ├── api/               # APIルート
│   └── layout.tsx         # ルートレイアウト
├── components/
│   ├── ui/                # 再利用可能なUIコンポーネント
│   └── features/          # 機能固有コンポーネント
├── lib/                   # ユーティリティ・設定
├── prisma/                # スキーマ・マイグレーション
└── tests/                 # テストファイル
```

4. コーディング規約

プロジェクト固有のルールを明記します。Claude Codeはこれらを遵守してコードを生成します。

## コーディング規約
- コンポーネントは関数コンポーネント+hooksのみ（クラスコンポーネント禁止）
- 型定義は `types/` ディレクトリにまとめる
- APIレスポンスは必ず `ApiResponse<T>` 型でラップ
- エラーハンドリングは `AppError` クラスを使用
- コミットメッセージはConventional Commits形式
- 日本語コメントOK、変数名・関数名は英語

5. ビルド・テストコマンド

## 開発コマンド
- `npm run dev` — 開発サーバー起動（port 3000）
- `npm run build` — プロダクションビルド
- `npm run test` — テスト実行
- `npm run test:watch` — テストウォッチモード
- `npm run lint` — ESLint実行
- `npm run db:migrate` — DBマイグレーション
- `npm run db:seed` — シードデータ投入

プロジェクト別CLAUDE.mdの実例

実例1: Webアプリケーション

# CLAUDE.md

## プロジェクト概要
**ShopManager** - ECサイト管理ダッシュボード
- Shopify APIと連携した注文・在庫管理システム
- 管理者向けダッシュボード

## 技術スタック
- React 18 + TypeScript
- Vite 5 でビルド
- TanStack Query v5 でAPI状態管理
- Express.js バックエンド
- MongoDB + Mongoose

## 重要な注意点
- APIキーは `.env` に格納（コミット禁止）
- Shopify APIのレートリミット: 2req/sec
- 日本語ロケール前提の日時フォーマット

実例2: APIサーバー

# CLAUDE.md

## プロジェクト概要
**PaymentGateway** - 決済処理マイクロサービス
- Stripe/PayPay/LINE Pay対応
- REST API + WebSocket通知

## 技術スタック
- Python 3.12 + FastAPI
- SQLAlchemy 2.0 + Alembic
- Redis（キャッシュ・セッション）
- Docker Compose で開発環境構築

## セキュリティ要件
- すべてのエンドポイントにJWT認証必須
- 金額計算はDecimal型を使用（float禁止）
- PCI DSS準拠: カード情報は保持しない

実例3: ライブラリ・パッケージ

# CLAUDE.md

## プロジェクト概要
**date-jp** - 日本語日付処理ライブラリ
- 和暦⇔西暦変換
- 祝日判定（振替休日対応）
- npm公開パッケージ

## 開発方針
- Tree-shakingに対応するため、各関数を個別エクスポート
- IE11非対応（ES2020以上）
- 100%テストカバレッジを維持
- JSDocでの型注釈必須