プロジェクトに合ったCLAUDE.mdテンプレート

はじめに

CLAUDE.mdは、Claude Codeがセッション開始時に読み込む「プロジェクトの取扱説明書」です。ここに書いた内容をもとに、Claude Codeはプロジェクトの規約やワークフローを理解して作業を進めます。

ただ、いざ書こうとすると「何を書けばいいのか」「どこまで詳しく書くべきか」と悩みがちです。このレシピでは、プロジェクトの種類ごとにコピペして使えるテンプレートを3種類用意しました。そのまま使ってもいいですし、自分のプロジェクトに合わせてカスタマイズしてください。

まず /init を試そう

Claude Codeで /init を実行すると、コードベースを分析してCLAUDE.mdを自動生成してくれます。自動生成された内容をベースに、このテンプレートで足りない部分を補うのがおすすめです。

CLAUDE.mdの構成要素

テンプレートに入る前に、CLAUDE.mdに書く内容の優先度を整理しておきましょう。

優先度	セクション	内容
必須	ビルド・テストコマンド	Claude Codeが推測できないプロジェクト固有のコマンド
必須	コーディング規約	デフォルトと異なるスタイルルール
推奨	プロジェクト構成	ディレクトリ構造と各ディレクトリの役割
推奨	禁止事項	セキュリティ上やってはいけないこと
オプション	ワークフロー	ブランチ戦略やPRの出し方
オプション	アーキテクチャ判断	採用した技術選定の理由

書きすぎに注意

CLAUDE.mdは200行以下を目標にしましょう。長すぎるとコンテキストを圧迫し、重要な指示が埋もれてしまいます。「この指示を削除したらClaude Codeが間違いを犯すか？」を基準に取捨選択してください。

手順

プロジェクトの種類に合ったテンプレートを選ぶ

以下の3つから、自分のプロジェクトに最も近いテンプレートを選んでください。

テンプレート1: Next.js / Reactフロントエンドプロジェクト
テンプレート2: Python / FastAPIバックエンドプロジェクト
テンプレート3: モノレポ（Turborepo等）

テンプレートの詳細は次のセクションで紹介します。

テンプレートをコピーしてCLAUDE.mdを作成する

プロジェクトのルートディレクトリに CLAUDE.md を作成し、テンプレートの内容をコピーします。

touch CLAUDE.md

または .claude/CLAUDE.md に配置することもできます。どちらでもClaude Codeは自動的に読み込みます。

プロジェクトに合わせてカスタマイズする

テンプレートの各セクションを、実際のプロジェクトの情報に書き換えましょう。特にビルド・テストコマンドは正確に記載することが重要です。

動作を確認する

Claude Codeを起動して /memory コマンドを実行し、CLAUDE.mdが正しく読み込まれているか確認します。

/memory

読み込まれたファイルの一覧にCLAUDE.mdが表示されていれば成功です。

テンプレート1: Next.js / Reactフロントエンド

# CLAUDE.md
 
## プロジェクト概要
Next.js（App Router）を使ったWebアプリケーション。
TypeScript + Tailwind CSS + shadcn/ui で構築。
 
## コマンド
- `npm run dev` - 開発サーバー起動（http://localhost:3000）
- `npm run build` - プロダクションビルド
- `npm run lint` - ESLint実行
- `npm run test` - Vitest実行
- `npm run test -- --run src/path/to/file.test.ts` - 単一テスト実行
 
## ディレクトリ構成
- `src/app/` - App Routerのルーティング
- `src/components/` - UIコンポーネント（Atomic Design）
  - `ui/` - shadcn/uiベースの汎用コンポーネント
  - `features/` - 機能固有のコンポーネント
- `src/lib/` - ユーティリティ関数・API クライアント
- `src/hooks/` - カスタムフック
- `src/types/` - 型定義
 
## コーディング規約
- コンポーネントは関数コンポーネント + アロー関数で記述
- スタイリングはTailwind CSSのユーティリティクラスを使用
- import文はESModules構文（import/export）を使用
- 型定義でanyを使わない（やむを得ない場合は理由をコメントで明記）
- サーバーコンポーネントとクライアントコンポーネントを明確に分離
 
## テスト方針
- コンポーネントテストはVitest + Testing Library
- テストファイルは対象ファイルと同じディレクトリに `.test.tsx` で配置
- テスト名は日本語で「〜の場合、〜する」の形式
 
## 禁止事項
- `console.log` をコミットしない（デバッグ用は `console.debug` を使用）
- インラインスタイルを使わない
- API キーやシークレットをソースコードに含めない
- `next/image` を使わず `<img>` タグを直接使用しない

テンプレート2: Python / FastAPIバックエンド

# CLAUDE.md
 
## プロジェクト概要
FastAPIで構築したREST APIサーバー。
Python 3.12 + SQLAlchemy + Alembic + PostgreSQL。
 
## コマンド
- `uv run fastapi dev` - 開発サーバー起動
- `uv run pytest` - テスト全体実行
- `uv run pytest tests/path/to/test_file.py -v` - 単一テスト実行
- `uv run ruff check .` - リンター実行
- `uv run ruff format .` - フォーマッター実行
- `uv run alembic upgrade head` - マイグレーション適用
- `uv run alembic revision --autogenerate -m "説明"` - マイグレーション作成
 
