【保存版】CLAUDE.md 設計パターン集──個人開発・チーム開発・モノレポの3テンプレートを公開

Posted at 2026-05-18

結論：CLAUDE.md は「設計」するものです

CLAUDE.md は『書けば動く』が『設計しないと破綻する』──プロジェクト規模別に実戦投入したテンプレートをそのまま公開します。

この記事を読むと、以下がわかります。

個人開発・チーム開発・モノレポそれぞれに最適化した CLAUDE.md テンプレート
トークンを浪費しないためのアンチパターンと回避策
/compact コマンドとの併用でコンテキストウィンドウを最大限活用する方法

「とりあえず README を貼っておけばいいんでしょ？」──それ、一番やってはいけないパターンです。

環境・前提条件

項目	バージョン / 条件
Claude Code	最新安定版（2025年7月時点）
対象読者	Claude Code を業務で使うエンジニア
前提知識	ターミナルでの Claude Code 基本操作ができること

1. CLAUDE.md が果たす3つの役割

CLAUDE.md は単なるメモ書きではありません。大きく分けて 3つの役割 を担っています。

① コンテキスト注入

Claude Code はセッション開始時に CLAUDE.md を読み込みます。ここにプロジェクトの技術スタックやディレクトリ構成を書くことで、毎回説明し直す手間がゼロになります。

② ガードレール

「本番 DB に直接マイグレーションを実行しない」「dist/ ディレクトリは編集しない」など、禁止操作を明示できます。Claude は CLAUDE.md の指示を高い優先度で守ります。

③ チーム規約

命名規則、テスト方針、コミットメッセージのフォーマットなど、人間のチームメンバーに求める規約をそのまま AI にも適用できます。

2. テンプレート①：個人開発向け──最小構成で最大効果

個人開発では「短く・必要十分に」が鉄則です。トークンを節約しながら、Claude の出力品質を最大化しましょう。

テンプレート

# CLAUDE.md

## Project Overview
- 個人開発のタスク管理アプリ（Next.js 15 + Supabase）
- 一人で開発しているため、コードレビューは Claude が担う

## Tech Stack
- Framework: Next.js 15 (App Router)
- Language: TypeScript (strict mode)
- DB: Supabase (PostgreSQL)
- Styling: Tailwind CSS v4
- Package Manager: pnpm

## Directory Structure
src/
├── app/          # App Router pages
├── components/   # React components (default: Server Component)
├── lib/          # Utility functions & Supabase client
├── types/        # TypeScript type definitions
└── hooks/        # Custom React hooks (Client Component only)

## Coding Rules
- 関数コンポーネントのみ使用（class component 禁止）
- `any` 型の使用禁止。不明な型は `unknown` を使い、型ガードで絞り込む
- コンポーネントファイルは PascalCase、それ以外は camelCase
- Server Component をデフォルトとし、`use client` は必要最小限に

## Commands
- `pnpm dev` – 開発サーバー起動
- `pnpm build` – プロダクションビルド
- `pnpm test` – vitest 実行
- `pnpm lint` – eslint 実行

## Important Notes
- Supabase の service_role_key は絶対にクライアントサイドで使わない
- `.env.local` をコード内にハードコードしない
- 変更後は必ず `pnpm build` でビルドが通ることを確認してから完了とする

設計ポイント

セクション	狙い
Project Overview	一文でプロジェクト全体像を注入
Tech Stack	バージョンまで明記して古い API の提案を防ぐ
Directory Structure	「どこに何を置くか」の迷いを排除
Coding Rules	最重要ルールを4〜5個に絞る
Commands	Claude がコマンドを実行する際の正確性を担保
Important Notes	絶対に守るべきセキュリティ・品質ライン

個人開発では 全体で 80〜150 行以内 に収めるのが目安です。これ以上長くなるなら、設計を見直すサインかもしれません。

3. テンプレート②：チーム開発向け──レビュー規約と禁止操作の埋め込み

チーム開発では「人間同士の暗黙知」を CLAUDE.md で明文化することが重要です。

テンプレート

# CLAUDE.md

## Project Overview
- BtoB SaaS プロダクト（マルチテナント構成）
- チーム: バックエンド3名、フロントエンド2名、QA1名
- Claude Code は全メンバーがローカルで利用

## Tech Stack
- Backend: Go 1.23 + Echo v4
- Frontend: React 19 + TypeScript 5.7
- DB: PostgreSQL 16 (マルチテナント: スキーマ分離方式)
- Infrastructure: AWS ECS Fargate + RDS
- CI/CD: GitHub Actions

