CLAUDE.md上級設計

モノレポでのCLAUDE.md戦略

モノレポ構成のプロジェクトでは、CLAUDE.mdの配置戦略が特に重要です。ルートには共通ルール、各パッケージには固有ルールを配置し、 Descendant Loading（下方向の遅延読み込み）を活用します。

重要な仕様として、兄弟ディレクトリのCLAUDE.mdは読み込まれない設計になっています。 たとえばfrontend/で作業中にbackend/CLAUDE.mdは読み込まれません。 これはコンテキストの肥大化を防ぐための意図的な設計です。 Skillsをサブフォルダに配置することで、必要なときだけ読み込まれる構造を実現できます。

my-monorepo/
  CLAUDE.md                    # 共通ルール（コミット規約、PR形式等）
  packages/
    frontend/
      CLAUDE.md                # React/Next.js固有のルール
      .claude/skills/          # フロントエンド用Skills
    backend/
      CLAUDE.md                # API設計・DB操作のルール
      .claude/skills/          # バックエンド用Skills
    shared/
      CLAUDE.md                # 共通ライブラリのルール

# Descendant Loading の動作:
# frontend/ で作業 → ルートCLAUDE.md + frontend/CLAUDE.md が読まれる
# backend/CLAUDE.md は読まれない（兄弟ディレクトリ）

.claude/rules/でルールを分離

CLAUDE.mdが肥大化してきたら、.claude/rules/ディレクトリにルールを分割します。 CLAUDE.md自体はインデックス（目次）として機能させ、詳細なルールは個別ファイルで管理します。

この分割により、トピックごとにルールを整理でき、チームメンバーが特定のルールを見つけやすくなります。 また、PRレビュー時にも「どのルールが変更されたか」が一目で分かります。

.claude/
  rules/
    coding-style.md       # コーディング規約
    testing.md            # テストのルール
    api-design.md         # API設計のガイドライン
    security.md           # セキュリティポリシー
    commit-message.md     # コミットメッセージ規約

# CLAUDE.md はインデックスとして機能
# 各ルールファイルへの参照を記述

<important if="...">タグ

CLAUDE.mdが長くなると、Claudeが特定のルールを無視する問題が発生します。 Dex氏が推奨する対策が、<important if="...">タグによる条件付きルール定義です。

このタグを使うことで、特定の条件下で確実にルールを遵守させることができます。 ドメイン固有の重要なルールや、見落とされがちな制約を強調するのに有効です。

# CLAUDE.md での使用例

<important if="editing files in src/api/">
APIエンドポイントを変更する場合は必ず以下を確認すること:
- OpenAPI specを更新
- バージョニングヘッダーを確認
- レートリミット設定を確認
</important>

<important if="creating new database migrations">
マイグレーションファイルには必ずロールバック処理を含めること。
本番環境でのロールバックが不可能な変更は禁止。
</important>

<important if="modifying authentication logic">
認証ロジックの変更は必ずセキュリティレビューを経ること。
トークンの有効期限は30分を超えてはならない。
</important>

Auto Memoryの活用と注意

Claude CodeにはAuto Memory機能があり、 作業中に学んだことを自動的に保存してくれます。 ビルドコマンド、デバッグ手順、発見したパターンなどが自動で記録され、 次回のセッションで活用されます。

便利な機能ですが、無制限に肥大化するリスクがあります。 定期的に保存された内容を確認し、不要な項目を削除してください。autoMemoryDirectory設定で保存先をカスタマイズすることもできます。

# Auto Memoryの保存先をカスタマイズ
# settings.json
{
  "autoMemoryDirectory": ".claude/memory"
}

# 保存された内容を確認
/memory

# Auto Memoryが保存する内容の例:
# - 「npm run build で正常にビルドできた」
# - 「このプロジェクトではpnpmを使用している」
# - 「テスト実行は npm test -- --watch で高速化できる」
# - 「ESLint設定でsemicolonはエラーになる」

settings.jsonとの明確な使い分け

CLAUDE.mdとsettings.jsonは役割が異なります。 この使い分けを間違えると、意図した動作にならない場合があります。

• settings.json — attribution（Co-Authored-By等）、permission（ツール権限）、sandbox設定。ハーネスが強制的に実行するもの
• CLAUDE.md — コーディング規約、設計方針、命名規則。文脈依存でAIが判断すべきもの

# settings.json に書くべき設定（ハーネスが強制実行）
{
  "permissions": {
    "allow": ["Edit(*)", "Bash(npm run *)"],
    "deny": ["Read(.env)"]
  },
  "attribution": {
    "enabled": true,
    "message": "Co-Authored-By: Claude"
  }
}

# CLAUDE.md に書くべき設定（AIが文脈判断）
# - コーディング規約
# - 設計パターンの選択基準
# - 命名規則
# - エラーハンドリング方針

月次レビュープロセス

CLAUDE.mdは一度書いたら終わりではありません。スプリントのレトロスペクティブで定期的に見直すことが重要です。 特にチーム開発では、「削除が追加より重要」という原則を意識してください。

CLAUDE.mdの変更はPRレビューで管理し、単独でのドリフト（勝手な変更）を防止します。 チーム全員が内容を理解し、変更に合意していることが品質維持の前提です。

