Claude の乱コードを止める！設定ファイル 1 つで AI 精度が 10% 向上

既存プロジェクトを Claude Code で直しているのに、技術スタックが別物扱いになる——React プロジェクトなのに Vue っぽいコード、ドキュメントは TypeScript なのに JavaScript が量産される。CLAUDE.md はプロジェクトルートに置く、こうした「コンテキストのズレ」を防ぐための設定ファイルです。

Node バックエンドで痛い目に遭いました。Claude が Koa ベースのミドルウェアを Express で書き直し、パイプライン全体が動かなくなった。Anthropic のテストでは、CLAUDE.md をきちんと書くとコーディング精度が 5%〜10% 上がることが多い。以下 7 つの書き方は、私が踏み抜いた穴から整理したもので、どれもそのまま使える例付きです。

CLAUDE.md とは何か

要するに、CLAUDE.md はプロジェクトルートの Markdown ファイルで、Claude Code にプロジェクトを理解させるためのものです。.editorconfig や README.md に似ていますが、役割はもっと具体的——AI にどうコードを書かせるかを指示します。

仕組みはシンプル：プロジェクト内で Claude Code を使うと、このファイルが自動読み込みされます。公式は自動ロードと言いますが、コミュニティの経験では /init で明示的に読み込ませ、AI が設定を「理解した」状態にするのが確実です。内容は AI のコンテキストメモリに載り、以降のコード生成と提案すべてに効きます。

重要なのが 階層設定 への対応です：

project-root/
├── CLAUDE.md              # グローバル設定（プロジェクト全体）
├── frontend/
│   └── .claude/
│       └── CLAUDE.md     # フロントエンド固有
└── backend/
    └── .claude/
        └── CLAUDE.md     # バックエンド固有

ルートで共通規約を定義し、サブモジュールで上書きできます。フロントは React、バックエンドは Node.js——それぞれ別設定を維持するイメージです。

4 つの核心原則

CLAUDE.md を書く前に、この 4 つを覚えておいてください。最初は気にせず 300 行超の「大作」を書き、Claude の精度が落ちた経験があります。

1. 簡潔性：100 行以内

これは痛い目で学んだ教訓です。CLAUDE.md は README ではない。長文は不要。

なぜ短く？ Claude のコンテキストウィンドウは大きいですが、CLAUDE.md はトークンクォータを食います。長いほど、実コード分析に回せるトークンが減る。Arize AI の研究では 100 行以内が最も効果的です。

❌ 悪い例（冗長・重複）：

# プロジェクト概要
これは React ベースのフロントエンドプロジェクトです。ユーザーインターフェースを構築するために React を使用しています。
React は Facebook によって開発された JavaScript ライブラリであり...（React 紹介が 200 字続く）
# 技術スタック
我々の技術スタックには以下が含まれます：
- React - これは我々の UI フレームワークであり、バージョンは 18.2 です...
- TypeScript - タイプチェックを行うために使用します...

✅ 良い例（簡潔・直接）：

# 技術スタック
- React 18.2 (Hooks 優先、Class コンポーネント回避)
- TypeScript (Strict モード)
- TailwindCSS (utilities 優先)
# コード規約
- 関数コンポーネント + カスタム Hooks
- Props 分割代入
- const を優先、let は避ける

違いがわかりますか？ 2 つ目は 60 文字程度で、同じかそれ以上の情報を伝えています。

2. 具体性：曖昧さを捨て、実行可能に

シンプルに聞こえますが、ここでつまずきやすい。

❌ 悪い例（曖昧）：

# コードスタイル
- コードを簡潔に保つ
- ベストプラクティスを使用する
- パフォーマンス最適化に注意する

これは書いていないのと同じ。「簡潔」とは？「ベストプラクティス」とは？ AI は実行できません。

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

✅ 良い例（具体的・検証可能）：

# コードスタイル
- 単一関数は 50 行以内。超えたら分割
- API 呼び出しには必ずエラー処理と loading 状態
- リストレンダリングには key を付与。index ではなく ID を使う
- ネスト三項演算子は避け、if/else か早期 return に

