概要
最近、コーディングエージェントの利用料が上がり、高性能モデルを常用するとコストが無視できません。できるだけ安価なモデルを指定して使いたいというのが率直なところです。
コードマップを利用して「関連ファイルを引く索引」をあらかじめ与えておけば、安価なモデルでもスキャンを抑えつつ、速く正確に答えられ、高性能モデルに遜色ない出力が期待できます。
今回は、その索引を .mdc(Cursor Rule)として生成する Cursor Skills を作成しました。
Skills
---
name: codemap
description: >-
特定ディレクトリのコードマップ(.mdc ルール)を作成・更新する。
構造マップや依存関係マップの作成、.cursor/rules へのルール追加、
@<ディレクトリ> を対象にしたプロンプト最適化を行うときに使う。
---
# コードマップ作成スキル
## 手順
1. 事前確認(着手前に確認し、不明点は推測せず質問して待つ)
- 対象ディレクトリ(ルートからの相対パス)
- 成果物の置き場所(原則 `.cursor/rules/<name>.mdc`)
- 探索許可(明示的に許可されたときだけ探索)
- globs(ルート相対。`~/` や絶対パスは使わない)
2. 調査(許可後、対象ディレクトリ内のみ最小限で)
- 入口 → 構成要素 → 流れ → 依存 の順に、薄く広く把握する
- node_modules / .venv / 生成物 は除外する
3. 生成(下記テンプレートに沿って .mdc を出力)
4. 完了報告(作成パス / 設定した globs / 想定ワークスペース / 主要セクション概要)
`.mdc` テンプレート:
```markdown
---
description: <対象名> のコードマップ。<対象> 配下でプロンプトを実行する際、最初に参照して関連ファイルを特定しスキャン量を抑える。
globs: <ワークスペース相対パス>/**
alwaysApply: false
---
# <対象名> コードマップ
> 最終更新: <YYYY-MM-DD> / 対象コミット: <short sha 分かれば>
<1〜2文の概要>
## 変更対象の即引き
| やりたいこと / 症状 | まず読むファイル | 補助 |
|---|---|---|
| ... | ... | ... |
## エントリポイント(どこから実行が始まるか)
## 主要コンポーネントと責務(構成要素とそれぞれの役割)
## 主要な処理フロー(入力から出力までの流れ)
## 依存関係(内部・外部の依存を、呼び出しの「方向」で)
## 状態とデータ(永続化・共有状態・スキーマがある場合)
## 設定と環境(config / env / feature flag)
## 拡張・変更ポイント(機能追加や修正で触る場所)
## 前提・制約・落とし穴(並行性・副作用・既知の注意)
## ドキュメントと参考(詳細が要るときだけ開く)
## 触らない領域(生成物・レガシー・大量データ等)
```
運用
1. スキルを設置
~/.cursor/skills/codemap/SKILL.md
2. スキルを呼び出す
対象のリポジトリを開いた状態で、@codemap を呼び出して依頼します。探索してほしい場合はその許可も明記
@codemap スキルに従い、cloud_run/ 向けのコードマップを作成してください。
ワークスペースはこのリポジトリのルートで開いています。探索を許可します。
3. codemap を参照させる
- 対象ディレクトリのファイルを触る作業では、globs により地図が自動で文脈に入る
- 確実に参照させたいときは、依頼文で @<ルール名> を明示的に添える
- 依頼は「まず地図を見て、関連ファイルを1〜3個に絞ってから読む」と一言添えると、探索の暴走をさらに抑えられる
4. 更新
- 構造に変更が入ったら、
@codemapで該当セクションだけ差分更新を依頼 - 更新のたびに、.mdc 先頭の「最終更新 / 対象コミット」を書き換え