## ディレクトリ構成
- `src/app/` - FastAPIアプリケーション本体
  - `api/` - エンドポイント定義（ルーター）
  - `models/` - SQLAlchemyモデル
  - `schemas/` - Pydanticスキーマ（リクエスト/レスポンス）
  - `services/` - ビジネスロジック
  - `repositories/` - データアクセス層
- `tests/` - テストコード（srcと同じ構造をミラー）
- `alembic/` - マイグレーションファイル
 
## コーディング規約
- 変数名・関数名はsnake_case、クラス名はPascalCase
- 型ヒントを必ず付ける（引数・戻り値ともに）
- 外部APIやDB操作には必ずtry-exceptを入れる
- エラーレスポンスはRFC 7807準拠のフォーマットで返す
- 環境変数はpydantic-settingsで管理し、直接os.getenvを使わない
 
## テスト方針
- テストフレームワークはpytest
- DBを使うテストはテスト用のトランザクションでラップしてロールバック
- 外部APIはrespxでモック
- テスト名は `test_対象_条件_期待結果` の形式
 
## 禁止事項
- 本番DBへの直接接続・操作
- パスワード・トークンをログに出力
- SQLの文字列結合（SQLインジェクション防止）
- `from xxx import *` の使用

テンプレート3: モノレポ（Turborepo）

# CLAUDE.md
 
## プロジェクト概要
Turborepoで管理するモノレポ。
フロントエンド（Next.js）+ バックエンド（Node.js）+ 共有パッケージ。
 
## コマンド
- `pnpm install` - 依存関係インストール
- `pnpm dev` - 全パッケージの開発サーバー起動
- `pnpm build` - 全パッケージのビルド
- `pnpm lint` - 全パッケージのリント
- `pnpm test` - 全パッケージのテスト
- `pnpm --filter @myapp/web dev` - 特定パッケージのみ起動
- `pnpm --filter @myapp/api test` - 特定パッケージのみテスト
 
## ディレクトリ構成
- `apps/web/` - フロントエンド（Next.js）
- `apps/api/` - バックエンド（Express/Fastify）
- `packages/ui/` - 共有UIコンポーネント
- `packages/shared/` - 共有ユーティリティ・型定義
- `packages/config/` - 共有設定（ESLint, TypeScript等）
 
## パッケージ間の依存関係
- `apps/web` → `packages/ui`, `packages/shared`
- `apps/api` → `packages/shared`
- `packages/ui` → `packages/shared`
 
## コーディング規約
- 共有パッケージへの変更は影響範囲を確認してからコミット
- パッケージ間の依存は `workspace:*` で指定
- 各パッケージのCLAUDE.mdも確認すること（詳細なルールはそちらに記載）
 
## テスト方針
- 単一テストの実行を優先（全体テストは時間がかかる）
- 共有パッケージの変更時は依存先パッケージのテストも実行
 
## 禁止事項
- パッケージ間の循環依存を作らない
- 共有パッケージを経由せず、アプリ間で直接コードを参照しない
- ルートの node_modules を直接操作しない

応用テクニック

サブディレクトリのCLAUDE.mdを活用する

モノレポの場合、各パッケージのディレクトリにもCLAUDE.mdを配置できます。Claude Codeはそのディレクトリのファイルを操作するとき、自動的にサブディレクトリのCLAUDE.mdも読み込みます。

monorepo/
├── CLAUDE.md              # プロジェクト全体のルール
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # フロントエンド固有のルール
│   └── api/
│       └── CLAUDE.md      # バックエンド固有のルール
└── packages/
    └── shared/
        └── CLAUDE.md      # 共有パッケージのルール

CLAUDE.local.mdで個人設定を追加する

チームで共有するCLAUDE.mdとは別に、個人的な設定は CLAUDE.local.md に書きましょう。.gitignore に追加してバージョン管理から除外します。

# CLAUDE.local.md
 
## 個人設定
- 開発サーバーはポート3001で起動（3000は別プロジェクトで使用中）
- テスト実行前にローカルのRedisを起動する必要がある
- デバッグ時は `DEBUG=app:*` 環境変数を設定する

@importで外部ファイルを参照する

CLAUDE.mdが長くなりすぎる場合は、@ 構文で他のファイルをインポートできます。

# CLAUDE.md
 
プロジェクト概要については @README.md を参照。
利用可能なコマンドは @package.json で確認可能。
 
## 追加の指示
- Gitワークフロー: @docs/git-workflow.md

コンテキスト消費に注意

@import で読み込んだファイルは起動時にコンテキストに展開されます。ファイルを分割しても合計サイズは変わらないので、本当に必要な情報だけをインポートしましょう。

まとめ

CLAUDE.mdはプロジェクトの種類に合わせてテンプレートから始めると効率的
必須項目は「ビルド/テストコマンド」と「コーディング規約」の2つ
200行以下を目標に、具体的で検証可能な指示を書く
モノレポではサブディレクトリごとにCLAUDE.mdを配置して指示をスコープできる
個人設定はCLAUDE.local.mdに分離してバージョン管理から除外する