Claude Code を使っていて「毎回同じことを説明しなければならない」「コーディングスタイルがバラバラになる」と感じたことはありませんか？その悩みを解決するのが CLAUDE.md です。

CLAUDE.md はプロジェクトのルール・文脈・注意事項を書いておくと、Claude が自動で読み込んでくれる設定ファイルです。一度書けば毎回の指示が不要になり、チームで共有すれば全員が同じルールで Claude を使えます。

スポンサーリンク

目次

1. CLAUDE.mdとは何か
2. 配置場所と読み込み順序
3. CLAUDE.mdの基本構成
4. 書くべき7つのセクション
5. 良い書き方・悪い書き方
6. コピーして使えるテンプレート
7. チームで運用するコツ
8. まとめ

1. CLAUDE.mdとは何か

CLAUDE.md は、Claude Code がプロジェクトを開始するときに自動で読み込む Markdown 形式の設定ファイルです。ここに書いたことは、毎回のプロンプトで指示しなくても Claude が常に守ってくれます。

具体的には次のような情報を書きます。

• プロジェクトの技術スタック・アーキテクチャの説明
• コーディング規約・命名ルール
• よく使うコマンド（ビルド・テスト・デプロイ）
• やってはいけないこと（禁止事項）
• 外部サービスや環境変数の説明

2. 配置場所と読み込み順序

CLAUDE.md は複数の場所に置くことができ、それぞれ異なるスコープで適用されます。

3. CLAUDE.mdの基本構成

CLAUDE.md は通常の Markdown で書きます。特別な構文は不要です。見出し・箇条書き・コードブロックを使って人間が読みやすく書けば、Claude も正確に理解します。

# プロジェクト名

プロジェクトの一言説明。

## 技術スタック

- フロントエンド: Next.js 15 / TypeScript / Tailwind CSS
- バックエンド: FastAPI / Python 3.12
- データベース: PostgreSQL 16 / Redis

## よく使うコマンド

\`\`\`bash
npm run dev      # 開発サーバー起動
npm test         # テスト実行
npm run build    # ビルド
\`\`\`

## コーディング規約

- 関数名はキャメルケース（例: getUserById）
- コンポーネントはパスカルケース（例: UserCard）
- コメントは日本語で書く

## 禁止事項

- console.log をコミットしない
- any 型を使わない
- 直接 main ブランチにプッシュしない

4. 書くべき7つのセクション

# ECサイト管理システム

中小企業向けのEC運営バックオフィスシステム。
注文管理・在庫管理・顧客管理・売上分析の機能を提供する。
非エンジニアのスタッフが日常的に使うため、操作性を最優先にする。

## 技術スタック

- **フロントエンド**: Next.js 15 (App Router) / TypeScript 5 / Tailwind CSS 3
- **バックエンド**: FastAPI 0.110 / Python 3.12
- **DB**: PostgreSQL 16（主DB）/ Redis 7（キャッシュ・セッション）
- **インフラ**: AWS ECS / RDS / ElastiCache
- **テスト**: Vitest（フロント）/ pytest（バック）

## アーキテクチャの特徴

- フロントとバックは完全分離（APIで通信）
- 認証は JWT（15分有効）+ リフレッシュトークン
- ファイルアップロードは S3 に直接アップロード

## コマンド

\`\`\`bash
# 開発
npm run dev            # フロント開発サーバー（localhost:3000）
uvicorn main:app --reload  # バック開発サーバー（localhost:8000）

# テスト
npm test               # フロントテスト
pytest tests/ -v       # バックテスト
npm run test:e2e       # E2Eテスト（Playwright）

# DB
alembic upgrade head   # マイグレーション実行
alembic revision --autogenerate -m "説明"  # マイグレーション作成
\`\`\`

## コーディング規約

### 命名
- 変数・関数: キャメルケース（`getUserById`）
- クラス・コンポーネント: パスカルケース（`UserCard`）
- 定数: アッパースネーク（`MAX_RETRY_COUNT`）
- DB カラム: スネーク（`created_at`）

### TypeScript
- `any` 型は使用禁止。型がわからない場合は `unknown` を使う
- 型定義は `interface` より `type` を優先
- `null` より `undefined` を優先

### コメント
- コードの「なぜ」を書く（「何をしているか」は書かない）
- TODO コメントには必ず担当者名を入れる（`// TODO(yamada): ...`）

## ディレクトリ構成

