Skip to content

zeuikli/claude-code-workspace / .claude/skills/map

產出 codebase 語意符號地圖(classes、functions、interfaces、types 的精確 file:line 位置)。適合在大型重構前或接手陌生 codebase 時使用。

Map — Codebase Symbol Map

觸發條件

  • 開始大規模重構前,需要精確的符號位置
  • 接手陌生 codebase,需要快速建立心智地圖
  • 避免 Grep 在註解/字串中找到誤報
  • 與 prime skill 搭配:prime 讀 README,map 產出符號索引

執行方式

# 在專案根目錄執行(輸出存於 ~/.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

輸出格式範例

# 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 反覆搜尋。

支援語言

語言提取符號類型
TypeScriptfunction, class, interface, type, const, enum
JavaScriptfunction, class, const, module.exports
Pythonclass, def, TypeVar
Rustpub fn, pub struct, pub enum, pub trait
Goexported 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,不含動態建立的符號
  • 更新時機:每次大規模重構後重跑更新地圖
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall