0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@StreamSolty

Claude CodeのCLAUDE.md設計完全ガイド — 上級者が実践する7つの原則

0
Posted at

Claude Codeを使い始めたけど「なんか思ったより賢くない」と感じたことはありませんか？

その原因はほぼ確実にCLAUDE.mdの設計にあります。

この記事では、海外上級者が実践しているCLAUDE.mdの設計原則を、実際のサンプルコードとともに解説します。

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にこのルールがないと：

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

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

原則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

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?