CLAUDE.mdの書き方ガイド【開発効率を最大化するプロジェクト設定】

CLAUDE.mdとは？ — Claude Codeの「プロジェクト記憶」を理解する

CLAUDE.mdの役割 — 毎回の指示を不要にする設定ファイル

CLAUDE.mdは、プロジェクトのルートディレクトリに配置するMarkdownファイルです。Claude Codeが起動するたびに自動的に読み込まれ、セッション全体を通じて「ルール」として機能します。

わかりやすく言えば、CLAUDE.mdは「新しく入ったチームメンバーに渡すプロジェクトの引き継ぎ資料」のようなものです。技術スタック、コーディング規約、よく使うコマンド、プロジェクト固有の注意点——これらをCLAUDE.mdに書いておけば、Claude Codeは毎回のセッションでそのルールに従って作業してくれます。

CLAUDE.mdがないとどうなるのか？

CLAUDE.mdがない状態でClaude Codeを使うと、以下のような問題が頻繁に発生します。ShiftBの受講生142名のデータでも、CLAUDE.mdなしで開発を始めた受講生の78%が「AIが意図と違うコードを生成する」と回答しています。

CLAUDE.mdの読み込み仕組み — いつ・どのように適用されるか

Claude Codeは起動時に、以下の順番でCLAUDE.mdを読み込みます：

1. グローバル設定：~/.claude/CLAUDE.md（すべてのプロジェクトに適用）
2. プロジェクト設定：プロジェクトルートのCLAUDE.md（そのプロジェクトのみ）
3. ローカル設定：サブディレクトリのCLAUDE.md（該当ディレクトリ作業時のみ）

読み込まれた内容はすべてのプロンプトに暗黙的に追加されるため、毎回同じ指示を繰り返す必要がなくなります。ただし、CLAUDE.mdの内容が長すぎると実作業に使えるコンテキストが減少するため、200行以内に収めることが推奨されています。

CLAUDE.mdと他の設定ファイルとの違い

重要なポイントは、CLAUDE.mdはリンターの代替ではないということです。コードのフォーマット（インデント幅、セミコロンの有無など）はESLintやPrettierに任せ、CLAUDE.mdにはAIでなければ判断できないプロジェクト固有のルールを書くのが正しい使い方です。

CLAUDE.mdの基本構造 — 必ず含めるべき5つの要素

要素1：プロジェクト概要（What）

最初に、プロジェクトが何であるかを1〜2行で簡潔に伝えます。Claude Codeはこの情報を元に、コード生成の方向性を決定します。

# Project: ShiftB School Website
Next.js 15 (App Router) + Supabase + Vercel で構築された
プログラミングスクールのWebサイト。記事メディア・LP・申し込みフォームを含む。

ここで技術スタックを明記するのがポイントです。「Next.js」とだけ書くと、Pages RouterかApp Routerかが曖昧になり、AIが古いパターンのコードを生成する原因になります。バージョン番号とルーティング方式まで書きましょう。

要素2：コマンド一覧（How to Run）

開発・テスト・ビルド・デプロイで使うコマンドを列挙します。Claude Codeはここに書かれたコマンドを使ってタスクを実行するため、正確に書くことが重要です。

## Commands
- dev: `npm run dev` (port 3000)
- build: `npm run build`
- test: `npm run test`
- test single: `npm run test -- path/to/test.test.ts`
- lint: `npm run lint`
- format: `npx prettier --write .`

よくある失敗：テストコマンドに「単一ファイル実行」の方法を書かないケース。Claude Codeは変更したファイルのテストだけを実行したいことが多いため、単一ファイルの実行方法も必ず含めましょう。

要素3：コードスタイル・規約（Rules）

ESLintやPrettierでは表現できない、プロジェクト固有のルールを書きます。リンターに任せられるものは書かないのが鉄則です。

## Code Style
- Use named exports (not default exports) for components
- Tailwind: use `gap-10` format, NOT `gap-[40px]`
- API routes: always validate input with zod schemas
- Error handling: use custom AppError class, not raw Error
- Database: always use parameterized queries, never string interpolation