これで AI は何をすべきかわかります。各ルールは明確で検証可能。

3. 反復性：恐れず更新する

プロジェクト初期に CLAUDE.md を書いて半年放置——Vue 2 から Vue 3 に移行したのに、設定にはまだ「Options API を使う」と残っている、という例をよく見ます。

# キーで素早く更新：Claude Code 内で # を押すと CLAUDE.md をすぐ参照・編集できます。AI の挙動がおかしいと感じたら、その場で直す。先延ばしにしない。

実例：先週、Claude が axios でコードを生成し続けました。チームは fetch + 独自ラッパーに統一済み。# で CLAUDE.md に 1 行追加：

# HTTP リクエスト
- `src/utils/request.ts` でラップした fetch を統一利用
- axios や生 fetch の直接使用は禁止

保存後、このミスは再発しませんでした。

4. チーム共有：バージョン管理に入れる

見落とされがちですが、CLAUDE.md は Git にコミットする。.gitignore と同じくらい重要。

設定はチームのコーディング合意の表れです。メンバーごとに CLAUDE.md が違えば、AI が生成するコードのスタイルもバラバラになります。

# .gitignore で CLAUDE.md を無視しない
# ❌ 間違い
*.md
# ✅ 正解
*.md
!CLAUDE.md
!README.md

Code Review でも CLAUDE.md の変更を確認しましょう。誰かが直したら、チーム全員が知る必要があります。

"設定ファイルは簡潔かつ具体的に。100 行以内が最も効果的。各ルールは実行可能で検証可能であること。"

必須 5 つのコンテンツモジュール

最小限の有効設定としてまとめたものです。これらが欠けると CLAUDE.md はほぼ役に立ちません。

1. 技術スタック宣言

フレームワーク、ライブラリ、バージョンを明示。これが土台です。

# 技術スタック
**フロントエンド**
- Next.js 14 (App Router)
- React 18 (Server Components 優先)
- TypeScript 5.2
- Tailwind CSS 3.4
**バックエンド**
- Node.js 20 LTS
- Express 4.18
- Prisma ORM
- PostgreSQL 15

バージョン番号を書いている点に注目。未指定だと Claude は古い API でコードを書く可能性があります。Next.js 13 と 14 ではルーティングの書き方がまったく違う——バージョン指定は必須です。

2. プロジェクト構造の説明

ファイルの置き方を伝え、コードを正しい場所に置かせます。

# プロジェクト構造
src/
├── app/              # Next.js ページルート
├── components/       # 再利用 UI コンポーネント
│   ├── ui/          # 基礎コンポーネント (Button, Input)
│   └── features/    # 業務コンポーネント (UserCard, OrderList)
├── lib/             # ユーティリティと hooks
├── services/        # API 呼び出し層
└── types/           # TypeScript 型定義
# ファイル命名
- コンポーネント：PascalCase (UserProfile.tsx)
- ユーティリティ：camelCase (formatDate.ts)
- 定数：UPPER_SNAKE_CASE (API_BASE_URL)

これがあれば、ユーザーカードコンポーネントは components/features/UserCard.tsx に置くべきだと Claude もわかります。

3. よく使うコマンド

見落とされがちですが、非常に有用です。

# 開発コマンド
npm run dev          # 開発サーバー (localhost:3000)
npm run build        # 本番ビルド
npm run test         # Jest テスト
npm run lint         # ESLint
npm run type-check   # TypeScript 型チェック
# データベース
npx prisma studio    # DB GUI
npx prisma migrate dev  # マイグレーション

Claude がコード検証やテスト実行をするとき、正しいコマンドを知っているとトラブルが減ります。

4. コードスタイル規約

ここが本丸。十分に具体的に。

# コード規約
## React コンポーネント
- 関数コンポーネント + Hooks。Class コンポーネント禁止
- Props 型はコンポーネント直上、interface を使う（type ではない）
- 内部順序：Props 定義 → コンポーネント関数 → export
## 状態管理
- ローカル：useState/useReducer
- サーバー：TanStack Query
- グローバル：Zustand（Context は避ける）
## エラー処理
- API 呼び出しは try-catch 必須
- ユーザー向けエラーは toast
- 開発は console.error、本番は Sentry へ

