# CLAUDE.md 設定ガイド

`CLAUDE.md` は Claude Code の**プロジェクトレベルの設定ファイル**です。Claude Code を起動するたびに、プロジェクト内の `CLAUDE.md` が自動的に読み込まれ、プロジェクトのアーキテクチャ・コーディング規約・特別な規則を把握することで、あなたのプロジェクトをより正確に理解できるようになります。

## なぜ CLAUDE.md が必要なのか

CLAUDE.md を使用しない場合、毎回の会話で次のようなことを繰り返し説明する必要があります：
- 「このプロジェクトは pnpm を使っています。npm ではありません」
- 「テストコマンドは `yarn test:unit` です。`npm test` ではありません」
- 「すべてのコンポーネントは TypeScript を使用し、any は禁止です」

これらの情報を CLAUDE.md に記述しておくと、Claude は起動後に自動的に読み込むため、毎回説明する必要がなくなります。

## ファイルの階層

Claude Code は複数の階層にある CLAUDE.md を読み込み、マージします：

| 場所 | 適用範囲 |
|------|---------|
| `~/.claude/CLAUDE.md` | グローバル設定、すべてのプロジェクトに適用 |
| `プロジェクトルート/CLAUDE.md` | プロジェクト設定、チーム共有のために Git にコミット |
| `.claude/CLAUDE.md` | プロジェクト固有の設定、`.gitignore` に追加可能 |
| サブディレクトリ内の `CLAUDE.md` | Claude がそのディレクトリにいるときのみ読み込まれる |

## クイック作成

`/init` コマンドを使用して自動生成します：

```
/init
```

Claude が現在のプロジェクト構造を分析し、プロジェクト情報を含む CLAUDE.md を自動生成します。

## 基本構造

```markdown
# プロジェクト名

## 概要
プロジェクトの目的と技術スタックを簡潔に説明する。

## 技術スタック
- ランタイム：Node.js 20
- フレームワーク：Next.js 15
- スタイリング：Tailwind CSS
- データベース：PostgreSQL + Prisma

## よく使うコマンド
- 開発サーバーの起動：`npm run dev`
- テストの実行：`npm test`
- プロダクションビルド：`npm run build`
- コードチェック：`npm run lint`

## コーディング規約
- TypeScript を使用し、`any` 型は禁止
- コンポーネントは関数型で記述する
- スタイリングは Tailwind のみ使用し、インライン style は書かない
- コミットメッセージの形式：`feat:` / `fix:` / `docs:` などのプレフィックス

## プロジェクト構造
- `src/app/` — Next.js App Router ページ
- `src/components/` — 再利用可能なコンポーネント
- `src/lib/` — ユーティリティ関数
- `prisma/` — データベーススキーマとマイグレーション

## 注意事項
- `prisma/migrations/` は変更せず、新しいマイグレーションのみ作成する
- すべての API ルートは `src/app/api/` にある
- 画像リソースは `public/images/` に配置する
```

## 実用的なヒント

### 1. パッケージマネージャーの指定

```markdown
## パッケージ管理
pnpm を使用し、npm や yarn は使わないこと。
依存関係のインストール：`pnpm install`
依存関係の追加：`pnpm add <パッケージ名>`
```

### 2. テスト規約の説明

```markdown
## テスト
- ユニットテスト：`vitest`、ファイル名は `.test.ts` で終わる
- E2E テスト：`playwright`、`tests/e2e/` に配置
- ユニットテストの実行：`pnpm test:unit`
- E2E の実行：`pnpm test:e2e`
- 新機能にはテストを必ず含める
```

### 3. 禁止操作の通知

```markdown
## 禁止操作
- `console.log` を使わず、プロジェクトの `logger` モジュールを使用する
- `package-lock.json` を直接変更しない
- `main` ブランチに直接コミットせず、フィーチャーブランチを使用する
```

### 4. アーキテクチャの背景を提供する

```markdown
## アーキテクチャの説明
このプロジェクトはヘキサゴナルアーキテクチャ（Hexagonal Architecture）を採用しています：
- `domain/` — ビジネスロジック、外部フレームワークに依存しない
- `application/` — ユースケース、domain と infrastructure を調整する
- `infrastructure/` — データベース・HTTP などの外部アダプター
- `interfaces/` — Web コントローラー・CLI などのエントリーポイント
新機能はこの階層構造に従い、domain 層に外部依存を持ち込まないこと。
```

### 5. 他のドキュメントを参照する

```markdown
## 詳細情報
- API ドキュメント：`docs/api.md`
- デプロイ手順：`docs/deploy.md`
- データベーススキーマ：`prisma/schema.prisma`
```