要素4：プロジェクト構造（Where）

重要なディレクトリやファイルの場所を示します。すべてのファイルを列挙する必要はなく、AIが迷いやすいポイントに絞ります。

## Architecture
- /app: Next.js App Router pages and layouts
- /app/_components: Shared UI components
- /app/_utils: Utility functions
- /app/api: API routes (all require auth middleware)
- /lib/db: Database access layer (Supabase client)
- /types: Shared TypeScript types

要素5：注意点・禁止事項（Gotchas）

プロジェクト固有の「地雷」を書きます。これがCLAUDE.mdの中で最も価値のあるセクションです。新しいチームメンバーが踏みがちな罠を先回りして伝えることで、AIのミスを防ぎます。

## Important Notes
- NEVER modify /lib/auth.ts directly - it's shared across all services
- The `users` table has RLS policies - always use service role key for admin operations
- Images must be served from /public/images, NOT external URLs (CSP policy)
- Environment variables: use NEXT_PUBLIC_ prefix only for client-side values

良い例・悪い例で学ぶCLAUDE.mdの書き方

悪い例：情報過多で効果が薄いCLAUDE.md

ShiftBの受講生のCLAUDE.mdレビューで最も多い問題が「書きすぎ」です。以下は典型的な悪い例です。

# 悪い例：情報過多のCLAUDE.md（500行以上）

## プロジェクト概要
このプロジェクトは2024年1月に開始された、React 18とNext.js 14を使った
Webアプリケーションです。チームは3名で構成されており、フロントエンドは
田中さん、バックエンドは佐藤さん、デザインは鈴木さんが担当しています。
スプリントは2週間サイクルで、毎週月曜日にスタンドアップミーティングを
実施しています。Jiraのプロジェクトキーは「MYAPP」です...

## すべてのAPIエンドポイント一覧
GET /api/users - ユーザー一覧を取得
GET /api/users/:id - ユーザー詳細を取得
POST /api/users - ユーザーを作成
PUT /api/users/:id - ユーザーを更新
DELETE /api/users/:id - ユーザーを削除
GET /api/products - 商品一覧を取得
...（100行以上続く）

## コーディング規約
- インデントは2スペース
- セミコロンは使わない
- シングルクォートを使う
- 1行は80文字以内
...（Prettierで設定できる内容が延々と続く）

この例の問題点は3つあります：

1. チーム情報・ミーティング情報はAIの作業に無関係
2. APIエンドポイントの全一覧はコードベースを読めばわかる情報
3. Prettierで設定できるフォーマットルールはリンターに任せるべき

CLAUDE.mdの各行について「これを削除したら、Claude Codeが間違いを犯すか？」と自問してください。答えが「No」なら削除すべきです。

良い例：簡潔で効果的なCLAUDE.md

同じプロジェクトのCLAUDE.mdを改善すると、以下のようになります。

# Project: MyApp
Next.js 14 (App Router) + Prisma + PostgreSQL のSaaSアプリケーション。
マルチテナント対応。Stripe決済連携あり。

## Commands
- dev: `npm run dev`
- build: `npm run build`
- test: `npx vitest run`
- test single: `npx vitest run path/to/test.ts`
- lint: `npm run lint`
- db migrate: `npx prisma migrate dev`
- db generate: `npx prisma generate`

## Code Style
- Named exports for all components and utilities
- Tailwind: use spacing scale (gap-4), not arbitrary values (gap-[16px])
- API routes: validate all input with zod, return typed responses
- Use `AppError` class for errors, not raw throw
- DB queries: always scope by tenantId for multi-tenant isolation

## Architecture
- /app/(dashboard): Authenticated pages (require session)
- /app/(marketing): Public pages (no auth)
- /lib/db.ts: Prisma client singleton
- /lib/auth.ts: NextAuth config — DO NOT MODIFY without team review

## Important
- All DB queries MUST include tenantId filter (multi-tenant)
- Never use `dangerouslySetInnerHTML` — use sanitize-html lib
- Images: /public/images only, no external URLs (CSP)
- Env vars: NEXT_PUBLIC_ prefix = client-side only

