Claude CodeをCursorみたいに使う！インデックス化でプロジェクト文脈をAIに渡しトークンも節約！

※この記事はClaudeで下書きを作成し、実体験ベースで加筆・修正しています。

はじめに

Claude Codeを使っていて、「プロジェクトの全体像をAIにどう伝えるか」に課題を感じたことはありませんか？
本記事では、Claude Codeをより効率的に活用するための工夫として、プロジェクトインデックス化という手法を紹介します。Cursorライクな体験を目指す方に特におすすめです。

課題：モノレポや大規模プロジェクトでのAI活用の難しさ

Claude Codeはプロジェクトの内容を把握してくれて素晴らしいのですが、マルチプラットフォームプロジェクトでClaude Codeを使う際、以下のような課題があります：

• プロジェクト構造の把握に時間がかかる
• tokenを多く消費する
• コンテキストが失われる可能性がある

※個人で開発中のプロジェクト「Water Watch（仮）」はモノレポ構成で、Spring Bootのバックエンド、iOSアプリ、Webフロントエンドを1つのリポジトリで管理しています。

解決策：プロジェクトインデックス化

プロジェクトの構造を事前にJSON形式でインデックス化し、Claude Codeが必要に応じて参照できるようにすることで、これらの課題を解決できます。

実際のClaude Codeチャット内容

1. インデックス作成の指示

> claude-code-index-prompts.md の内容を確認し、その指示に従ってください。

⏺ Read(../claude-code-index-prompts.md)
  ⎿  Read 190 lines (ctrl+r to expand)

⏺ このプロジェクトはSpring Boot（バックエンド）とiOS（フロントエンド）の
  マルチプロジェクトワークスペースです。指示に従って、各プロジェクトの
  インデックスとAPI マッピングを作成します。

⏺ Task(Spring Boot index creation)
  ⎿  Done (11 tool uses · 27.4k tokens · 42.8s)

⏺ Write(../spring_index.json)
  ⎿  Wrote 99 lines to ../spring_index.json

claude-code-index-prompts.mdはこちらに置いてあります。

2. インデックス活用の様子

/clearコマンドで新しいコンテキストを開始後：

> RequirementDefinition_external_info.md これを実現したいのですが

⏺ RequirementDefinition_external_info.mdファイルを読み込んで、要件を確認します。

⏺ Read(RequirementDefinition_external_info.md)
  ⎿  Read 286 lines (ctrl+r to expand)

⏺ 現在のプロジェクト構造も確認して、実装計画を立てます。

⏺ Read(project_index/spring_index.json)  # 👈 自動的にインデックスを参照！
  ⎿  Read 99 lines (ctrl+r to expand)

Claude CodeはCLAUDE.mdで指示しているため要件ファイルを渡すだけで、プロジェクトインデックスを参照し、適切な実装計画を立案してくれました。

インデックス作成プロンプトの内容

claude-code-index-prompts.mdの主要部分：

# Claude Code Index Creation Prompts

## 目的
プロジェクトの構造を効率的に把握し、AIアシスタントが
プロジェクト全体のコンテキストを理解できるようにする

## Spring Bootプロジェクトの場合

以下の情報を含むJSONインデックスを作成してください：

1. **プロジェクト基本情報**
   - プロジェクト名
   - フレームワークとバージョン
   - 使用言語
   - ビルドツール

2. **コントローラー情報**
   - 各コントローラーのベースパス
   - エンドポイント一覧（HTTPメソッド、パス、説明）
   - 認証要否
   - レート制限

3. **エンティティ情報**
   - テーブル名
   - 主要フィールド
   - リレーションシップ
   - 列挙型の値

## 出力形式
project_index/spring_index.json として保存

作成されたインデックスファイル

1. spring_index.json（バックエンド）

{
  "project_name": "Water Watch Backend",
  "framework": "Spring Boot 3.x",
  "language": "Kotlin",
  "build_tool": "Gradle",
  "controllers": {
    "AuthController": {
      "base_path": "/api/v1/auth",
      "endpoints": [
        "POST /login - User authentication",
        "POST /register - User registration", 
        "GET /me - Get current user profile"
      ]
    },
    "WaterReportController": {
      "base_path": "/api/v1/reports",
      "endpoints": [
        "POST / - Create water report (auth required)",
        "GET /{id} - Get specific report",
        "PUT /{id} - Update report (auth required)",
        "DELETE /{id} - Delete report (auth required)",
        "GET / - List reports with filters",
        "GET /search - Search reports by keyword",
        "GET /my - Get user's reports (auth required)"
      ]
    }
  },
  "entities": {
    "User": {
      "table": "users",
      "key_fields": ["id", "username", "email", "prefecture", "trustScore"],
      "relationships": ["OneToMany WaterReport", "OneToMany FactCheck"]
    },
    "WaterReport": {
      "table": "water_reports", 
      "key_fields": ["id", "category", "title", "description", "prefecture"],
      "categories": ["MAINTENANCE_CONSTRUCTION", "OUTAGE_SUPPLY", "TROUBLE_ISSUE"],
      "verification_statuses": ["UNVERIFIED", "UNDER_REVIEW", "VERIFIED", "FLAGGED"]
    }
  }
}

