map

# Map — Codebase Symbol Map ## 觸發條件 - 開始大規模重構前，需要精確的符號位置 - 接手陌生 codebase，需要快速建立心智地圖 - 避免 Grep 在註解/字串中找到誤報 - 與 `prime` skill 搭配：prime 讀 README，map 產出符號索引 ## 執行方式 ```bash # 在專案根目錄執行（輸出存於 ~/.claude/codebase-maps/） python3 ~/.claude/skills/map/scripts/symbol_map.py # 或指定目標目錄 python3 ~/.claude/skills/map/scripts/symbol_map.py /path/to/project ``` 腳本會： 1. 自動偵測語言（TypeScript / JavaScript / Python / Rust / Go） 2. 提取所有 exported 符號與精確 `file:line` 3. 輸出 markdown 地圖至 `~/.claude/codebase-maps/<project>_symbols.md` ## 輸出格式範例 ```markdown # Codebase Symbol Map **Project**: `my-project` **Languages**: typescript **Files**: 42 | **Symbols**: 183 ## Classes | Symbol | Location | |--------|----------| | `AuthProvider` | `src/auth/provider.ts:15` | ## Functions | Symbol | Location | |--------|----------| | `formatDate` | `src/utils/date.ts:42` | ``` ## 產出後的使用方式 地圖生成後，直接引用精確位置： - 「讀 `src/auth/provider.ts:15` 確認 AuthProvider 的介面」 - 「`src/utils/date.ts:42` 的 `formatDate` 需要修改」 不再需要猜測或用 Grep 反覆搜尋。 ## 支援語言 | 語言 | 提取符號類型 | |------|------------| | TypeScript | function, class, interface, type, const, enum | | JavaScript | function, class, const, module.exports | | Python | class, def, TypeVar | | Rust | pub fn, pub struct, pub enum, pub trait | | Go | exported func, struct, interface (大寫開頭) | ## Gotcha - **腳本路徑**：確認 `~/.claude/skills/map/scripts/symbol_map.py` 存在（在 workspace 的 `.claude/skills/map/scripts/` 目錄中） - **輸出目錄**：地圖存於 `~/.claude/codebase-maps/`，非 workspace 目錄，不會被 git 追蹤 - **大型 codebase**：超過 1000 個檔案時產出可能較大；用 `head -100` 先看摘要 - **動態語言**：Python 只提取頂層 class/def，不含動態建立的符號 - **更新時機**：每次大規模重構後重跑更新地圖