Skip to content

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

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

FileKindSize
SKILL.mdskill md2.4 KB
scripts/symbol_map.pyexecutablescript11.0 KB
---
name: map
description: 產出 codebase 語意符號地圖(classes、functions、interfaces、types 的精確 file:line 位置)。適合在大型重構前或接手陌生 codebase 時使用。
disable-model-invocation: true
context: fork
---

# 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,不含動態建立的符號
- **更新時機**:每次大規模重構後重跑更新地圖
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: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated 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: 322kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall