repo-map

快速理解任何代码库的综合参考。涵盖文档、代码、配置、Git 和会话历史的所有模式。完整的操作手册。

📖 中文导读:快速理解任何代码库的综合参考。涵盖文档、代码、配置、Git 和会话历史的所有模式。完整的操作手册。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: repo-map description: Comprehensive reference for understanding any repo fast. All patterns for docs, code, configs, git, and conversation history. The complete playbook. allowed-tools: Bash, Read, Grep, Glob

Repo Map - Complete Understanding Playbook

Everything you need to understand a repository in minimal tokens.

The 5 Dimensions of Repo Understanding

Dimension What Skills
History What was I working on? search-history
Docs What should I know? index-docs
Code How does it work? codebase-index
Config How is it configured? read-configs
Git What's the current state? (built-in)

1. DOCUMENTATION PATTERNS

Headings

Level Pattern Command
H1 # Title grep -rn "^# " --include="*.md"
H2 ## Section grep -rn "^## " --include="*.md"
H3 ### Subsection grep -rn "^### " --include="*.md"
H1+H2 Combined grep -rn "^##\? " --include="*.md"
H1+H2+H3 All grep -rn "^###\?\? " --include="*.md"

Markdown Elements

Element Command
Mermaid diagrams grep -rln "mermaid" --include="*.md"
Code blocks grep -rn '^```[a-z]' --include="*.md"
Code block languages grep -roh '^```[a-z]*' --include="*.md" | sort | uniq -c | sort -rn
Tables `grep -rn "^
Links grep -ron "\[.*\](.*)" --include="*.md"
Images grep -ron "!\[.*\](.*)" --include="*.md"
TODOs grep -rn "TODO|FIXME|XXX" --include="*.md"
Checkboxes grep -rn "\[ \]|\[x\]" --include="*.md"

Key Doc Files

ls -la README.md CLAUDE.md CONTRIBUTING.md CHANGELOG.md LICENSE 2>/dev/null
ls -la docs/ doc/ documentation/ 2>/dev/null

2. CODE PATTERNS

Entry Points

Language Pattern Command
Python if __name__ rg "if __name__" --type py -l
Go func main() rg "^func main" --type go -l
Node module.exports rg "module\.exports" --type js -l
TypeScript export default rg "^export default" --type ts -l

API Routes

Framework Command
FastAPI rg "@(app|router)\.(get|post|put|delete)" --type py -n
Flask rg "@.*\.route\(" --type py -n
Express rg "(app|router)\.(get|post|put|delete)\(" --type js -n
Cloud Functions rg "functions_framework" --type py -n

Definitions

What Command
Python classes rg "^class " --type py -n
Python functions rg "^def " --type py -n
TS/JS classes rg "^(export )?class " --type ts -n
TS interfaces rg "^(export )?interface " --type ts -n
Go structs rg "^type .* struct" --type go -n

Models & Schemas

ORM/Framework Command
SQLAlchemy rg "class.*\(.*Base\)" --type py -n
Pydantic rg "class.*BaseModel" --type py -n
Django rg "models\.Model" --type py -n
Prisma rg "^model " --glob "*.prisma"

Imports & Dependencies

# Most used Python packages
rg "^(from\|import) " --type py | cut -d' ' -f2 | cut -d'.' -f1 | sort | uniq -c | sort -rn | head -20

# Most used JS/TS imports
rg "^import .* from" --type ts --type js | grep -oP "from ['\"].*?['\"]" | sort | uniq -c | sort -rn | head -20

Decorators & Patterns

# Python decorators
rg "^@\w+" --type py | cut -d':' -f2 | sort | uniq -c | sort -rn | head -15

# Error classes
rg "class.*Exception|class.*Error\(" --type py -n

3. CONFIG PATTERNS

Project Configs

Type Files Command
Python pyproject.toml, setup.py ls pyproject.toml setup.py 2>/dev/null
Node package.json, tsconfig.json ls package.json tsconfig*.json 2>/dev/null
Go go.mod, go.sum ls go.mod go.sum 2>/dev/null

Environment

# Find env files
ls -la .env* env.* 2>/dev/null

# Env var names (NOT values)
grep -h "^[A-Z]" .env* 2>/dev/null | cut -d'=' -f1 | sort | uniq

Cloud & CI/CD

# GCP
ls app.yaml cloudbuild.yaml *.tf 2>/dev/null

# GitHub Actions
ls .github/workflows/*.y*ml 2>/dev/null

# Docker
ls Dockerfile docker-compose*.yml 2>/dev/null

Build Tools

ls Makefile BUILD.bazel *.bzl 2>/dev/null

4. GIT PATTERNS

# Current state
git status --short | head -20

# Current branch
git branch -v | grep "^\*"

# Recent commits
git log --oneline -10

# Changed files (staged)
git diff --cached --name-only

# Contributors
git shortlog -sn | head -10

5. CONVERSATION HISTORY

cd ~/.claude/services

# Recent sessions
python3 conversation-search.py --list-sessions | head -5

# Search for topic
python3 conversation-search.py "TOPIC" --max 3 --full

# Last exchanges
python3 conversation-search.py "." --session SESSION_ID --max 10 --full

QUICK REFERENCE CARD

Minimal Startup (30 sec)

# 1. Sessions
cd ~/.claude/services && python3 conversation-search.py --list-sessions | head -3

# 2. Doc headings
cd - && find . -name "*.md" -not -path "*/.git/*" | xargs grep -n "^# " 2>/dev/null | head -20

# 3. Entry points
rg "if __name__|^func main" --type py --type go -l 2>/dev/null | head -5

# 4. Git state
git status --short | head -10

Full Startup (60 sec)

echo "=== HISTORY ===" && cd ~/.claude/services && python3 conversation-search.py --list-sessions | head -3
echo "=== DOCS ===" && cd - > /dev/null && find . -name "*.md" -not -path "*/.git/*" | xargs grep -n "^# " 2>/dev/null | head -20
echo "=== ENTRY POINTS ===" && rg "if __name__|^func main" --type py --type go -l 2>/dev/null | head -5
echo "=== CLASSES ===" && rg "^class " --type py -c 2>/dev/null | head -10
echo "=== CONFIGS ===" && ls pyproject.toml package.json app.yaml .env* 2>/dev/null
echo "=== GIT ===" && git status --short | head -10 && git branch -v | grep "^\*"

Token Budget Guide

Action Tokens When
List files ~50 Always
Grep headings ~100-200 Always
Count classes ~50-100 Always
Read one file ~500-2000 When needed
Full file content ~2000+ Rarely

Rule: Index everything, read selectively.


Skill Purpose
startup Master bootstrap sequence
post-compact Context recovery
index-docs Doc structure
codebase-index Code architecture
read-configs Config discovery
search-history Conversation context