## チーム運用のベストプラクティス

### Git の管理方針

```
CLAUDE.md          → Git にコミット（チームで共有）
.claude/CLAUDE.md  → .gitignore に追加（個人設定）
```

`.gitignore` に次を追加します：

```gitignore
# 個人用の Claude Code 設定
.claude/CLAUDE.md
.claude/settings.local.json
```

### コードレビューのチェック項目

PR レビューのたびに確認します：
- 技術スタックを追加したとき、CLAUDE.md も更新したか？
- プロジェクト構成を変えたとき、「プロジェクト構成」の節を更新したか？
- 重要なコマンドを追加したとき、「コマンド」の節を更新したか？

### オンボーディング用ドキュメントとして

CLAUDE.md はプロジェクトの入門ドキュメントとしても最適です：
1. clone した新メンバーはまず CLAUDE.md を読んで全体像をつかむ
2. `claude` を起動する → Claude はすでにプロジェクトの規約をすべて知っている
3. `> このプロジェクトを理解したい` から探索を始める

---

## 高度なテクニック

### インライン展開せず参照する

CLAUDE.md は長くしすぎないほうがよいです。詳細なドキュメントは中身を書かず、パスを参照します：

```markdown
## アーキテクチャ
詳細なアーキテクチャ資料：`docs/architecture.md`
API 設計規約：`docs/api-design.md`
データベーススキーマ：`prisma/schema.prisma`
```

Claude は必要になった時点でこれらのファイルを自動的に読みます。

### AGENTS.md との関係

| | CLAUDE.md | AGENTS.md |
|---|---|---|
| ツール | Claude Code | Codex CLI |
| 形式 | Markdown | Markdown |
| 内容 | 80% 以上を流用できる | 80% 以上を流用できる |

Claude Code と Codex を併用する場合、2 つのファイルは共存できます：
- **共通の内容**：技術スタック、コマンド、コーディング規約、プロジェクト構成
- **ツール固有**：Claude の `/model` や `/plan` の指示は CLAUDE.md に、Codex の approval mode の設定は AGENTS.md に

> 詳しくは [AGENTS.md 設定ガイド](/docs/usage/agents-md)。

### コンテキスト消費を抑える

CLAUDE.md の内容は常にコンテキストに残ります（`/compact` でも消えません）。おすすめは：

- **全体を 500 行以内に収める**
- 詳細なドキュメントはインラインにせずパス参照にする
- 頻繁に変わる情報（進捗など）は書かない
- コード例は書かない（Claude はソースを自分で読める）

---

## よくある失敗とデバッグ

### CLAUDE.md が読み込まれない

```bash
# ファイルがプロジェクトルートにあるか確認
ls -la CLAUDE.md

# Claude が認識しているか確認
claude
> CLAUDE.md は見えていますか？どんな技術スタックが書かれていますか？
```

### 長すぎてコンテキストが足りなくなる

```bash
# 行数を確認
wc -l CLAUDE.md
# 500 行を超えていたら整理する

# コンテキストの使用量を確認
/cost
```

### チームメンバーで挙動が食い違う

各自のグローバル設定 `~/.claude/CLAUDE.md` は人によって異なります。チームの挙動が揃わないときは確認します：
1. プロジェクトルートの CLAUDE.md は十分に具体的か？
2. 誰かが `.claude/CLAUDE.md` でチームのルールを上書きしていないか？

---

## CLAUDE.md とコンテキスト管理

CLAUDE.md の内容はコンテキストスペースを消費します。以下を推奨します：
- CLAUDE.md を簡潔に保ち、最も重要な情報に集中する
- 詳細なアーキテクチャドキュメントについては、内容を直接コピーするのではなく、CLAUDE.md にパス参照を記述する
- 長いセッションでも、CLAUDE.md は常に可視状態を保つ（`/compact` で削除されない）

## プロジェクトテンプレート

以下は、よくあるプロジェクトタイプ向けに実戦で磨かれた CLAUDE.md の出発点です。自分のスタックに合うものをコピーし、詳細を調整してください。

### テンプレート 1：React + TypeScript フロントエンド