• 毎月のレビュー — 不要になったルールを削除。追加より削除を優先
• PRレビュー必須 — CLAUDE.mdの変更は必ずPRを通す
• 単独ドリフト防止 — 個人が勝手に変更しない。チームで合意
• チーム署名 — レビュー完了後、チーム全員が内容を確認した記録を残す

200行以下の原則を実現する方法

CLAUDE.mdは200行以下に保つのが理想です。 これを実現するための具体的な方法を紹介します。

最も重要なのは、CLAUDE.mdをインデックス（目次）として使い、 詳細は外部ドキュメントにリンクすることです。コードベースから自明なこと（言語、フレームワーク等）は書きません。 「何をするか」よりも「何を避けるか」とその理由のペアで記述し、 抽象的な説明はコード例で置き換えます。

# 良い CLAUDE.md の例（200行以下）

## プロジェクト概要
ECサイトのバックエンドAPI。詳細は docs/architecture.md を参照。

## 禁止事項と理由
- any型の使用禁止 → 型安全性が崩れ、ランタイムエラーの原因になるため
- console.logでのデバッグ禁止 → 本番環境にログが残るため。loggerを使うこと
- 直接SQL禁止 → SQLインジェクションのリスク。必ずORMを経由

## コード例
```typescript
// 良い例: エラーハンドリング
const result = await userService.findById(id);
if (!result) throw new NotFoundException('User not found');

// 悪い例
const result = await db.query('SELECT * FROM users WHERE id = ' + id);
```

## 詳細リファレンス
- API設計: .claude/rules/api-design.md
- テスト規約: .claude/rules/testing.md
- セキュリティ: .claude/rules/security.md

コードベースをクリーンに保つ

Boris氏が強調するように、部分的にマイグレーションされたフレームワークはモデルを混乱させます。 たとえば「一部のコンポーネントはClass Components、一部はHooks」という状態や、 「一部のAPIはREST、一部はGraphQL」という混在状態は、AIの出力品質を著しく低下させます。

マイグレーションを始めたら完了させてください。中途半端な状態が最も危険です。 また、テスト実行が一発で通る状態を常に維持することも重要です。 テストが壊れた状態でClaude Codeに作業させると、壊れたテストを基準にして「正しい」コードを生成してしまう可能性があります。

Instruction Budgetを意識したCLAUDE.md設計

コンテキスト管理の章で解説したInstruction Budgetの概念は、CLAUDE.md設計に直接影響します。 フロンティアLLMが安定的に従える命令数は約150〜200。 この「予算」はCLAUDE.mdの記述だけでなく、システムプロンプト、ツール定義、MCP接続のすべてを含みます。

つまり、MCPサーバーを5つ接続してツール定義が100個になれば、 CLAUDE.mdに使える命令バジェットは残り50〜100しかありません。 「全部入り」のCLAUDE.mdを書いて、さらにMCPも全部つなぐ――これは予算超過の典型パターンです。

予算配分チェックリスト

CLAUDE.mdを書く前に、現在の予算消費状況を把握しましょう。 以下のチェックリストで、自分のプロジェクトの予算配分を確認してください。

• MCPツール数を確認 — 接続中のMCPサーバーのツール定義数を合計する。目安は50個以内
• settings.jsonのルール数を確認 — permissionsのallow/denyルール数を数える
• CLAUDE.mdの命令数を数える — 箇条書き1項目 ≒ 1命令として概算。100以内が理想
• 合計が150を超えたら削る — 優先度の低い命令を.claude/rules/に退避し、必要時だけ参照される構造にする

予算を節約する記述テクニック

同じ意味を伝えるにも、書き方次第で消費する命令数は変わります。 Dex氏の知見を踏まえた、効率的なCLAUDE.mdの記述法を紹介します。

# ❌ 命令が冗長（5命令分）
- テストは必ず書くこと
- テストファイルは __tests__/ に配置すること
- テストはJestを使うこと
- テストのカバレッジは80%以上にすること
- テスト実行は npm test で行うこと

# ✅ 圧縮した記述（2命令分）
- テスト: Jest, __tests__/ 配置, カバレッジ80%以上, npm test
- テストなしのPRは禁止

ポイントは関連するルールをグループ化して1行にまとめることです。 箇条書きの各項目がLLMにとっての「1命令」に近い単位になるため、 5行の箇条書きを1〜2行にまとめるだけで、命令バジェットの消費を半分以下にできます。

また、コードベースから自明なこと（使用言語、フレームワーク、ディレクトリ構造）は CLAUDE.mdに書かない方が予算効率が良いです。 Claudeはコードベースを読めば分かることを改めて指示される必要はありません。

まとめ

CLAUDE.mdの上級設計は、個人の生産性向上からチーム全体の品質管理へとスコープが広がります。 モノレポでの配置戦略、.claude/rules/による分割管理、settings.jsonとの使い分け、 そして月次レビューによる継続的な改善。これらを実践することで、 CLAUDE.mdは単なる設定ファイルではなく、チームの開発品質を支える基盤として機能します。 200行以下に保ちながら、コードベース自体もクリーンに維持する――この両輪が、 Claude Codeを組織規模で活用するための最終的な答えです。