5. ワークフローと制限

何をしてよく、何をしてはいけないか。

# ワークフロー
- 新機能：型定義 → コンポーネント → テスト
- バグ修正：再現テスト → 修正 → テスト通過確認
# 制限事項
- ❌ `/prisma/schema.prisma` を変更しない（チームレビュー必須）
- ❌ 新規依存をインストールしない（package.json レビューで議論）
- ❌ `/lib/auth/*` を変更しない（認証はセンシティブ）
- ✅ `/components` と `/app` 下の業務コードは自由に変更可

AI の「親切心」で重要コードを壊すのを防げます。

効果を倍にする 7 つの実践テクニック

テクニック 1：SHOULD/MUST で優先度を示す

すべてのルールが同じ重要度ではありません。

# 規約優先度
**MUST（必須）**
- MUST TypeScript Strict モード
- MUST すべての API にエラー処理
**SHOULD（推奨）**
- SHOULD コンポーネント 200 行以内
- SHOULD 重複ロジックはカスタム Hook へ
**COULD（任意）**
- COULD JSDoc コメント

RFC 仕様書の書き方に由来します。導入後、Claude は「MUST」への遵守が明らかに厳しくなります。

KiloClaw - 企業向けマネージド OpenClaw、AI エージェントのオーケストレーションとスマートルーティングを加速

今すぐ始める →広告

テクニック 2：/init コマンドを使う

自動ロードと言われますが、プロジェクトを開くたび /init を実行することを強く推奨します。

あなた：/init
Claude：プロジェクト設定を読み込みました。現在の技術スタック：React 18 + TypeScript...

AI の記憶をリフレッシュするイメージです。CLAUDE.md を直した直後は /init で即反映。

テクニック 3：言葉よりサンプルコード

規約を長文で説明するより、例を示す方が速い。

❌ テキストのみ：

- API 関数には型定義、エラー処理、loading 状態が必要

✅ サンプル付き：