この例は約40行で、AIが本当に知るべき情報だけを含んでいます。特にマルチテナント対応のtenantIdフィルター必須というルールは、リンターでは検出できないため、CLAUDE.mdに書く価値があります。

判断基準：CLAUDE.mdに書くべきか？チェックリスト

実際のプロンプト出力比較 — CLAUDE.mdの有無でここまで変わる

同じプロンプト「ユーザー一覧APIを作って」をCLAUDE.mdあり/なしで比較した結果です。

CLAUDE.mdなしの場合：

// Pages Router + JavaScript で生成される
export default function handler(req, res) {
  const users = await db.query("SELECT * FROM users");
  res.status(200).json(users);
}

CLAUDE.mdありの場合：

// App Router + TypeScript + zod + tenantId で生成される
import { z } from "zod";
import { prisma } from "@/lib/db";
import { getSession } from "@/lib/auth";
import { AppError } from "@/lib/errors";

const querySchema = z.object({
  page: z.coerce.number().min(1).default(1),
  limit: z.coerce.number().min(1).max(100).default(20),
});

export async function GET(request: Request) {
  const session = await getSession();
  if (!session) throw new AppError("Unauthorized", 401);

  const { searchParams } = new URL(request.url);
  const { page, limit } = querySchema.parse(
    Object.fromEntries(searchParams)
  );

  const users = await prisma.user.findMany({
    where: { tenantId: session.tenantId },
    skip: (page - 1) * limit,
    take: limit,
  });

  return Response.json({ users, page, limit });
}

CLAUDE.mdに書いたルール（App Router、zod検証、tenantIdフィルター、AppErrorクラス）がすべて反映されています。1回のプロンプトで、レビュー不要なレベルのコードが生成される——これがCLAUDE.mdの威力です。

プロジェクト規模別CLAUDE.mdテンプレート

小規模プロジェクト（個人開発・MVP）：20〜40行

個人開発やMVP段階では、シンプルなCLAUDE.mdで十分です。ShiftBの受講生の初期プロジェクトの87%がこのサイズに収まっています。

# Project: TaskFlow
タスク管理SaaS。Next.js 15 (App Router) + Supabase + Vercel。

## Commands
- dev: `npm run dev`
- build: `npm run build`
- lint: `npm run lint`

## Code Style
- TypeScript strict mode
- Named exports for components
- Tailwind: spacing scale only (gap-4, not gap-[16px])
- Use server actions for form submissions

## Architecture
- /app/(app): Authenticated routes
- /app/(marketing): Public pages
- /components/ui: shadcn/ui components

## Important
- Supabase RLS is enabled — always test with correct user context
- Never expose service_role key to client-side code

ポイント：MVP段階ではルールを最小限にし、開発を進める中で必要になったルールを追加していくのがベストです。最初から完璧を目指すと、CLAUDE.mdの作成自体に時間がかかり本末転倒です。

中規模プロジェクト（チーム開発・本格SaaS）：40〜100行

複数の機能モジュールや認証・決済連携がある本格的なプロジェクトでは、より詳細なルールが必要になります。

# Project: ShopManager
ECサイト管理SaaS。Next.js 15 (App Router) + Prisma + PostgreSQL + Stripe。
マルチテナント対応。管理者/スタッフ/オーナーの3ロール。

## Commands
- dev: `npm run dev`
- build: `npm run build`
- test: `npx vitest run`
- test single: `npx vitest run path/to/test.ts`
- lint: `npm run lint`
- db migrate: `npx prisma migrate dev`
- db seed: `npx prisma db seed`

## Code Style
- Named exports for all modules
- Tailwind: spacing scale, no arbitrary values
- API: validate input with zod, return typed { data, error } responses
- Errors: use AppError class with error codes
- DB: always scope queries by organizationId (multi-tenant)
- Auth: check role permissions before DB operations

## Architecture
- /app/(dashboard)/[orgId]: Tenant-scoped dashboard routes
- /app/api/v1: Public API endpoints (API key auth)
- /app/api/internal: Internal endpoints (session auth)
- /lib/db.ts: Prisma singleton with query logging
- /lib/stripe.ts: Stripe client — webhook handler in /app/api/webhooks
- /services: Business logic layer (keep thin controllers)

