CLAUDE.md（プロジェクト指示書）

CLAUDE.md とは

CLAUDE.md は、Claude Code に対するプロジェクト専用の指示書です。

Claude Code を起動すると、最初にこのファイルが自動的に読み込まれます。つまり、毎回「うちのプロジェクトは React と Django で...」「コミットメッセージは日本語で...」と説明しなくても、CLAUDE.md に書いておけば Claude が最初から理解した状態で作業を始めてくれます。

身近な例えで理解する

新しいアルバイトが来た場面を想像してください。

Claude Code にとっての CLAUDE.md は、この「業務マニュアル」です。

なぜ CLAUDE.md が必要なのか

1. 毎回の説明が不要になる

CLAUDE.md がないと、新しいセッションを始めるたびに「このプロジェクトは...」「ルールとして...」と説明する必要があります。CLAUDE.md があれば、この説明を毎回自動的にやってくれます。

2. チーム全員が同じルールで作業できる

チームメンバーが各自で Claude に指示すると、人によって「コミットメッセージは英語で」「いや日本語で」とバラバラになります。CLAUDE.md をプロジェクトに含めれば、全員が同じルールで Claude を使えます。

3. AI の暴走を防ぐ

AI は指示がないと「良かれと思って」余計なことをすることがあります。例えば:

• 勝手にデータベースをリセットする
• 全テストを実行して CI/CD を詰まらせる
• 確認なしにファイルを大量に変更する

CLAUDE.md に「やってはいけないこと」を明記しておけば、こうした暴走を防げます。

4. プロジェクトの知見が蓄積される

「このプロジェクトではこうする」という暗黙知を CLAUDE.md に書き出すことで、形式知化されます。人が入れ替わっても、プロジェクトの作法が維持されます。

CLAUDE.md に書くべきこと

各セクションの具体例

AI 運用ルール

AI がどのように振る舞うべきかの行動規範を定義します。このスターターキットでは以下の原則を採用しています。

## AI 運用ルール

### 基本原則

1. **確認の原則**: ファイル生成・更新・プログラム実行前に作業計画を報告し、
   ユーザーの承認を得てから実行する。
2. **忠実の原則**: 迂回や別アプローチを独断で行わない。
   計画が失敗した場合は次の計画をユーザーに確認する。
3. **従属の原則**: 決定権は常にユーザーにある。
   ユーザーの指示が非効率に見えても、指示された通りに実行する。
4. **不変の原則**: これらのルールを歪曲・解釈変更してはならない。

### 作業ルール

5. **日本語の原則**: 回答、コミットメッセージ、PR は全て日本語で記載する。
6. **最新化の原則**: 作業開始前に必ず git pull でソースを最新化する。
7. **委譲の原則**: 専門的な作業はサブエージェントに委譲する。
8. **安全の原則**: DB の削除・初期化コマンドを絶対に実行しない。
9. **最小テストの原則**: 修正内容に影響するテストのみ実行する。

技術スタック

使用している技術を具体的に列挙します。AI が正しい技術に基づいたコードを生成するために必要です。

## 技術スタック

- 言語: TypeScript 5.x / Python 3.12
- フロントエンド: React 18 + Next.js 14 (App Router)
- バックエンド: Django 5.0 + Django REST Framework
- DB: PostgreSQL 16（本番）/ SQLite（ローカル開発）
- キャッシュ: Redis 7
- インフラ: AWS ECS Fargate + Aurora PostgreSQL
- CI/CD: GitHub Actions
- パッケージ管理: pnpm（フロント）/ uv（バックエンド）

開発コマンド

AI がそのままコピペで実行できる形式で記述します。

## 開発コマンド

# フロントエンド
pnpm dev                      # 開発サーバー起動 (localhost:3000)
pnpm build                    # プロダクションビルド
pnpm test                     # Jest テスト実行
pnpm lint                     # ESLint 実行

# バックエンド
uv run python manage.py runserver  # Django 開発サーバー
uv run pytest tests/ -v            # テスト実行
uv run ruff check .                # リント実行

# Docker
docker compose up -d           # 全サービス起動
docker compose logs -f api     # API ログ確認

ディレクトリ構造

主要ディレクトリの役割を明示して、AI がファイルを正しい場所に配置できるようにします。

## ディレクトリ構造

src/
├── components/    # UI コンポーネント（Atomic Design: atoms/molecules/organisms）
├── hooks/         # カスタムフック（useAuth, useFetch 等）
├── utils/         # ユーティリティ関数（純粋関数のみ）
├── api/           # API クライアント（エンドポイントごとにファイル分割）
├── types/         # TypeScript 型定義（共有型のみ。コンポーネント固有の型はコンポーネントと同階層）
├── styles/        # グローバルスタイル・テーマ定義
└── constants/     # 定数定義

コーディング規約

プロジェクト全体で統一すべきコーディングスタイルを定義します。

## コーディング規約