2. api_map.json（API連携マッピング）

{
  "authentication": {
    "POST /api/v1/auth/login": {
      "backend": "AuthController.login",
      "web_frontend": "AuthManager.login",
      "ios": "APIService.login",
      ...
    }
  },
  "water_reports": {
    "GET /api/v1/reports": {
      "backend": "WaterReportController.getReports",
      "web_frontend": "ReportsManager.loadReports",
      "ios": "APIService.getReports",
      "description": "Get paginated list of water reports with filtering",
      ...
    }
  }
}

インデックス化による効果

1. 効率的なプロジェクトコンテキストの参照

Before（インデックスなし）

> AuthControllerにユーザープロフィール更新機能を追加したいです

まずはプロジェクト構造を把握するため、AuthControllerを参照します。

Search(pattern: "**/AuthController*.kt")

AuthControllerが見つかりました内容を確認します。

Read(path/to/AuthController.kt)
⎿  Read 200 lines
...

After（インデックスあり）

> AuthControllerにユーザープロフィール更新機能を追加したいです

⏺ Read(project_index/spring_index.json)
⏺ 既存のAuthControllerを確認します
⏺ Read(path/to/AuthController.kt)

⏺ 以下の実装を提案します：
  ...

2. トークンの節約

具体的なデータが無くて申し訳ないですが、バックエンドのspring_index.jsonは現状99行のみかつ内容も簡潔なので、計画＞実装を繰り返す時に効いてきます。

3. 一貫性のある実装

インデックスに含まれる命名規則やパターンにより、AIは既存コードと一貫性のある実装を提案してくれます。

CLAUDE.mdへの組み込み

プロジェクトルールファイル（CLAUDE.md）に以下を追加：

## プロジェクトインデックスファイルの必須読み込み

### 🔥 重要 - 作業開始時に必ず読み込むファイル

**すべての計画・実装を始める前に、以下のインデックスファイルを必ず読み込むこと:**

1. **`project_index/spring_index.json`** - Spring Bootバックエンドの構造概要
2. **`project_index/ios_index.json`** - iOSアプリの構造概要
3. **`project_index/web_index.json`** - Webフロントエンドの構造概要
4. **`project_index/api_map.json`** - プロジェクト間API連携マッピング

### 使用タイミング
- **🔥 最優先**: 新機能実装・修正作業の計画立案時
- **作業開始前**: コード分析・調査作業の前
- **API変更時**: クロスプラットフォーム影響確認

その他のコツ

1. インデックスの粒度

詳細すぎず、概要すぎない適切な粒度が重要：

// ❌ 詳細すぎる（トークンの無駄）
"updateUser": {
  "method": "PUT",
  "path": "/users/{id}",
  "parameters": {
    "id": "Long, path parameter, user ID",
    "request": {
      "username": "String, optional, 3-20 characters",
      "email": "String, optional, valid email format",
      // ... 全フィールドの詳細
    }
  }
}

// ✅ 適切な粒度
"endpoints": [
  "PUT /users/{id} - Update user profile (auth required)"
]

2. 定期的な更新

# 開発の区切りでインデックスを再生成
> 今回の変更を反映してproject_indexを更新してください

# 重要な変更時は即座に更新
> ExternalDataControllerを追加したので、spring_index.jsonに反映してください

3. チーム開発での活用

## 新規メンバー向けオンボーディング

1. project_index/フォルダの全ファイルを確認
2. CLAUDE.mdのルールを理解
3. Claude Codeで以下を実行：
   > project_indexを読み込んで、プロジェクトの概要を説明してください

まとめ

プロジェクトインデックス化により、Claude CodeでもCursorのような統合開発環境に近い開発体験を実現できます：

• トークン削減 - 効率的なコンテキスト共有
• 即座のプロジェクト理解 - /clear後も文脈を維持
• 一貫性のある実装 - 既存パターンの自動認識
• クロスプラットフォーム開発の効率化 - API連携の可視化

大規模プロジェクトやマルチプラットフォーム開発でClaude Codeを活用する際は、ぜひプロジェクトインデックス化を試してみてください。

追記

• インデックスファイルが肥大化してくるとそれはそれでtokenを消費するので、参照頻度やインデックス化する内容は適宜調整して、現状ちょうど良いところを模索中です。
• CLAUDE.mdとの棲み分けは以下を想定しています。
  • CLAUDE.md: 基本ルールを記載（コーディングスタイル、ビルド方法、ドメイン知識）、変更頻度は低い、リポジトリ管理して開発チーム共有
  • project_index: 実装するたびに変化するため頻繁に更新、必要に応じて読み込み