注目 Configuration Troubleshooting CLAUDE.md Best Practices

CLAUDE.md アンチパターン：生産性を台無しにする12の間違い

開発者をイライラさせ、時間を浪費する最も一般的な CLAUDE.md の間違いを避けましょう。Claude Code を軌道に戻すトラブルシューティングテクニックを学びます。

2026年1月14日 • 12 min read • 著者：Claude World

悪い CLAUDE.md は、CLAUDE.md がないよりも悪いことがあります。設定が助けにならず対立すると、すべてのやり取りがストレスになります。

このガイドでは、私たちが見てきた最も一般的な12のアンチパターン、それらが発生する理由、そして修正方法を説明します。また、問題が発生した際のトラブルシューティングテクニックも紹介します。

パート1：12のアンチパターン

アンチパターン1：小説

症状： CLAUDE.md が500行以上で、考えついたすべてのルールが含まれている。

どう見えるか：

# CLAUDE.md (847行)

## コードスタイル (217行)
- 変数には camelCase を使用
- クラスには PascalCase を使用
- 定数には SCREAMING_SNAKE_CASE を使用
- ファイル名には kebab-case を使用
- タブではなく2スペースでインデント
- 1行最大100文字
- 常にセミコロンを使用
- let より const を優先
- var は絶対使わない
... (さらに200行以上)

なぜ問題か： Claude は毎セッションこのすべてのコンテキストを処理する必要があります。ほとんどは Claude がすでに知っている一般的なアドバイスです。トークンを無駄にし、重要な部分を見落とす可能性があります。

修正方法：

# コード標準
標準的な TypeScript の慣例に従う。特定のオーバーライド：
- 4スペースインデント（2ではなく）
- セミコロンなし（Prettier が処理）
- 1行最大80文字

詳細は @.eslintrc.js と @.prettierrc を参照。

経験則： linter/formatter の設定でカバーされている場合、CLAUDE.md で繰り返さない。

アンチパターン2：過保護な親

症状： すべてのアクションに確認が必要。Claude が常に許可を求める。

どう見えるか：

# 権限
- ファイルを読む前に確認
- ファイルを書く前に確認
- コマンドを実行する前に確認
- 変更を加える前に確認
- 仮定せず、常に確認

なぜ問題か： 生産性が破壊されます。実際の作業よりもアクションの承認に多くの時間を費やすことになります。

修正方法：

# 自律操作（確認不要）
- プロジェクト内のすべてのファイルを読む
- src/、tests/、docs/ でファイルを作成/変更
- 実行：npm test、npm run lint、npm run build
- ローカル git ブランチを作成
- devDependencies をインストール

# 確認が必要
- 本番依存関係をインストール
- .env や設定ファイルを変更
- リモートにプッシュ
- ファイルを削除
- データベースマイグレーションを実行

settings.json で細かく制御：

{
  "permissions": {
    "allow": ["Read", "Write(src/**)", "Bash(npm run:*)"],
    "deny": ["Write(.env*)", "Bash(rm -rf:*)"]
  }
}

アンチパターン3：ゴーストタウン

症状： CLAUDE.md は存在するが、有用なことがほとんど書かれていない。

どう見えるか：

# CLAUDE.md

これは React プロジェクトです。

なぜ問題か： Claude はすべてを推測しなければならない - 慣例、技術スタック、好み。毎セッションがゼロからのスタートです。

修正方法： 最低限含める：

# プロジェクト概要
Next.js 14 App Router、PostgreSQL、Stripe を使用した EC プラットフォーム。

# 技術スタック
- Next.js 14（App Router）
- TypeScript（strict モード）
- Prisma + PostgreSQL
- Tailwind CSS
- Vitest でテスト

# コマンド
- npm run dev     # 開発サーバー起動（ポート3000）
- npm test        # テスト実行
- npm run lint    # コード品質チェック

# ディレクトリ構造
src/
├── app/          # Next.js ルートとページ
├── components/   # 共有 React コンポーネント
├── lib/          # ユーティリティ関数
└── services/     # ビジネスロジック

アンチパターン4：コピペスペシャル

症状： 他人の CLAUDE.md を理解や適応なしにコピーした。

どう見えるか：

# どこかのチュートリアルから
- Rust の所有権モデルを使用
- Elm アーキテクチャに従う
- pytest でテスト

# 実際のプロジェクト：React + TypeScript

なぜ問題か： 矛盾した、または無関係な指示が Claude を混乱させます。プロジェクトに合わないルールを適用する可能性があります。