## Testing
- Unit tests: /tests/unit (pure logic, no DB)
- Integration tests: /tests/integration (uses test DB)
- Always mock Stripe in tests using stripe-mock

## Important
- All DB queries MUST include organizationId filter
- Stripe webhook handler MUST verify signature before processing
- Never delete records — use soft delete (deletedAt timestamp)
- File uploads: S3 only, max 10MB, validate MIME type
- Rate limit all public API endpoints (see /lib/rate-limit.ts)

大規模プロジェクト（モノレポ・マイクロサービス）：階層構造で管理

大規模プロジェクトでは、1つのCLAUDE.mdに全情報を詰め込むのではなく、階層構造で管理します。

# ルートの CLAUDE.md（共通ルール：20行程度）

# Project: MegaPlatform
pnpm workspaceモノレポ。フロント(Next.js) + API(Hono) + 共有パッケージ。

## Commands
- install: `pnpm install`
- build all: `pnpm run build`
- test all: `pnpm run test`

## Monorepo Rules
- Shared types: /packages/types に定義
- 各パッケージ間の依存は packages/types のみ許可
- 直接importはNG — 必ずパッケージ名で参照

# apps/web/CLAUDE.md（フロントエンド固有のルール）

Next.js 15 App Router フロントエンド。

## Commands
- dev: `pnpm --filter web dev`
- test: `pnpm --filter web test`

## Code Style
- Server Components がデフォルト。"use client" は最小限に
- データ取得は Server Components 内で直接行う
- クライアント状態は zustand を使用

# apps/api/CLAUDE.md（API固有のルール）

Hono + Drizzle ORM の API サーバー。

## Commands
- dev: `pnpm --filter api dev`
- test: `pnpm --filter api test`

## Code Style
- All routes must use authMiddleware
- Response format: { success: boolean, data?: T, error?: string }
- Use drizzle schema, not raw SQL

CLAUDE.mdの階層構造 — グローバル・プロジェクト・ローカルの使い分け

3つの階層とその役割

Claude Codeは3つの階層のCLAUDE.mdを読み込みます。それぞれの役割を理解して使い分けることで、設定の重複を防ぎつつ、必要な場所に適切なルールを配置できます。

グローバルCLAUDE.mdの実践例

~/.claude/CLAUDE.mdには、どのプロジェクトでも共通のルールを書きます。

# Global Rules

- 日本語で回答する
- コミットメッセージは日本語で、Conventional Commits形式
  例: feat: ユーザー認証機能を追加
- コードコメントは英語
- エラーメッセージは英語
- 不明な点があれば実装前に質問する

注意：グローバルCLAUDE.mdは10行以内に収めることを推奨します。すべてのプロジェクトに読み込まれるため、長すぎると全プロジェクトのパフォーマンスに影響します。

ローカルCLAUDE.mdの活用シーン

サブディレクトリにCLAUDE.mdを置くケースは、主に以下の3つのパターンです：

1. モノレポの各パッケージ：フロントエンドとバックエンドで異なるルールが必要な場合
2. テストディレクトリ：テストの書き方や使用するモック・ヘルパーの指定
3. 特殊なモジュール：決済処理やメール送信など、特に慎重な取り扱いが必要な領域

# tests/CLAUDE.md（テストディレクトリ固有のルール）

## Testing Conventions
- Use vitest, not jest
- Test file naming: {module}.test.ts
- Use test factories from /tests/factories for test data
- Mock external APIs using msw (Mock Service Worker)
- Never make real HTTP requests in tests
- Each test must be independent — no shared mutable state

階層間の優先順位と競合時の振る舞い

CLAUDE.mdの内容が階層間で競合した場合、より具体的（ネストが深い）ファイルが優先されます。ただし、上位の設定が完全に無視されるわけではなく、すべてのCLAUDE.mdの内容がコンテキストに含まれます。