## Architecture Decisions
- アーキテクチャ: クリーンアーキテクチャ (domain → usecase → infra)
- API 設計: REST (OpenAPI 3.1 で定義済み。`/docs/openapi.yaml` を参照)
- 認証: JWT (RS256) + リフレッシュトークン

## Coding Standards
### Backend (Go)
- エラーハンドリング: `fmt.Errorf("xxx: %w", err)` でラップ
- ロガー: `slog` パッケージのみ使用（`log` パッケージ禁止）
- テスト: テーブルドリブンテスト必須。カバレッジ80%以上を維持

### Frontend (React)
- 状態管理: TanStack Query でサーバー状態管理。グローバル state は Zustand
- CSS: CSS Modules（Tailwind は使わない──既存コードとの整合性のため）
- テスト: React Testing Library + vitest

## Git Rules
- ブランチ: `feature/TICKET-123-short-description`
- コミットメッセージ: Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)
- PR 作成時: 変更概要 + 動作確認手順を必ず記載

## 🚫 Prohibited Actions
- `main` / `develop` ブランチへの直接コミット禁止
- `DROP TABLE` / `TRUNCATE` 文の生成禁止
- 本番環境の環境変数・シークレットをコード内に記載しない
- `node_modules/` や `vendor/` の中身を編集しない
- 既存の OpenAPI 定義と矛盾する API エンドポイントの追加禁止

## Review Checklist (Claude がコード生成時にセルフチェック)
- [ ] 型安全性: `any` / interface{} の不必要な使用がないか
- [ ] SQL インジェクション: プレースホルダを使っているか
- [ ] N+1 クエリ: ループ内で DB アクセスしていないか
- [ ] テスト: 新規関数にはテストが書かれているか
- [ ] 命名: チームの命名規則に沿っているか

## Commands
- Backend: `make run`, `make test`, `make lint`
- Frontend: `npm run dev`, `npm run test`, `npm run lint`
- DB Migration: `make migrate-up` (ローカルのみ)

設計ポイント

チーム開発テンプレートのキモは Prohibited Actions と Review Checklist の2セクションです。

Prohibited Actions: 「やってはいけないこと」を箇条書きで明示すると、Claude は非常に忠実に守ります。🚫 のような絵文字で視覚的に強調するのも効果的です
Review Checklist: Claude にコード生成時の「セルフレビュー」を促します。チェックリスト形式にすることで、漏れを減らせます

チーム全員で .claude/ ディレクトリごと Git 管理し、CLAUDE.md の変更も PR レビュー対象にするのがおすすめです。

4. テンプレート③：モノレポ向け──サブディレクトリ別の継承戦略

モノレポでは「全体に適用するルール」と「パッケージ固有のルール」を分離する必要があります。Claude Code は ディレクトリ階層に沿って CLAUDE.md を読み込むため、この仕組みを活用します。

スコープ継承の仕組み

ルートの CLAUDE.md が最も広いスコープを持ち、サブディレクトリの CLAUDE.md が特化した指示で上書き・補完します。Claude Code がサブディレクトリで作業する場合、ルートからそのディレクトリまでの全 CLAUDE.md が結合されて読み込まれます。

ルート CLAUDE.md（共通ルール）

# CLAUDE.md (Repository Root)

## Project Overview
- モノレポ構成の SaaS プロダクト
- パッケージマネージャ: pnpm workspaces
- パッケージ一覧は `/packages/` 配下を参照

## Global Rules
- 全パッケージ共通で TypeScript strict mode を使用
- Conventional Commits を遵守
- パッケージ間の依存は `@myapp/*` スコープの内部パッケージ経由のみ
- 循環依存の作成禁止

## 🚫 Global Prohibited Actions
- ルートディレクトリ直下にアプリケーションコードを置かない
- 他パッケージの `src/` 内部を直接 import しない（公開 API のみ使用）
- `pnpm-lock.yaml` を手動編集しない

## Monorepo Commands
- `pnpm install` – 全パッケージの依存インストール
- `pnpm -r build` – 全パッケージビルド
- `pnpm --filter <package> test` – 特定パッケージのテスト実行

サブディレクトリ CLAUDE.md（パッケージ固有ルール）

# CLAUDE.md (packages/web-app)

## Package Overview
- ユーザー向け Web フロントエンド
- Framework: Next.js 15 (App Router)