# API 呼び出し規約
参考例：
\`\`\`typescript
// src/services/user.ts
export async function getUser(id: string): Promise<User> {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) throw new Error('Failed to fetch user');
    return await response.json();
  } catch (error) {
    console.error('getUser error:', error);
    throw error;
  }
}
\`\`\`
すべての API 関数はこのパターン：型付き戻り値 + try-catch + エラーログ

例を見せると、生成コードが期待にかなり近づきます。

テクニック 4：階層設定（Monorepo 必須）

Monorepo なら階層設定は必須です。

monorepo-root/
├── CLAUDE.md                    # グローバル：共通規約、Git ワークフロー
├── apps/
│   ├── web/
│   │   └── .claude/CLAUDE.md   # Web：React + Next.js
│   └── mobile/
│       └── .claude/CLAUDE.md   # モバイル：React Native
└── packages/
    └── shared/
        └── .claude/CLAUDE.md   # 共有パッケージ：純 TS ユーティリティ

ルート CLAUDE.md（グローバル）：

# Monorepo 共通規約
- パッケージマネージャーは pnpm
- TypeScript 設定はルート tsconfig.json を継承
- コミットは Conventional Commits
# ワークフロー
- コード修正前に `pnpm install`
- コミット前に `pnpm run lint` で全パッケージチェック

apps/web/.claude/CLAUDE.md（フロント専用）：

# Web アプリ固有
ルート規約を継承。追加設定：
- 技術スタック：Next.js 14 + React 18
- スタイル：Tailwind CSS
- 状態管理：Zustand

Claude はルートを先に読み、作業ディレクトリに応じてサブ設定を読みます。各サブプロジェクトで共通規約を繰り返す必要がありません。

テクニック 5：❌ と ✅ で対比

人も AI も対比学習が効きます。

# 状態更新規約
❌ 誤り：state を直接変更
\`\`\`typescript
const [user, setUser] = useState({name: 'John', age: 30});
user.age = 31; // オブジェクトを直接変更している
\`\`\`
✅ 正解：イミュータブル更新
\`\`\`typescript
const [user, setUser] = useState({name: 'John', age: 30});
setUser(prev => ({...prev, age: 31}));
\`\`\`

ルールが一目でわかり、Claude の学習効率も上がります。

テクニック 6：よくあるエラーパターンを記録

チームがよく犯すミスを書き、AI にチェックさせる。

# ⚠️ よくある間違いと回避
## 1. 副作用のクリーンアップ忘れ
❌ 問題コード：
\`\`\`typescript
useEffect(() => {
  const timer = setInterval(() => {/* ... */}, 1000);
  // クリーンアップなし！
}, []);
\`\`\`
✅ 正しいやり方：
\`\`\`typescript
useEffect(() => {
  const timer = setInterval(() => {/* ... */}, 1000);
  return () => clearInterval(timer);
}, []);
\`\`\`
## 2. 依存配列の欠落
ESLint が依存不足を警告したら、警告を無効化せず依存を追加するか useCallback/useMemo で最適化

Claude が生成時にこれらの穴を自発的に避けやすくなります。

テクニック 7：詳細ドキュメントへリンク

CLAUDE.md は短く保ちつつ、詳細はリンクで。

# 詳細規約
- [API 設計規約](./docs/api-guidelines.md) - RESTful API 標準
- [コンポーネント開発ガイド](./docs/component-guide.md) - 分割と再利用
- [テスト規約](./docs/testing.md) - 単体・統合テスト要件

簡潔さを保ちながら、必要時に Claude が追加コンテキストを取れます。

最も陥りやすい 5 つの落とし穴

落とし穴 1：長すぎて全部詰め込む

README、API ドキュメント、業務ロジックまで CLAUDE.md に入れる——初心者がよくやります。
問題：トークンを食い、重要情報が薄まる。
対策：100 行以内に厳守。AI コーディングに本当に必要な情報だけ。

落とし穴 2：更新しない

プロジェクトは変わるのに CLAUDE.md は固定。
問題：古い設定で誤コードが量産される。
対策：大規模リファクタのたびに更新。PR で設定変更もレビュー。

落とし穴 3：バージョン管理を忘れる

.gitignore に入れる、またはコミットしない。
問題：メンバーごとにスタイルがバラバラ。
対策：必ず Git に含め、コードと一緒にレビュー。

Alibaba Cloud - 開発者向けクラウドの第一候補、Lighthouse サーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

落とし穴 4：ルールが抽象的すぎる

「コードを簡潔に」「ベストプラクティスに従う」——空虚な一文。
問題：AI は実行できず、未記載と同じ。
対策：各ルールは具体的・検証可能・実行可能に。

落とし穴 5：機密情報の漏洩

API キーや DB パスワードを CLAUDE.md に書く。
問題：設定はリポジトリに入るため漏洩リスク。
対策：設定の方法だけ書き、具体値は書かない。

❌ 誤り
\`\`\`markdown
# データベース設定
DATABASE_URL=postgresql://admin:password123@localhost:5432/mydb
\`\`\`
✅ 正解
\`\`\`markdown
# 環境変数
- DATABASE_URL: .env.local から読み込み。形式は .env.example 参照
- API_KEY: 環境変数から取得。ローカル開発は @田中 に連絡してテストキーを取得
\`\`\`

3 つの実プロジェクト事例

事例 1：React フロントエンド

現在メンテ中の EC フロント設定（簡略版）：

# EC フロントエンド
## 技術スタック
- Next.js 14.0 (App Router)
- React 18.2
- TypeScript 5.2
- Tailwind CSS 3.4
- Zustand (状態管理)
- TanStack Query (サーバー状態)
## プロジェクト構造
src/
├── app/          # ページルート
├── components/   # コンポーネント
│   ├── ui/      # 基礎
│   └── features/ # 業務
├── lib/         # ユーティリティ
└── services/    # API
## コード規約
- コンポーネント：関数 + Hooks
- 状態：ローカル useState、グローバル Zustand、サーバー TanStack Query
- スタイル：Tailwind utilities。複雑レイアウトはコンポーネント化
- エラー：API は try-catch 必須
## コマンド
npm run dev      # 開発サーバー
npm run build    # 本番ビルド
npm run lint     # リント
## 制限
- /lib/auth/* は変更しない（認証）
- 新規パッケージはインストールしない（チーム議論）

効果：Claude が生成するコンポーネント構造が手書きに近づき、調整時間が大幅に減りました。

事例 2：Node.js バックエンド

Express API プロジェクトの設定：

# 注文管理 API
## 技術スタック
- Node.js 20 LTS
- Express 4.18
- Prisma ORM
- PostgreSQL 15
- Zod (検証)
## プロジェクト構造
src/
├── routes/       # ルート
├── controllers/  # 業務ロジック
├── services/     # DB 操作
├── middleware/   # ミドルウェア
└── utils/        # ユーティリティ
## コーディング規約
- すべての API：リクエスト検証 (Zod) + エラー処理 + ログ
- DB 操作は services 層に集約
- コントローラーは入出力のみ。業務ロジックは書かない
- async/await を使い、コールバックは避ける
## API 例
\`\`\`typescript
// controllers/order.controller.ts
export async function createOrder(req: Request, res: Response) {
  try {
    const data = orderSchema.parse(req.body);
    const order = await orderService.create(data);
    logger.info('Order created', { orderId: order.id });
    res.json({ success: true, data: order });
  } catch (error) {
    logger.error('Create order failed', error);
    res.status(500).json({ success: false, error: 'Internal error' });
  }
}
\`\`\`
## コマンド
npm run dev       # 開発 (nodemon)
npm run build     # TS コンパイル
npm test          # Jest
npx prisma studio # DB GUI

効果：生成 API に Zod 検証とエラー処理が付くようになり、品質が明らかに向上。

事例 3：Monorepo

フロントとバックエンドを含む Monorepo：

ルート CLAUDE.md：

# フルスタック Monorepo
## アーキテクチャ
- pnpm workspaces
- apps/: アプリケーション
- packages/: 共有パッケージ
## 共通規約
- TypeScript Strict
- ESLint + Prettier で統一
- Conventional Commits
## コマンド
pnpm install           # 全依存インストール
pnpm run dev           # 前後端同時起動
pnpm run lint          # 全パッケージチェック
pnpm --filter web dev  # web のみ起動

apps/web/.claude/CLAUDE.md：

# Web アプリ
ルート規約を継承
- Next.js 14 + React
- ポート：3000
- 詳細はルート CLAUDE.md 参照

apps/api/.claude/CLAUDE.md：

# API サービス
ルート規約を継承
- Express + Prisma
- ポート：4000
- 詳細はルート CLAUDE.md 参照

効果：作業ディレクトリに応じてコンテキストが切り替わり、フロントでは React、バックエンドでは Express コードが生成されます。

結論：今日から CLAUDE.md を最適化しよう

7 つのテクニックを読めば、良い CLAUDE.md の輪郭は見えているはず。覚えておくべき 3 点：

1. 簡潔に — 100 行以内、必要な情報だけ
2. 具体的に — 各ルールは実行可能・検証可能
3. 継続更新 — プロジェクトと一緒に設定も変える

経験上、良い CLAUDE.md は AI の作業効率を少なくとも 30% 上げます。一度に全部書く必要はありません。技術スタック宣言から始め、AI がミスするたびに 1 ルール追加すれば十分。

今すぐプロジェクトを開き、CLAUDE.md を作るか直しましょう。Claude Code をこれから使うなら、このファイルが第一歩。すでに使っているのに精度が足りないなら、今日のテクニックを試してください。

最後に：CLAUDE.md は一度きりの作業ではありません。大規模リファクタ、スタック更新、規約変更のたびに更新を。AI にプロジェクトを本当に理解させる——それは良い CLAUDE.md から始まります。