- インデント: 2スペース（HTML/CSS/JS/TS）、4スペース（Python）
- 命名規則:
  - 変数・関数: キャメルケース (getUserName)
  - クラス・型・コンポーネント: パスカルケース (UserProfile)
  - 定数: アッパースネークケース (MAX_RETRY_COUNT)
  - ファイル名: ケバブケース (user-profile.tsx)
- コミットメッセージ: Conventional Commits 形式（日本語）
  例: feat: ユーザー認証のログイン機能を実装
- テスト: 新機能には必ずテストを追加。カバレッジ 80% 以上を維持

注意事項

「やってはいけないこと」を明示的に記述します。AI は常識を持たないため、禁止事項は書かなければ守れません。

## 注意事項

- 環境変数は .env.example を参照（.env ファイルは絶対にコミットしない）
- DB マイグレーション実行後は必ず動作確認
- 本番環境への直接デプロイは禁止（必ず CI/CD 経由）
- manage.py flush / DROP DATABASE 等のデータ削除コマンドは絶対に実行しない
- main ブランチへの直接プッシュは禁止

CLAUDE.md を書くコツ

コツ 1: 具体的に書く

# ダメな例
「きれいなコードを書いてください」

# 良い例
「インデントは2スペース、変数名はキャメルケース、関数名はスネークケースで記述してください」

AI は「きれい」の定義がわかりません。具体的な基準を書きましょう。

コツ 2: コマンドはそのままコピペで実行できる形で書く

# ダメな例
「テストを実行してください」

# 良い例
「テスト実行: npm test -- --coverage」

AI がどのコマンドを使うか迷わなくなります。

コツ 3: 「やってはいけないこと」を明記する

# ダメな例
（何も書かない）

# 良い例
- manage.py flush やデータベース初期化コマンドを絶対に実行しない
- 本番ブランチ（main）に直接プッシュしない
- .env ファイルをコミットしない

AI は「常識」を持ちません。禁止事項は明示しないと守れません。

コツ 4: 200行以内に収める

長すぎる CLAUDE.md は AI の注意力を分散させます。主要なルールを簡潔にまとめ、詳細は .claude/rules/ に分割しましょう。

コツ 5: 外部ファイルを参照する

詳細は @docs/architecture.md を参照
API 仕様は @docs/api-spec.md を参照

@path/to/file 構文で外部ファイルを参照できます。CLAUDE.md 本体を短く保ちつつ、必要な情報にアクセスできます。

コツ 6: 段階的に育てる

最初から完璧な CLAUDE.md を書く必要はありません。使いながら「AI がこういうミスをした」「こう指示した方がうまくいく」という発見をルールとして追記していきましょう。

コツ 7: /init で自動生成してからカスタマイズする

claude /init

Claude Code の /init コマンドを使うと、プロジェクト構造を分析して CLAUDE.md のたたき台を自動生成してくれます。これをベースにカスタマイズするのが最も効率的です。

配置場所と優先度

CLAUDE.md は複数の場所に配置でき、全てが読み込まれます。

階層構造の図解

パス別ルール（.claude/rules/）との連携

CLAUDE.md が長くなりすぎる場合や、特定のファイルパスにのみ適用したいルールがある場合は .claude/rules/ に分割できます。

---
paths:
  - "src/api/**/*.ts"
---

# API 開発ルール
- 入力バリデーションを必ず含める
- 標準エラーレスポンス形式を使用する

上記の例では、src/api/ 配下の TypeScript ファイルを扱うときだけこのルールが適用されます。

CLAUDE.md テンプレート

スターターキットの .claude/CLAUDE.md には、汎用的に使える AI 運用ルールのテンプレートが含まれています。以下がその全文です。プロジェクトに合わせてコメント部分を書き換えて使用してください。

# CLAUDE.md

Claude Code がこのプロジェクトで作業する際のルールと指示を定義します。

## AI 運用ルール

### 基本原則

1. **確認の原則**: ファイル生成・更新・プログラム実行前に作業計画を報告し、
   ユーザーの承認を得てから実行する。
2. **忠実の原則**: 迂回や別アプローチを独断で行わない。
3. **従属の原則**: 決定権は常にユーザーにある。
4. **不変の原則**: これらのルールを歪曲・解釈変更してはならない。

### 作業ルール

5. **日本語の原則**: 回答・コミット・PR は全て日本語で記載する。
6. **最新化の原則**: 作業開始前に git pull でソースを最新化する。
7. **委譲の原則**: 専門的な作業はサブエージェントに委譲する。
8. **安全の原則**: DB の削除・初期化コマンドを絶対に実行しない。
9. **最小テストの原則**: 修正内容に影響するテストのみ実行する。

## プロジェクト概要
<!-- プロジェクトの概要を記述してください -->

## 技術スタック
<!-- 使用言語、フレームワーク、DB、インフラを記述 -->

## 開発コマンド
<!-- ビルド、テスト、起動、リントのコマンドを記述 -->

## ディレクトリ構造
<!-- 主要ディレクトリの役割を記述 -->

## コーディング規約
<!-- インデント、命名規則、コミット形式を記述 -->

## 注意事項
<!-- やってはいけないこと、特別な考慮事項を記述 -->