修正方法： 最初から始める。これらの質問に答える：

  1. このプロジェクトは何をするか？
  2. 技術スタックは何か？
  3. 必須のコマンドは何か？
  4. 自分の具体的な慣例は何か？
  5. どの操作を保護する必要があるか？

他人のテンプレートではなく、自分の答えから CLAUDE.md を構築する。

アンチパターン5：タイムカプセル

症状： CLAUDE.md が何ヶ月も更新されていない。非推奨のパターンや古い技術を参照している。

どう見えるか：

# 最終更新：2024-03-15

## データベース
MongoDB と Mongoose モデルを使用。

# （6ヶ月前に PostgreSQL に移行済み）

なぜ問題か： Claude は古い指示に従い、現在のアーキテクチャに合わないコードを作成します。

修正方法： レビューをスケジュール：

# CLAUDE.md
最終更新：2026-01-14
バージョン：3.2

## レビュートリガー
- [ ] 主要機能完了後
- [ ] 技術スタック変更時
- [ ] チームメンバー参加/離脱時
- [ ] 月次レビュー（毎月1日）

## 最近の変更
- 3.2：MongoDB から PostgreSQL へ移行
- 3.1：API バリデーション要件を追加
- 3.0：Claude Code v2.0 用に再構築

アンチパターン6：矛盾製造機

症状： CLAUDE.md の異なる部分が矛盾した指示を出している。

どう見えるか：

# テスト
すべての機能にユニットテストが必要。
90%カバレッジを目指す。

...

# 高速イテレーション
ラピッドプロトタイピングではテストをスキップ。
テストで遅れないように。

なぜ問題か： Claude はどの指示に従うべきかわからない。動作が予測不能になります。

修正方法： 明示的な優先度と例外を使用：

# テスト（絶対）
すべての機能にユニットテストが必要。
新しいコードは最低80%カバレッジ。

**例外：**
- `_experimental` プレフィックスのファイル
- `scripts/` ディレクトリのスクリプト
- 明示的にテストをスキップするよう指示された場合

アンチパターン7：専門用語のジャングル

症状： CLAUDE.md が Claude の知らない内部用語や略語を使用している。

どう見えるか：

# ルール
- すべての PFR は QG3 を通過する必要がある
- サービスは BATS パターンに従う
- ゲートウェイ層には DTO を使用
- ACME エンドポイントの FE/BE パリティを確保

なぜ問題か： Claude は未知の用語を予測不能に解釈するか、完全に無視します。

修正方法： 用語を定義：

# 用語集
- PFR：Pull Feature Request（機能ブランチの呼び方）
- QG3：Quality Gate 3（テスト合格、カバレッジ >80%、lint エラーなし）
- BATS：Business-API-Transform-Store（サービス層パターン）
- DTO：Data Transfer Object（API 境界の型付きインターフェース）

# ルール
- すべての機能ブランチ（PFR）はマージ前に QG3 を通過する必要がある
- サービスは BATS パターンに従う：@docs/bats-pattern.md を参照

アンチパターン8：セキュリティシアター

症状： 印象的に聞こえるが、実際には意味のあるものを保護していないセキュリティルール。

どう見えるか：

# セキュリティ
- eval() は絶対使わない
- innerHTML を使わない
- すべての入力をサニタイズ
- パラメータ化クエリを使用

なぜ問題か： これらは Claude がすでに従っている一般的なルールです。コードベースの実際のセキュリティリスクは対処されていません。

修正方法： 実際のリスクに焦点を当てる：

# セキュリティ（プロジェクト固有）

## 決済処理（src/services/payment/）
- すべての Stripe API 呼び出しは lib/stripe.ts のラッパーを使用
- 完全なカード番号をログに記録しない（下4桁のみ）
- PCI コンプライアンス：エラーメッセージにカードデータなし

## 認証（src/services/auth/）
- JWT シークレットは環境変数からのみ
- トークン有効期限：15分（アクセス）、7日（リフレッシュ）
- レート制限：5回の失敗 = 15分ロックアウト

## データ処理
- PII フィールド（email、name、address）は静的時に暗号化
- ユーザー入力には lib/security.ts の sanitize() ヘルパーを使用

アンチパターン9：マイクロマネージャー

症状： 指示が具体的すぎて、Claude がエッジケースに適応できない。

どう見えるか：