## Local Rules (このパッケージ固有)
- コンポーネント設計: Atomic Design (atoms → molecules → organisms)
- `app/` 配下は Server Component をデフォルトとする
- API 通信は `@myapp/api-client` パッケージ経由のみ

## Commands
- `pnpm --filter web-app dev` – 開発サーバー
- `pnpm --filter web-app test` – テスト実行
- `pnpm --filter web-app build` – ビルド

継承戦略のコツ

ルートは「してはいけないこと」を中心に──全体に影響する禁止ルールを書く
サブディレクトリは「どうすべきか」を中心に──そのパッケージ固有の設計判断を書く
3階層以上は慎重に──深すぎるとトークン消費が増え、ルールの衝突リスクも高まります

5. アンチパターン集：トークンを浪費する CLAUDE.md の共通ミス5選

実戦で見てきた「やりがちだけど効果が薄い」パターンを紹介します。

❌ 1. README.md のコピペ丸貼り

README はユーザー向けのドキュメントであり、AI への指示書ではありません。バッジ画像の URL やインストール手順の冗長な説明がトークンを圧迫します。

✅ 対策: CLAUDE.md には「Claude に知ってほしい情報」だけを抽出して書く。

❌ 2. ファイルツリーの全量記載

数百ファイルのツリーを貼ると、それだけで数千トークンを消費します。

✅ 対策: 第2階層までに留め、重要なディレクトリにだけコメントを添える。

❌ 3. 曖昧な精神論

「きれいなコードを書いてください」「ベストプラクティスに従ってください」は、Claude にとって解釈の幅が広すぎて実質的に機能しません。

✅ 対策: 具体的なルールに変換する。「関数は30行以内」「ネストは3段まで」のように数値化する。

❌ 4. 外部リンクの大量添付

Claude Code は CLAUDE.md 内のリンクを自動で読みに行きません。URL を並べるだけではトークンの無駄です。

✅ 対策: リンク先の要点を1〜2行で要約して記載し、リンクは参考情報として添える。

❌ 5. 変更履歴・議事録の埋め込み

「2025/06/15: 認証方式を JWT に変更」のような履歴は、現在の状態が分かれば不要です。

✅ 対策: CLAUDE.md には常に「現在の正」だけを書く。変更履歴は Git の履歴で追えばよい。

6. /compact との併用でコンテキストウィンドウを節約するテクニック

CLAUDE.md を充実させると、その分コンテキストウィンドウを消費します。長いセッションでは、途中でコンテキストが溢れることもあります。

/compact コマンドとは

/compact は Claude Code のセッション中に使える組み込みコマンドで、これまでの会話履歴を要約・圧縮してくれます。コンテキストウィンドウの空きを回復させたいときに使います。

実践テクニック

① セッション中にコンテキスト残量を意識する

大きな機能実装の途中で「レスポンスが遅くなった」「回答の質が下がった」と感じたら、コンテキスト上限に近づいているサインです。/compact で会話を圧縮しましょう。

② CLAUDE.md 自体をコンパクトに保つ

CLAUDE.md はセッション開始時に毎回読み込まれるため、肥大化はセッション全体に影響します。

ルールは箇条書き1行で表現する
説明文ではなく「指示文」で書く
例示は最小限（1例で十分伝わるなら1例だけ）

③ タスクごとにセッションを分ける

1セッションで複数の無関係なタスクを行うと、コンテキストが膨張します。「1タスク = 1セッション」を原則にすると、CLAUDE.md の指示が最後まで効き続けます。

④ /compact にカスタム指示を渡す

/compact 現在のタスクはユーザー認証機能の実装です。認証に関係ない会話は省略してください。

このように、何を残して何を捨てるかを指示すると、圧縮後の品質が上がります。

まとめ

CLAUDE.md は「コンテキスト注入」「ガードレール」「チーム規約」の3役を担う設計文書であり、規模に応じたテンプレートを選ぶことが重要
モノレポでは階層的な CLAUDE.md 配置で「共通ルール」と「パッケージ固有ルール」を分離し、トークン効率とルールの明確性を両立する
アンチパターン（README 丸貼り・曖昧な指示・履歴の埋め込み）を避け、/compact と併用することでコンテキストウィンドウを最大限に活かせる

参考リンク

Claude Code 公式ドキュメント – Memory – CLAUDE.md の仕組みと読み込み順序の詳細
Claude Code 公式ドキュメント – Overview – Claude Code の全体像と基本操作
Anthropic 公式ブログ – Best practices for using Claude Code – Claude Code 活用のベストプラクティス

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up