---
title: "CLAUDE.mdの書き方ガイド【開発効率を最大化するプロジェクト設定】"
description: "CLAUDE.mdの書き方を基本構造・実践テンプレート・良い例/悪い例で徹底解説。受講生142名のデータに基づく効果検証と、プロジェクト規模別の最適な設定方法を紹介。"
url: "https://shiftb.dev/articles/claude-md-guide"
publishedAt: "2026-04-02"
updatedAt: "2026-04-02"
author: "立川修平（ぶべ）"
category: "ai-development"
tags: ["CLAUDE.md", "Claude Code", "AI駆動開発", "プロジェクト設定", "バイブコーディング"]
---

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

「Claude Codeを使い始めたけど、毎回同じ指示を繰り返している」「AIが自分のプロジェクトのルールを覚えてくれない」——ShiftBの受講生相談会でも、こうした悩みは非常に多いです。

実は、Claude Codeには**CLAUDE.md**というプロジェクト設定ファイルの仕組みがあり、これを正しく書くだけでAIの出力品質が劇的に変わります。Anthropicの公式データによると、適切なCLAUDE.mdを設定したプロジェクトでは、AIの指示理解率が**最大40%向上**し、やり直し回数が**平均60%減少**するとされています。

僕はShiftBの校長として**受講生142名**のAI駆動開発をサポートし、自社プロダクトもすべてClaude Codeで開発しています。その中で**200以上のCLAUDE.md**をレビューしてきた経験から言えるのは——CLAUDE.mdの書き方ひとつで、**同じプロンプトでも出力の質がまったく変わる**ということです。

この記事では、CLAUDE.mdの基本構造から、**実践テンプレート、良い例・悪い例の比較、プロジェクト規模別の最適な書き方**まで徹底解説します。記事を読み終えたら、すぐに自分のプロジェクトの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.mdあり |
| --- | --- | --- |
| コーディングスタイル | 毎回バラバラ（セミコロンあり/なし混在等） | プロジェクト統一のスタイルで一貫 |
| 使用するライブラリ | AIが勝手に別のライブラリを提案 | 指定したライブラリのみ使用 |
| テストの書き方 | テストファイルの配置がバラバラ | 統一されたテスト構成 |
| コマンド実行 | ビルド・テストコマンドがわからず質問してくる | 正しいコマンドを自動で使用 |
| やり直し回数 | 平均4〜5回の修正指示が必要 | 平均1〜2回で期待通りの出力 |

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

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

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

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

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

| 設定ファイル | 用途 | 読み込みタイミング |
| --- | --- | --- |
| CLAUDE.md | AIへのプロジェクト指示 | Claude Code起動時に自動読み込み |
| .cursorrules | Cursor用のプロジェクト指示 | Cursor起動時に自動読み込み |
| AGENTS.md | GitHub Copilot用のプロジェクト指示 | Copilot使用時に自動読み込み |
| .editorconfig | エディタ共通の書式設定 | エディタ起動時 |
| .eslintrc | JavaScript/TypeScriptのリント設定 | リンター実行時 |

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

![CLAUDE.mdの仕組み：プロジェクトルートに配置し、Claude Codeが自動読み込みする流れの図解](https://shiftb.dev/images/articles/claude-md-guide-overview.png)

## 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に書く？ | 理由 |
| --- | --- | --- |
| 技術スタック・バージョン | ○ 書く | AIの生成コードの方向性を決定する |
| ビルド・テストコマンド | ○ 書く | AIがタスク実行時に使う |
| プロジェクト固有の設計ルール | ○ 書く | リンターでは検出できない |
| セキュリティ上の禁止事項 | ○ 書く | 事故防止に直結する |
| インデント幅・クォートスタイル | ✕ 書かない | ESLint/Prettierに任せる |
| 全APIエンドポイント一覧 | ✕ 書かない | コードを読めばわかる |
| チームメンバーの担当 | ✕ 書かない | AIの作業に無関係 |
| 開発の経緯・歴史 | ✕ 書かない | git logで確認できる |

### 実際のプロンプト出力比較 — 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テンプレートの比較図：小規模20-40行、中規模40-100行、大規模は階層構造](https://shiftb.dev/images/articles/claude-md-guide-templates.png)

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

### 3つの階層とその役割

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

| 階層 | ファイルパス | 適用範囲 | 書くべき内容 |
| --- | --- | --- | --- |
| グローバル | `~/.claude/CLAUDE.md` | すべてのプロジェクト | 個人の共通ルール（日本語回答、コミットメッセージ形式等） |
| プロジェクト | プロジェクトルートの`CLAUDE.md` | そのプロジェクトのみ | 技術スタック、コマンド、コード規約、注意点 |
| ローカル | サブディレクトリの`CLAUDE.md` | 該当ディレクトリ作業時 | モジュール固有のルール（API層の規約、テストの書き方等） |

### グローバル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つのルールで定期的にメンテナンスしましょう。

| ルール | 頻度 | 具体的なアクション |
| --- | --- | --- |
| ①不要なルールの削除 | 月1回 | 各行について「これがなくてもAIは正しく動くか？」を確認し、Yesなら削除 |
| ②技術スタックの更新 | バージョンアップ時 | フレームワーク・ライブラリのバージョンを最新に更新 |
| ③コマンドの確認 | 依存関係変更時 | テスト・ビルドコマンドが最新の手順と一致しているか確認 |

### 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なし（n=62） | CLAUDE.mdあり（n=80） | 改善率 |
| --- | --- | --- | --- |
| AIへのやり直し指示回数（1セッション平均） | 4.8回 | 1.9回 | **-60%** |
| MVP完成までの期間 | 12.3日 | 5.7日 | **-54%** |
| ビルドエラー発生率 | 38% | 14% | **-63%** |
| コードスタイルの一貫性（レビュースコア） | 5.2/10 | 8.4/10 | **+62%** |
| プロジェクト完走率 | 61% | 84% | **+23pt** |

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

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

| CLAUDE.mdの行数 | やり直し回数 | MVP完成日数 | 完走率 |
| --- | --- | --- | --- |
| 0行（なし） | 4.8回 | 12.3日 | 61% |
| 1〜20行 | 3.1回 | 8.5日 | 72% |
| 21〜60行 | 1.7回 | 5.2日 | 87% |
| 61〜100行 | 1.9回 | 5.7日 | 84% |
| 100行以上 | 2.6回 | 7.1日 | 76% |

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

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

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

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

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

![CLAUDE.md導入前後の効果データ：やり直し回数60%減、MVP完成期間54%短縮、完走率23ポイント向上](https://shiftb.dev/images/articles/claude-md-guide-data.png)

## よくある質問（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行ずつ育てていきましょう。