# エラー処理
1. まずネットワークエラーかどうかチェック
2. ネットワークエラーなら「ネットワークエラーが発生しました」と表示
3. ネットワークエラーでなければ、バリデーションエラーかチェック
4. バリデーションエラーなら、フィールド固有のメッセージを表示
5. バリデーションエラーでなければ、認証エラーかチェック
6. 認証エラーなら /login にリダイレクト
7. それ以外は「エラーが発生しました」と表示

なぜ問題か： 実際のエラーはより複雑です。この硬直したフローチャートは最初の予期しないケースで壊れます。

修正方法： 手順ではなく原則を示す：

# エラー処理の原則
- ユーザー向けエラー：技術的な詳細なしの親切なメッセージ
- 開発者エラー：開発モードでは完全なスタックトレース
- ネットワークエラー：リトライを提案、可能ならオフラインモードを提供
- 認証エラー：ログインにリダイレクト、リターン URL を保持
- React エラー処理には ErrorBoundary コンポーネントを使用
- すべてのエラーをモニタリングにログ（lib/monitoring.ts 参照）

## エラーレスポンス形式
{ error: string, code: string, details?: object }
完全な型定義は @src/types/errors.ts を参照。

アンチパターン10：希望的観測

症状： CLAUDE.md が実際の動作ではなく、希望する動作を記述している。

どう見えるか：

# アーキテクチャ
明確な分離を持つクリーンアーキテクチャに従う：
- Domain 層：純粋なビジネスロジック
- Application 層：ユースケース
- Infrastructure 層：外部サービス
- Presentation 層：UI コンポーネント

# （現実：すべてが components/ にあり、分離なし）

なぜ問題か： Claude は理想のアーキテクチャ用のコードを書き、実際のコードベースには合いません。新しいコードがフィットしません。

修正方法： 現状について正直に：

# アーキテクチャ（現状）
ほとんどのロジックが React コンポーネント内。徐々に抽出中：
- ビジネスロジック → src/services/（進行中）
- API 呼び出し → src/lib/api.ts（完了）
- 共有型 → src/types/（完了）

# アーキテクチャ（目標状態）
最終目標は @docs/target-architecture.md を参照。

# マイグレーションルール
- 新機能：services 層を使用
- バグ修正：既存のコンポーネントロジックを変更してOK
- リファクタリング：ファイルを触る際に services に抽出

アンチパターン11：ワンサイズフィットオール

症状： コンテキストに関係なく、同じルールがすべてに適用される。

どう見えるか：

# 標準
- 100%テストカバレッジ
- 完全な JSDoc ドキュメント
- 包括的なエラー処理
- パフォーマンス最適化

なぜ問題か： すべてに同じ厳格さが必要なわけではありません。プロトタイプコードと本番コードには異なるニーズがあります。

修正方法： コンテキスト対応ルールを使用：

# コンテキスト別の標準

## 本番コード（src/services/、src/lib/）
- 最低90%テストカバレッジ
- すべてのパブリック API に JSDoc
- 型付きエラーで完全なエラー処理
- ホットパスのパフォーマンスプロファイリング

## UI コンポーネント（src/components/）
- 70%テストカバレッジ
- Props ドキュメント必須
- ページレベルのエラーバウンダリ

## スクリプト＆ツール（scripts/、tools/）
- テストは任意
- 最小限のドキュメント
- ハッピーパスにフォーカス

## 実験（src/_experimental/）
- カバレッジ要件なし
- 2週間以内に削除または昇格

アンチパターン12：サイロ

症状： チームメンバーがそれぞれ異なる CLAUDE.md ファイルを持ち、標準が矛盾している。

どう見えるか：

# Alice の CLAUDE.md：「状態管理に Redux を使用」
# Bob の CLAUDE.md：  「状態管理に Zustand を使用」
# Carol の CLAUDE.md：「状態管理に React Query を使用」

なぜ問題か： コードが一貫性を失います。PR にスタイルの衝突があります。オンボーディングが混乱します。

修正方法： 層の階層を正しく使用：

.claude/CLAUDE.md          # 共有チーム標準（コミット済み）
CLAUDE.local.md            # 個人の好み（gitignore）
~/.claude/CLAUDE.md        # グローバル個人設定

チーム合意：

# .claude/CLAUDE.md（チームバージョン）
## 状態管理
- サーバー状態：React Query
- クライアント状態：Zustand
- フォーム状態：React Hook Form

## 個人の好み
個人のオーバーライドには CLAUDE.local.md を使用。
チームの議論なしに共有 CLAUDE.md を変更しない。