たとえば、グローバルで「日本語で回答」と設定し、特定プロジェクトで「英語で回答」と設定した場合、そのプロジェクトではClaude Codeは英語で回答します。矛盾する指示がある場合は、ローカル > プロジェクト > グローバルの順で優先されます。

CLAUDE.mdの育て方 — 継続的メンテナンスの実践法

/init コマンドで始める — ゼロからの初期化

CLAUDE.mdを一から書く必要はありません。Claude Codeの/init コマンドを実行すると、プロジェクトの構造を自動分析して、CLAUDE.mdのたたき台を生成してくれます。

# プロジェクトルートで実行
claude
> /init

/initが生成するCLAUDE.mdは、package.jsonやディレクトリ構造から自動的に技術スタック・コマンド・アーキテクチャを推測します。ただし、プロジェクト固有の注意点（Gotchas）は自動生成できないため、手動で追記する必要があります。

「AIが間違えたら追記する」育成サイクル

CLAUDE.mdの最も効果的な育て方は、「AIが間違えるたびに、その防止ルールを追記する」というサイクルです。ShiftBではこれを「CLAUDE.md育成ループ」と呼んでいます。

1. Claude Codeで作業する
2. AIが間違った出力をした場合、なぜ間違えたかを特定する
3. その間違いを防ぐルールをCLAUDE.mdに1行追記する
4. 次回以降、同じ間違いが発生しなくなる

たとえば、Claude Codeがimport styles from "./page.module.css"のようなCSS Modulesのコードを生成したら、CLAUDE.mdにUse Tailwind utility classes, not CSS Modulesと追記します。これだけで、以降のセッションではTailwindのコードが生成されるようになります。

ShiftBの受講生データでは、この育成ループを2週間実践した受講生のCLAUDE.mdは平均35行になり、AIのやり直し回数が初日比で67%減少しています。

定期メンテナンスの3つのルール

CLAUDE.mdは「書いて終わり」ではありません。古くなったCLAUDE.mdは、ないよりも有害です。以下の3つのルールで定期的にメンテナンスしましょう。

CLAUDE.mdのバージョン管理

CLAUDE.mdは必ずGitにコミットしましょう。理由は2つあります：

1. チーム全員で共有できる：チーム開発では、CLAUDE.mdを通じてAIへの指示を統一できます
2. 変更履歴が残る：どのルールがいつ追加されたか、なぜ追加されたかがgit logで確認できます

.gitignoreに入れてはいけません。個人的な設定は~/.claude/CLAUDE.md（グローバル）に書き、プロジェクトのCLAUDE.mdにはチームで共有すべきルールだけを書きましょう。

受講生142名のデータで見るCLAUDE.mdの効果

CLAUDE.md導入前後の開発効率比較

ShiftBでは2025年後半から、受講生全員にCLAUDE.mdの作成を推奨しています。導入前後のデータを比較すると、その効果は明確です。

CLAUDE.mdの行数と効果の関係

興味深いのは、CLAUDE.mdの行数と効果の関係です。ShiftBの受講生データを分析すると、30〜60行のCLAUDE.mdが最も効果的であることがわかりました。

100行を超えるとむしろ効果が下がっています。これは、情報過多によってClaude Codeのコンテキストウィンドウを圧迫し、本来の作業指示に使えるトークン数が減少するためと考えられます。

最も効果のあったCLAUDE.mdのセクション

受講生に「CLAUDE.mdのどのセクションが最も役立ったか」を聞いたところ、以下の結果でした：

1. 注意点・禁止事項（Gotchas） — 回答者の89%が「非常に効果的」
2. コマンド一覧 — 回答者の82%が「非常に効果的」
3. コードスタイル — 回答者の71%が「非常に効果的」
4. プロジェクト構造 — 回答者の65%が「効果的」
5. プロジェクト概要 — 回答者の58%が「効果的」

注意点・禁止事項が圧倒的に1位という結果は、非常に示唆的です。AIが「やってはいけないこと」を知ることで、最も大きなミスを防げるからです。CLAUDE.mdに最初に書くべきは、禁止事項かもしれません。

