📝
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を消費するので、参照頻度やインデックス化する内容は適宜調整して、現状ちょうど良いところを模索中です。
Discussion