```markdown
# MyApp Frontend

## 技術スタック
- React 19 + TypeScript 5.x
- ビルドツール：Vite 6
- スタイリング：Tailwind CSS v4（utility-first、インライン style は書かない）
- 状態管理：Zustand（グローバル）、TanStack Query（サーバー状態）
- ルーティング：React Router v7
- テスト：Vitest + Testing Library + MSW

## コマンド
- 開発：`pnpm dev`（ポート 3000）
- テスト：`pnpm test`（Vitest watch モード）
- 単発テスト：`pnpm test:run`
- ビルド：`pnpm build`
- Lint：`pnpm lint`（ESLint + Prettier）
- 型チェック：`pnpm typecheck`

## コーディング規約
- コンポーネント：関数コンポーネント + Hooks、class コンポーネントは禁止
- Props：`interface` で定義する（`type` は使わない）
- ファイル名：コンポーネントは PascalCase（UserProfile.tsx）、ユーティリティは camelCase（formatDate.ts）
- インポート順：React → サードパーティ → プロジェクト内部 → スタイル
- `any` 型は禁止、明示的な型注釈を必須とする
- 非同期処理は TanStack Query に統一し、`useEffect` + `fetch` を直接書かない

## プロジェクト構造
- src/components/ — 再利用可能な UI コンポーネント
- src/pages/ — ルートページ
- src/hooks/ — カスタム Hooks
- src/api/ — API リクエストのラッパー（TanStack Query の queryFn）
- src/stores/ — Zustand stores
- src/lib/ — ユーティリティ関数
- src/types/ — グローバル型定義

## 注意事項
- パッケージマネージャー：pnpm（npm や yarn ではない）
- Node.js 22+
- すべての API リクエストは src/api/client.ts を経由する（インターセプター付き）
- 画像は public/images/ に置き、/images/ パスで参照する
```

### テンプレート 2：Python + FastAPI バックエンド

```markdown
# MyApp Backend

## 技術スタック
- Python 3.12 + FastAPI
- ORM：SQLAlchemy 2.0（async）+ Alembic マイグレーション
- データベース：PostgreSQL 16
- キャッシュ：Redis 7
- テスト：pytest + httpx + factory_boy

## コマンド
- 開発：`uvicorn app.main:app --reload --port 8000`
- テスト：`pytest -xvs`
- マイグレーション：`alembic upgrade head`
- 新規マイグレーション：`alembic revision --autogenerate -m "説明"`
- Lint：`ruff check .`
- フォーマット：`ruff format .`
- 型チェック：`mypy app/`

## コーディング規約
- 型注釈：すべての関数の引数と戻り値に型ヒントを付ける
- async/await：すべての I/O 操作は async を使用する
- Pydantic v2：リクエスト／レスポンスの schema は Pydantic BaseModel に統一する
- 依存性注入：データベース接続・認証などは FastAPI Depends() で注入する
- エラー処理：業務例外は app.exceptions.AppError を継承する

## プロジェクト構造
- app/main.py — アプリケーションのエントリーポイント
- app/api/ — ルート（リソースごとにファイル分割）
- app/models/ — SQLAlchemy モデル
- app/schemas/ — Pydantic schemas
- app/services/ — ビジネスロジック
- app/core/ — 設定・データベース・セキュリティなどのコアモジュール
- tests/ — テストファイル（app/ の構造をミラーする）
- alembic/ — データベースマイグレーション

## 注意事項
- alembic/versions/ にある既存のマイグレーションファイルは変更しない
- .env ファイルは Git にコミットせず、app/core/config.py の Settings クラスで読み込む
- 仮想環境：`python -m venv venv && source venv/bin/activate`
```

### テンプレート 3：Go マイクロサービス

```markdown
# MyService

## 技術スタック
- Go 1.23
- HTTP フレームワーク：Echo v4
- データベース：PostgreSQL + sqlc（型安全な SQL）
- メッセージキュー：NATS JetStream
- コンテナ化：Docker + docker-compose

## コマンド
- 実行：`go run ./cmd/server`
- テスト：`go test ./...`
- ビルド：`go build -o bin/server ./cmd/server`
- sqlc 生成：`sqlc generate`
- Lint：`golangci-lint run`

## コーディング規約
- エラー処理：必ず err をチェックし、_ で無視しない
- インターフェース命名：単一メソッドのインターフェースには -er 接尾辞を付ける（Reader, Writer）
- パッケージ命名：小文字の単語、アンダースコアは使わない
- ロギング：slog による構造化ログを使用する
- コンテキスト：すべての関数の第一引数に context.Context を渡す

## プロジェクト構造（標準 Go レイアウト）
- cmd/server/ — メインプログラムのエントリーポイント
- internal/handler/ — HTTP handler
- internal/service/ — ビジネスロジック
- internal/repository/ — データアクセス層
- internal/model/ — データモデル
- sql/ — SQL クエリファイル（sqlc が使用）
```

### テンプレート 4：Monorepo（Turborepo）

