CLAUDE.mdとは何か

CLAUDE.mdは、プロジェクトの .claude/ フォルダに配置するMarkdownファイルです。

Claude Codeはセッション開始時にこのファイルを自動で読み込み、以降の会話の文脈として保持します。

つまり、「このプロジェクトではXXXしてください」という指示を毎回言わなくて済む仕組みです。

your-project/
└── .claude/
    ├── CLAUDE.md    ← これ
    ├── skills/
    └── commands/

原則1: 長さは50〜150行に収める

最初に多くの人が犯すミスが「長すぎるCLAUDE.md」を書くことです。

海外上級者の共通見解：

50〜150行：最適
200行超：効果がゼロに近づく

なぜか？Claude Codeはコンテキスト全体を均等に扱いません。重要な指示が後半に埋もれると参照されなくなるのです。

# ❌ やりがちな失敗
このプロジェクトは2020年に始まった...（背景説明が延々と続く）
フロントエンドにはReactを使っています。バックエンドはNode.jsで...
データベースはPostgreSQLを使っています。Prismaでアクセスしています。
認証にはNextAuth.jsを使っています。セッション管理は...
（100行以上の背景情報）

# ✅ 正しい設計
# Tech Stack
- Frontend: Next.js 14 (App Router) + TypeScript
- Backend: Node.js + Express
- DB: PostgreSQL (Prisma)
- Auth: NextAuth.js

# Rules
- Diagnose before fixing
- Smallest change only

原則2: 必須の3ルールを書く

海外上級者が口を揃えて言う3つのルールがあります。

# Development Rules

1. **Diagnose before fixing** — コードを触る前に必ず診断のみ行う
2. **Smallest change only** — 問題を解決する最小限の変更のみ行う
3. **Ask when unclear** — 不明点があれば推測せず必ず確認する

この3行で「AIが暴走する」問題の90%が解消されます。

特に重要なのは1番目です。

バグを報告する際、CLAUDE.mdにこのルールがないと：

Claude Codeが原因を理解しないまま修正を開始
表面的な修正で一時的に動く
数時間後に同じバグが再発

このサイクルに陥っている人は非常に多いです。

原則3: プロジェクトタイプを明示する

CLAUDE.mdの冒頭でプロジェクトの種類を明示することで、Claude Codeの回答が最適化されます。

Webアプリ向けの例

# Project: Web Application

## Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS
- DB: PostgreSQL via Prisma ORM
- Auth: NextAuth.js v5
- Deployment: Vercel

## Code Style
- Use Server Components by default
- Client Components only when necessary (state, effects, browser APIs)
- Always use TypeScript strict types, no `any`
- Prefer named exports over default exports

APIサーバー向けの例

# Project: REST API Server

## Tech Stack
- Runtime: Node.js 20
- Framework: Express + TypeScript
- DB: PostgreSQL (Prisma)
- Auth: JWT (access + refresh token)
- Testing: Vitest

## Rules
- Always validate request body with Zod
- Never expose internal errors to client responses
- Log errors with context (userId, requestId)

原則4: 禁止事項を明示する

「やってほしいこと」だけでなく「やってはいけないこと」を書くと効果が大幅に上がります。

## Prohibited Actions

- NEVER modify .env files
- NEVER use `any` type in TypeScript
- NEVER run database migrations without explicit confirmation
- NEVER push directly to main branch
- NEVER install new packages without asking first

特に .env への書き込み禁止は必ず入れるべきです。

Hooksと組み合わせると、AIが .env を触ろうとした瞬間に自動でブロックできます（後述）。

原則5: コンテキスト管理の指示を入れる

## Context Management

- Run /compact when context usage reaches 30%
- Start a new session when switching between major features
- Always mention the current file path when asking about specific code

30%ルール：コンテキストが30%消費された時点で /compact を実行する。

なぜ30%なのか？

70%以上が消費されると、Claude Codeは「忘れながら」答え始めます。早めにコンパクトすることで品質を維持できます。

原則6: ワークフローを定義する

よく行う作業のフローをCLAUDE.mdに書いておくと、毎回説明する必要がなくなります。

## Workflows

### Bug Fix Flow
1. "Diagnose only — do NOT fix yet"
2. Review the diagnosis
3. "Now implement the fix"
4. Run tests

### Feature Development Flow
1. /plan → review the plan
2. "Implement the plan"
3. /review
4. /test

### Code Review Flow
1. /review → prioritize issues
2. Fix high-priority issues first
3. /review again to confirm

原則7: 定期的に見直す

CLAUDE.mdは一度書いたら終わりではありません。

2週間に1回のレビューを推奨：

## CLAUDE.md Maintenance

Last reviewed: 2026-05-26
Review schedule: Every 2 weeks

Questions to ask:
- Are these rules actually being followed?
- Any rules that are no longer needed?
- Any new patterns that should be added?

ルールが実際に機能しているかを定期確認することで、CLAUDE.mdが「形骸化」するのを防げます。

完成形のサンプル（Web App用）

# Project: [Your App Name]

## Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript strict
- DB: PostgreSQL (Prisma)
- Auth: NextAuth.js
- Deployment: Vercel

## Development Rules
1. Diagnose before fixing — do NOT touch code first
2. Smallest change that solves the problem only
3. Ask when unclear — never assume

## Prohibited
- NEVER modify .env files
- NEVER use `any` type
- NEVER run migrations without confirmation

## Context Management
- Run /compact at 30% context usage
- New session when switching major features

## Code Style
- Server Components by default
- Named exports preferred
- Zod for all external input validation

これで150行以内に収まる、実用的なCLAUDE.mdの完成です。

まとめ

原則	ポイント
1. 長さ	50〜150行。200行超はNG
2. 必須3ルール	diagnose / smallest / ask
3. プロジェクト明示	Tech Stackを冒頭に書く
4. 禁止事項	.env保護・型制約など
5. コンテキスト管理	30%ルールを明記
6. ワークフロー	よく使うフローを定義
7. 定期見直し	2週間ごとのレビュー

無料テンプレートを配布中

7種類のCLAUDE.mdテンプレートを無料公開しています。

GitHub（無料）:
https://github.com/noguso245-jpg/claude-code-starter

Webアプリ用テンプレート1種 + Hooksサンプル + 30分セットアップガイドが含まれます。

BOOTH（完全版 ¥9,800）:
https://streamsolty.booth.pm/items/8413724

CLAUDE.mdテンプレート 7種
実行可能スキル 53本
Hooks完全設定（.env保護・コスト管理・lint自動実行）
MCPスタック設定 3種
カスタムコマンド 10本

7日間全額返金保証。まずGitHubの無料版を試してから判断してください。

X（最新情報・Tips）: @k___n___t_1125