Claude Code 大規模コードベース・モノレポ完全活用ガイド｜CLAUDE.md階層設計・コンテキスト管理・サブエージェント分割調査の実践パターン

project/
├── CLAUDE.md              # 全体共通：技術スタック概要・リポジトリ規約・デプロイ手順
├── frontend/
│   ├── CLAUDE.md          # フロントエンド固有：Reactコンポーネント規約・CSS規約・テスト方針
│   └── src/
├── backend/
│   ├── CLAUDE.md          # バックエンド固有：APIエンドポイント規約・DB設計ルール・エラー処理
│   └── src/
├── core/
│   ├── CLAUDE.md          # コアサービス固有：ドメインロジック・共有型定義
│   └── src/
└── docs/

# プロジェクトルートで実行
claude
/init

# 生成後にClaudeに追加分析を依頼することも可能
# "このプロジェクトのテスト構成とデプロイ手順もCLAUDE.mdに追加してください"

# Project Overview
See @README.md for project overview.
See @package.json for available npm commands.

# Architecture
Our system design is documented in @docs/architecture.md
The API contract is defined in @docs/openapi.yaml

# Git Workflow
Follow the guidelines in @docs/git-workflow.md

# Personal Overrides
Additional personal instructions: @~/.claude/personal-style.md

# 認証フローの変更内容だけを残して圧縮
/compact Focus on the OAuth token refresh changes we made to src/auth/

# DBマイグレーション結果を優先して保持
/compact Keep the migration results and schema changes, discard the exploration phase

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "70"
  }
}

# 悪い例（メインコンテキストを大量消費する）
claude "src/ 全体を読んで認証システムの仕組みを教えてください"

# 良い例（サブエージェントで調査してサマリーを受け取る）
claude "Use subagents to investigate how our authentication system handles
token refresh, and whether we have any existing OAuth utilities I should reuse.
Summarize your findings concisely."

# 複数の調査を並列実行（大幅に時間短縮）
claude "Use parallel subagents to investigate:
1. How the frontend handles API error states (check src/frontend/)
2. How the backend formats error responses (check src/backend/api/)
3. What error handling patterns exist in our test files (check tests/)
Report how they align and where they conflict."

{
  "worktree": {
    "sparsePaths": [
      "packages/auth",
      "packages/shared",
      "services/api-gateway"
    ]
  }
}

# Shift+Tab でPlan Modeに切り替えてから
"Read src/auth/ and understand how we handle sessions and login.
Also look at how we manage environment variables for secrets.
Do not make any changes yet."

# 同じPlan Modeで続けて
"I want to add Google OAuth. What files need to change?
What is the session flow? What are the risks?
Create a detailed implementation plan."

# Shift+Tab でPlan Modeを解除してから
"Implement the OAuth flow from your plan.
Write tests for the callback handler.
Run the test suite and fix any failures before finishing."

claude "I want to build a notification system that supports email, Slack, and in-app notifications.

Interview me in detail using the AskUserQuestion tool.
Ask about:
- Technical implementation choices
- UI/UX considerations
- Edge cases and failure scenarios
- Security concerns
- Performance tradeoffs

Don't ask obvious questions. Dig into the hard parts I might not have considered.
Keep interviewing until we've covered everything.
Then write a complete spec to SPEC.md."

# 変更前に影響範囲を把握する
claude "Before making any changes, investigate with subagents:
1. All places that import or call the UserAuthentication class
2. Any tests that directly test this class
3. Any documentation that references this class

Report the full impact scope, then wait for my approval before making changes."