```markdown
# MyPlatform Monorepo

## 技術スタック
- パッケージ管理：pnpm workspace
- ビルドシステム：Turborepo
- 言語：TypeScript でフルスタック

## コマンド
- 全体の開発：`pnpm dev`
- 全体のテスト：`pnpm test`
- 全体のビルド：`pnpm build`
- 単一パッケージの開発：`pnpm --filter @myplatform/web dev`
- 依存関係の追加：`pnpm --filter @myplatform/api add express`

## パッケージ構造
- apps/web/ — Next.js フロントエンド
- apps/api/ — Express バックエンド
- apps/admin/ — 管理ダッシュボード
- packages/ui/ — 共有 UI コンポーネントライブラリ
- packages/config/ — 共有設定（eslint, tsconfig）
- packages/types/ — 共有型定義

## 注意事項
- 共有コードは packages/ に置き、apps 同士で直接参照しない
- 新しいパッケージを作成する際は packages/ui/package.json の形式を参考にする
- Turborepo キャッシュ：ビルド成果物は node_modules/.cache/turbo にキャッシュされる
```

### テンプレート 5：データサイエンス / ML プロジェクト

```markdown
# ML Pipeline

## 技術スタック
- Python 3.12
- フレームワーク：PyTorch 2.5 + Lightning
- データ処理：Polars（Pandas は使わない）
- 実験トラッキング：MLflow
- 依存管理：uv

## コマンド
- 訓練：`python -m src.train --config configs/experiment.yaml`
- 評価：`python -m src.evaluate --checkpoint runs/latest`
- データ前処理：`python -m src.preprocess --data-dir data/raw`
- Jupyter：`jupyter lab`
- テスト：`pytest tests/`

## コーディング規約
- 設定は YAML を使う（ハイパーパラメータをハードコードしない）
- データ処理は Polars を使う（Pandas より速く、型安全）
- すべての実験は MLflow に記録する
- Notebook は探索専用、プロダクションコードは必ず src/ に置く

## プロジェクト構造
- configs/ — 実験設定 YAML
- data/raw/ — 生データ（Git にコミットせず、DVC で管理）
- data/processed/ — 処理済みデータ
- src/ — コアコード（model, data, train, evaluate）
- notebooks/ — 探索的分析
- runs/ — 訓練の出力（checkpoints, logs）
```

## CLAUDE.md と AGENTS.md の選び方

Claude Code は `CLAUDE.md` をネイティブに読み込みます（メモリファイルやパススコープのルールも含む）。一方で、**それ以外**のほとんどのツール — Cursor、Codex、GitHub Copilot、Cline、Gemini / Antigravity、Aider、Zed など — は `AGENTS.md` を読み込みます。どちらのファイルを管理すべきかは、チームが使うツールの数によって決まります。

| シナリオ | 推奨 |
|----------|------|
| **単一ツール（Claude Code のみ）** | `CLAUDE.md` だけで十分 — AGENTS.md は不要 |
| **複数ツールのチーム** | `AGENTS.md` を共有の信頼できる情報源とし、それをインポートする薄い `CLAUDE.md` を併用する |

### 単一ツール：CLAUDE.md だけ

チーム全員が Claude Code を使っているなら、すべてを `CLAUDE.md` に書きます。2 つ目のファイルを用意するメリットはありません。

### 複数ツール：AGENTS.md を信頼できる情報源にする

Claude Code と Cursor・Codex・Copilot などを併用しているチームでは、共有ルール（技術スタック・コマンド・コーディング規約・プロジェクト構造）を `AGENTS.md` に置き、`CLAUDE.md` はそれをインポートして Claude 固有の追加分だけを書いた薄いファイルにします：

```markdown
# プロジェクトルール

@AGENTS.md

## Claude Code 固有
- 大規模リファクタリングでは /model で Opus 4.8 に切り替える
- docs/architecture.md は貼り付けず、パスで参照する
```

`@AGENTS.md` の行が共有内容を Claude Code のコンテキストに取り込むため、Claude はチームのルール **と** Claude 固有の追加分の両方を得られます。同じルールについて **2 つの食い違うコピーを保守することは避けてください** — 2 つのファイルは必ず時間とともにズレていくため、これが最大の落とし穴です。

> AGENTS.md の形式とそのツールチェーンの詳細は [AGENTS.md 設定ガイド](/docs/usage/agents-md) を参照してください。

## 次のステップ

- [コンテキスト管理](/docs/usage/context-management) を学ぶ — コンテキストウィンドウの管理テクニックを習得する
- [権限の設定](/docs/usage/permissions) を学ぶ — Claude が実行できる操作を制御する
- [ワークフローのヒント](/docs/usage/workflow-tips) を学ぶ — 効率的な Claude Code ワークフローを構築する