\`\`\`
src/
├── app/          # Next.js App Router のページ
├── components/   # 再利用可能なUIコンポーネント
├── features/     # 機能単位のモジュール（orders/items/users/...）
├── hooks/        # カスタム React Hooks
├── lib/          # ユーティリティ・外部サービスクライアント
└── types/        # TypeScript 型定義
\`\`\`

## 重要ファイル

- `src/lib/api.ts` - API クライアントの設定
- `src/lib/auth.ts` - 認証ロジック
- `prisma/schema.prisma` - DB スキーマ定義
- `.env.example` - 必要な環境変数の一覧

## 禁止事項

- `console.log` をコミットしない（`logger.ts` を使う）
- `any` 型を使わない
- 直接 `main` ブランチにプッシュしない（必ずPR経由）
- 環境変数をコードにハードコーディングしない
- `npm install` で `--save-dev` を忘れない

## 注意事項

- DB マイグレーションは必ずレビューを通すこと
- 外部 API の呼び出しは `src/lib/` 以下に集約すること
- テストなしのコードはマージしないこと

## 環境変数

`.env.local` ファイルが必要（`.env.example` からコピー）。

| 変数名 | 説明 |
|--------|------|
| DATABASE_URL | PostgreSQL の接続文字列 |
| REDIS_URL | Redis の接続文字列 |
| NEXTAUTH_SECRET | NextAuth のシークレットキー |
| AWS_S3_BUCKET | ファイルアップロード先バケット名 |

## 外部サービス

- **Stripe**: 決済処理（テスト環境は `sk_test_...`）
- **SendGrid**: メール送信
- **Sentry**: エラートラッキング

5. 良い書き方・悪い書き方

具体性が命

## コーディング規約

- きれいなコードを書く
- 適切なコメントを付ける
- テストを書く

## コーディング規約

- 1関数は30行以内に収める
- 公開関数にはJSDocを必ず書く
- カバレッジ80%以上を維持する

禁止事項は断言する

## 注意

- できればanyを避ける
- なるべくテストを書いてほしい
- mainへの直接pushは
  推奨しない

## 禁止事項

- `any`型を使用しない
- テストなしのコードは
  コミットしない
- mainへの直接pushを禁止

長すぎると読まれなくなる

6. コピーして使えるテンプレート

Webアプリ開発向けテンプレート

# [プロジェクト名]

[プロジェクトの一言説明]

## 技術スタック

- フロントエンド: [Next.js/React/Vue等] / TypeScript / [CSSフレームワーク]
- バックエンド: [Express/FastAPI/Rails等]
- DB: [PostgreSQL/MySQL/MongoDB等]
- テスト: [Vitest/Jest/pytest等]

## コマンド

\`\`\`bash
[開発サーバー起動コマンド]  # [説明]
[テスト実行コマンド]        # [説明]
[ビルドコマンド]            # [説明]
\`\`\`

## コーディング規約

- 言語: [日本語/英語] でコメントを書く
- 命名: [キャメルケース/スネークケース等のルール]
- 型: [TypeScriptの型ルール]
- 関数: [関数の長さ・スタイルルール]

## ディレクトリ構成

\`\`\`
src/
├── [ディレクトリ名]/  # [説明]
├── [ディレクトリ名]/  # [説明]
└── [ディレクトリ名]/  # [説明]
\`\`\`

## 禁止事項

- [絶対にやってはいけないこと1]
- [絶対にやってはいけないこと2]
- [絶対にやってはいけないこと3]

## 注意事項

- [気をつけてほしいこと]
- [Claude に知っておいてほしいプロジェクト固有の事情]

ユーザー共通設定（~/CLAUDE.md）向けテンプレート

# 個人設定

## 言語・スタイル

- 返答は日本語で行う
- コードのコメントは日本語で書く
- 説明は箇条書きより文章を優先する

## コーディングの好み

- TypeScript を優先する
- 関数型スタイルを優先する（クラスよりも関数）
- エラーハンドリングは必ず実装する

## 作業スタイル

- 変更前に必ず現在のコードを確認する
- 大きな変更の前に計画を提示してから実行する
- テストコードも必ず一緒に書く

7. チームで運用するコツ

Git で管理してチーム全員に配布する

プロジェクトルートの CLAUDE.md は Git でコミットして管理します。チームメンバー全員が同じルールで Claude を使えるようになり、コードスタイルの統一が自然と実現します。

# 最初にCLAUDE.mdをコミット
git add CLAUDE.md
git commit -m "chore: add CLAUDE.md for Claude Code configuration"

CLAUDE.md をメンテナンスする

プロジェクトが進むと技術スタックや規約が変わります。CLAUDE.md も定期的に見直して最新の状態に保つことが重要です。「もう使っていない技術が書いてある」「コマンドが変わった」という状態になると Claude が誤った情報を参照します。

個人設定との使い分け

CLAUDE.md は一度書くだけで、以降のすべての作業がスムーズになります。まずは「毎回 Claude に説明していること」をリストアップして、それをそのまま CLAUDE.md に書き起こすところから始めてみてください。