よくある質問（FAQ）

Q1. CLAUDE.mdはCursor（.cursorrules）と互換性がありますか？

直接の互換性はありませんが、内容は非常に似ています。プロジェクト概要・コマンド・コード規約・注意点という構成はほぼ同じなので、CLAUDE.mdの内容を.cursorrulesにコピーして微調整するのが最も効率的です。ShiftBでは両方のファイルを同じ内容で管理している受講生も多いです。

Q2. CLAUDE.mdは何語で書くべきですか？

英語を推奨します。理由は2つあります。①LLMは英語の学習データが最も多いため、英語の指示の方が正確に理解される傾向がある。②技術用語（コマンド、ライブラリ名、設計パターン名）はもともと英語なので、日本語に翻訳すると曖昧になることがあります。ただし、日本語で書いても十分機能するため、英語が苦手な場合は日本語でOKです。

Q3. CLAUDE.mdは.gitignoreに入れるべきですか？

入れるべきではありません。CLAUDE.mdはプロジェクトのルールを定義するファイルであり、チーム全員で共有すべきものです。個人的な設定（「日本語で回答して」など）は、グローバル設定（~/.claude/CLAUDE.md）に書きましょう。

Q4. /initで生成されたCLAUDE.mdをそのまま使っていいですか？

出発点としては十分ですが、そのままでは不十分です。/initは技術スタックとコマンドを自動検出しますが、プロジェクト固有の注意点（Gotchas）は生成できません。/initの出力を土台に、最低でも「注意点・禁止事項」セクションを手動で追加してください。受講生データでも、/initの出力だけの場合と、注意点を追記した場合で、やり直し回数に2.1倍の差がありました。

Q5. CLAUDE.mdが長くなりすぎた場合はどうすればいい？

100行を超えたら見直しのサインです。以下の手順で整理しましょう。①リンターで検出できるルール（インデント、セミコロン等）を削除。②コードベースから推測できる情報（ディレクトリ構造の全リスト等）を削除。③特定のサブディレクトリにしか関係しないルールは、そのディレクトリのローカルCLAUDE.mdに移動。

Q6. 複数のAIツール（Claude Code + Cursor）を併用する場合のCLAUDE.mdの管理方法は？

最もシンプルなアプローチは、CLAUDE.mdを「マスター」として管理し、.cursorrulesはCLAUDE.mdのシンボリックリンクまたはコピーにする方法です。内容の同期を自動化するため、git hooksでCLAUDE.mdの変更時に.cursorrulesも更新するスクリプトを設定している受講生もいます。

Q7. CLAUDE.mdにプロンプトテンプレートを書いてもいいですか？

書くべきではありません。CLAUDE.mdは「プロジェクトのルール」を定義する場所であり、「作業指示」を書く場所ではありません。プロンプトテンプレートは、Claude Codeのカスタムスラッシュコマンド（.claude/commands/）に配置するのが適切です。CLAUDE.mdには「何を」ではなく「どのように」を書きましょう。

まとめ

CLAUDE.mdは、Claude Codeを「賢いアシスタント」から「プロジェクトを熟知したパートナー」に変える設定ファイルです。この記事のポイントをまとめます。

• 5つの必須要素を含める：プロジェクト概要、コマンド、コード規約、構造、注意点
• 簡潔に書く：30〜60行が最適。リンターに任せられるルールは書かない
• 禁止事項を最優先で書く：受講生の89%が「最も効果的」と回答
• /initで始めて育てる：AIが間違えたら1行追記する育成ループ
• 定期メンテナンスを行う：古いCLAUDE.mdは、ないよりも有害
• Gitにコミットして、チームで共有する

ShiftBの受講生データでは、適切なCLAUDE.mdを導入するだけで、やり直し回数が60%減少し、MVP完成までの期間が54%短縮されています。たった30〜60行のMarkdownファイルが、開発体験を劇的に変えるのです。

まだCLAUDE.mdを作成していない方は、今すぐプロジェクトルートで/initを実行して、まずはたたき台を作ってみてください。そして、AIが間違えるたびに1行ずつ育てていきましょう。