大規模リポジトリでのClaude Code活用法

症状・課題

• プロジェクトが大きすぎて、Claudeが全体を把握できない
• 「このバグがどこで起きているか教えて」と聞いても的外れな回答が来る
• コンテキストがすぐに埋まる
• ファイルパスを指定しても「見つかりません」と言われる
• 大量のファイルを読み込むのに時間がかかる

※コンテキスト: Claudeが一度に記憶・参照できる会話・コードの範囲。上限を超えると古い情報が失われる。

原因

原因1: リポジトリ全体をコンテキストに入れようとしている

Claude Codeのコンテキストウィンドウには限りがあります。10万行を超えるコードベースを一度に読み込むことはできません。

原因2: ディレクトリ構造が複雑で、Claudeが迷子になっている

適切なガイダンスがないと、Claudeはどのファイルがどの役割を持つかを把握するだけで大量のコンテキストを消費します。

原因3: CLAUDE.mdがルートのみで、サブシステムの情報がない

モノレポや大型プロジェクトでは、ルートのCLAUDE.mdだけでは情報が足りません。

※コンテキストウィンドウ: Claudeが一度に処理できるテキストの最大量（トークン数）。モデルによって異なる。※CLAUDE.md: プロジェクトのルートに置くClaude Code専用の設定ファイル。プロジェクト固有のルールやコンテキストを記述する。※リポジトリ: Gitでコードと変更履歴を管理するフォルダ。GitHubなどのサービスで共有できる。※モノレポ: 複数のパッケージやアプリを1つのリポジトリで管理する構成。

解決手順

対策1: サブディレクトリにCLAUDE.mdを置く

大規模プロジェクトでは、各サブシステムに専用のCLAUDE.mdを配置します。

monorepo/
├── CLAUDE.md                    # リポジトリ全体の概要・禁止事項
├── packages/
│   ├── api/
│   │   └── CLAUDE.md           # APIの詳細・エンドポイント一覧
│   ├── web/
│   │   └── CLAUDE.md           # フロントエンドの詳細
│   └── shared/
│       └── CLAUDE.md           # 共有ライブラリの説明
└── infrastructure/
    └── CLAUDE.md               # インフラ設定の注意事項

ルートの CLAUDE.md はコンパクトに：

# [プロジェクト名] モノレポ

## 構成

- `packages/api/` — バックエンドAPI（詳細: packages/api/CLAUDE.md）
- `packages/web/` — Webフロントエンド（詳細: packages/web/CLAUDE.md）
- `packages/shared/` — 共有型定義・ユーティリティ

## ルール

- パッケージをまたぐ変更は必ず全パッケージでテストを実行する
- `packages/shared/` の型変更は影響範囲が広い。要注意
- ルートの `package.json` は触らない（ワークスペース設定）

対策2: 作業スコープを明示的に指定する

# ❌ 範囲が広すぎる依頼
「ユーザー認証のバグを直して」

# ✅ スコープを絞った依頼
「packages/api/src/auth/ ディレクトリのバグを調査して。
症状: ログイン後にセッションが即時切れる
再現: POST /api/auth/login → 200 OK → GET /api/me → 401
調査範囲: packages/api/src/auth/ のみで頼む」

対策3: .claudeignore で無視するファイルを指定する

プロジェクトルートに .claudeignore ファイルを作成することで、Claudeがアクセスするファイルを制限できます。

.claudeignore

# ビルド成果物
dist/
build/
.next/
out/

# 依存関係（Claudeに読ませる必要はない）
node_modules/
vendor/
.venv/

# ログ・一時ファイル
logs/
*.log
tmp/
.cache/

# 大きなデータファイル
data/dumps/
fixtures/large/
*.csv
*.sql

# テスト結果・カバレッジ
coverage/
.nyc_output/
test-results/

対策4: ファイルマップをCLAUDE.mdに書く

Claudeが全ファイルを探索しなくて済むように、重要なファイルの場所を明示します。

## 重要なファイルマップ

| 機能 | ファイル |
|------|---------|
| 認証ロジック | `src/auth/service.ts` |
| データベース接続 | `src/lib/db.ts` |
| 環境変数の型 | `src/env.ts` |
| APIクライアント | `src/lib/api-client.ts` |
| ルーティング定義 | `src/app/routes.ts` |
| 共通型定義 | `src/types/index.ts` |

対策5: 段階的なアプローチで作業する

「まず src/auth/ の構造を教えてください（コードは読まなくていい、ファイル一覧だけ）」
→ 構造を把握
→ 「では service.ts の handleLogin 関数だけ見てください」
→ ピンポイントで調査

※エンドポイント: APIにアクセスするためのURL。例: `/api/users` や `/api/posts/123` など。※環境変数: APIキーやデータベース接続情報など、コードに直接書きたくない値をOSやサーバーに設定する仕組み。※API: Application Programming Interface の略。外部サービスとプログラム間でデータをやりとりするための接続口。

大規模リポジトリ向けの効率的なプロンプト

コードを探すとき

「src/ 以下で 'validateToken' という関数を使っているファイルを探してください。
全ファイルを読まなくていい。ファイルパスだけ教えてください。」

影響範囲を調べるとき

「User モデルの email カラムを削除したい。
src/ 以下で email を参照している箇所を探してください（grep相当）。
ファイルと行番号だけ出力してください。」

変更の前に確認するとき

「src/api/users.ts の deleteUser 関数を変更したい。
この関数を呼び出している箇所を全て調べてください。
影響範囲を確認してから作業します。」

※プロンプト: AIへの指示文。Claude Codeへの指示の質がそのまま出力の質に影響する。

モノレポでの具体的な設定例

// .claude/settings.json（モノレポ用）
{
  "permissions": {
    "allow": [
      "Bash(npm run * --workspace=packages/*)",
      "Bash(pnpm --filter * run *)",
      "Bash(git *)"
    ]
  }
}

※npm: Node.jsのパッケージ管理ツール。`npm install` でライブラリをインストールする。

予防策

リポジトリを小さく保つ設計

巨大なモノレポより、適切に分割されたリポジトリのほうが Claude Code との相性は良いです。しかし、既存のモノレポを分割するのはコストがかかるので、上記の対策で対応してください。

定期的なCLAUDE.mdのメンテナンス

ファイル構造が変わったらCLAUDE.mdも更新します。古い情報はClaudeを混乱させます。

Tip

大規模リポジトリでの黄金律は「コンテキストを無駄にしない」ことです。「全体を把握させてから依頼する」ではなく、「必要な部分だけを示して依頼する」アプローチが効果的です。