パート2：トラブルシューティングガイド

問題：Claude が CLAUDE.md を無視する

チェック1：ファイルの場所

# 正しい場所：
./CLAUDE.md              # プロジェクトルート
./.claude/CLAUDE.md      # 隠しディレクトリ

チェック2：ファイルが読まれているか Claude に聞く：「CLAUDE.md からどの指示に従っていますか？」

チェック3：優先度の競合

優先度：CLAUDE.local.md > ./CLAUDE.md > ~/.claude/CLAUDE.md

ローカルオーバーライドがプロジェクトルールを隠している可能性があります。

問題：Claude が常に許可を求める

チェック1：権限設定

// .claude/settings.json
{
  "permissions": {
    "allow": ["Read", "Write", "Edit", "Bash(npm:*)"]
  }
}

チェック2：CLAUDE.md の矛盾した指示 「常に確認」や「事前に確認」などのフレーズを探して削除。

チェック3：企業の制限 組織内の場合、/etc/claude-code/settings.json の企業ポリシーをチェック。

問題：Claude が間違った慣例を使用する

チェック1：慣例が明示的か

# ダメ：
標準的な React パターンを使用。

# 良い：
## React パターン
- 関数コンポーネントのみ
- 名前付きエクスポート（default ではない）
- Props インターフェースは [ComponentName]Props と命名
- 共有フックは別ファイルに

チェック2：例が提供されているか

## コンポーネントテンプレート
標準構造は @src/components/_template.tsx を参照。

問題：Claude が以前のセッションを覚えていない

チェック1：Memory MCP が設定されているか

claude mcp add --scope project memory \
  -e MEMORY_FILE_PATH=./.claude/memory.json \
  -- npx -y @modelcontextprotocol/server-memory

チェック2：メモリファイルが存在し、読み取り可能か

cat .claude/memory.json

チェック3：メモリコマンドを使用しているか

  • /memory-save で重要なコンテキストを保存
  • /memory-search で以前の決定を思い出す

問題：settings.json が動作しない

チェック1：JSON が有効か

cat .claude/settings.json | jq .

チェック2：正しいプロパティ名

{
  "permissions": {
    "allow": [...],      // 小文字
    "deny": [...]        // 小文字
  },
  "enableAllProjectMcpServers": true,
  "ignorePatterns": [...]
}

チェック3：MCP サーバーの権限

claude mcp list
claude mcp reset-project-choices

問題：Rules ディレクトリが読み込まれない

チェック1：正しい構造

.claude/
├── CLAUDE.md
└── rules/
    ├── code-style.md
    └── testing.md

チェック2：Claude Code バージョン パス固有のルールには v2.0.20+ が必要：

claude --version

チェック3：フロントマターの構文

---
paths: src/api/**/*.ts
---

API ファイルのルール...

クイックリファレンス：CLAUDE.md ヘルスチェック

毎月このチェックリストを実行：

## CLAUDE.md ヘルスチェック

### 長さ
- [ ] 200行以下
- [ ] 冗長な情報なし
- [ ] 詳細は rules/ に抽出済み

### 明確さ
- [ ] 定義なしの専門用語なし
- [ ] 具体的で実行可能なルール
- [ ] 必要に応じて例を提供

### 正確さ
- [ ] 現在の技術スタックに一致
- [ ] 実際のアーキテクチャを反映
- [ ] 矛盾なし

### 権限
- [ ] 自律操作が定義されている
- [ ] 本当にリスクのある操作のみ確認が必要
- [ ] settings.json が正しく設定されている

### メンテナンス
- [ ] 最終更新日がある
- [ ] 変更履歴を維持
- [ ] レビュースケジュールを設定

まとめ

最高の CLAUDE.md ファイルにはこれらの特徴があります：

  • 簡潔： 200行以下、ユニークな内容に焦点
  • 正直： 願望ではなく現実を記述
  • 具体的： 曖昧な原則ではなく実行可能なルール
  • 階層的： 階層（グローバル、プロジェクト、ローカル）を使用
  • メンテナンス： プロジェクトの進化に合わせて定期的に更新

トラブルシューティング時は、常に確認：

  1. ファイルは正しい場所にあるか？
  2. 優先度の競合はないか？
  3. 指示は十分に明示的か？
  4. バージョンの不一致はないか？

素晴らしい CLAUDE.md はすべてを制御しようとしない - Claude が良い決定を下すのに十分なガイダンスを提供するだけです。

出典：Claude Code ドキュメント、Claude Code GitHub