Codebase Archaeology

Codebase Archaeology

You just inherited 200,000 lines of code. The author left. There are no docs. The CEO wants a new feature by Friday. This skill turns "where do I even start" into a structured 2-week onboarding plan.

What it does

A systematic reverse-engineering workflow for any codebase:

• Dependency map — module graph, circular deps, fan-in / fan-out metrics
• Dead code report — unused exports, unreachable functions, orphaned files
• Risk hotspots — files that change often + are complex + lack tests
• Conventions detector — what naming/structure does this codebase actually use
• Hidden entry points — scripts, cron jobs, CLI tools, undocumented APIs
• Onboarding guide generator — README, ARCHITECTURE.md, CONCEPTS.md
• "Where do I change X" — for a feature request, identifies all touchpoints

When to use it

• You just joined a team and need to ramp up fast
• You inherited a legacy codebase with no docs
• You need to estimate the cost of a refactor
• You want to find dead code to delete (or test gaps to fill)
• You need to onboard a new hire
• You're auditing a codebase before acquisition

Why it's better than ad-hoc prompting

Most "explain this codebase" prompts produce surface-level summaries. This skill is different:

• Quantitative — every module gets a score (complexity, coupling, churn)
• Actionable — outputs a prioritized 2-week plan, not just docs
• Visual — generates interactive dependency graphs (Mermaid)
• Comprehensive — covers 12 dimensions, not just "what does it do"
• Cumulative — second run shows what's changed since first

Architecture

┌─────────────────────────────────────────────────────────┐
│               Agent (Claude/Cursor)                     │
│  - Points at a codebase                                 │
│  - Runs archaeology scripts                             │
│  - Synthesizes findings + onboarding plan              │
└───────────────┬─────────────────────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────────────────────┐
│            skills/codebase-archaeology/                  │
│  scripts/                                                │
│    ├── dependency_map.py    # Import graph + cycles      │
│    ├── dead_code.py         # Unused exports, funcs      │
│    ├── hotspots.py          # Churn × complexity         │
│    ├── conventions.py       # Style + pattern detection  │
│    ├── entry_points.py      # Scripts, cron, CLI         │
│    ├── onboarding_gen.py    # README, ARCHITECTURE       │
│    └── feature_locator.py   # "Where do I add X?"        │
│  references/                                             │
│    ├── onboarding-plan.md                                │
│    ├── hotspot-playbook.md                                │
│    └── dead-code-policy.md                                │
│  templates/                                              │
│    ├── ARCHITECTURE.md.tmpl                              │
│    └── CONCEPTS.md.tmpl                                   │
└─────────────────────────────────────────────────────────┘

Quick start

# 1. Install
pip install networkx radon lizard pydeps mccabe

# 2. Generate dependency map
python scripts/dependency_map.py ./src --format mermaid > docs/architecture.md

# 3. Find dead code (Python)
python scripts/dead_code.py ./src --language python

# 4. Risk hotspots
python scripts/hotspots.py ./src --since "1 year ago"

# 5. Detect conventions
python scripts/conventions.py ./src

# 6. Find entry points
python scripts/entry_points.py .

# 7. Generate onboarding guide
python scripts/onboarding_gen.py ./src --output docs/

# 8. "Where do I add a new feature?"
python scripts/feature_locator.py ./src "user authentication"

Sample onboarding output (excerpt)

# Codebase Onboarding Plan — 2 weeks

## Day 1-2: Reconnaissance
- [ ] Read README.md (auto-generated)
- [ ] Review ARCHITECTURE.md (auto-generated) — focus on:
      - Module structure (3 layers: api → service → data)
      - 3 main domains: users, billing, reports
- [ ] Skim 5 most-imported files (top of dependency map)
- [ ] Run the test suite once to know the baseline

## Day 3-4: Hotspot familiarization
- [ ] Open top 5 hotspot files (most changed + most complex)
- [ ] Read their tests — they encode the team's expectations
- [ ] Note the 3 "load-bearing" modules (high fan-in, low churn)

## Day 5-7: Make your first change (in test branch)
- [ ] Add a feature in the simplest module
- [ ] Run lints, tests, type checks
- [ ] Open a PR — observe review feedback patterns
- [ ] Update ARCHITECTURE.md with what you learned

## Day 8-10: Tackle a small bug
- [ ] Pick a low-priority issue
- [ ] Use feature_locator.py to find touchpoints
- [ ] Make the fix, add a regression test
- [ ] Note any "weird" code that needs explaining

## Day 11-14: Write your "I just joined" doc
- [ ] 3 things that surprised you
- [ ] 3 things that are broken-but-intentional
- [ ] 3 things you'd refactor given time
- [ ] Add to CONCEPTS.md (auto-updated each run)

The 12 dimensions analyzed

1. Module structure — top-level layout, layer count, domain boundaries
2. Dependency graph — module imports, cycles, fan-in/fan-out
3. Dead code — unused exports, unreachable functions, orphan files
4. Risk hotspots — files with high churn AND high complexity
5. Test coverage — line + branch, gap analysis
6. Style conventions — naming, formatting, file structure
7. Error handling — exception patterns, error codes, retry logic
8. Concurrency model — threads, async, locks, actors
9. External integrations — APIs, DBs, queues, third-party libs
10. Configuration — env vars, config files, secrets
11. Entry points — main(), CLIs, cron, message handlers, webhooks
12. Documentation gaps — public functions without doc comments

Pricing

Single-purchase, lifetime access. $9.00.

Includes:

• 7 Python archaeology scripts
• 3 reference docs (onboarding plan, hotspot playbook, dead-code policy)
• 2 templates (ARCHITECTURE.md, CONCEPTS.md)
• Sample analysis of a real open-source project
• Future updates for the same major version

Example usage

"I'm joining a team next week. They have a 200k line Python/TypeScript monorepo with no docs. Give me a 2-week onboarding plan."

The skill will:

1. Run all 12 dimensions
2. Generate ARCHITECTURE.md from real data (not vibes)
3. Identify the 5 "must-understand" files
4. Output a day-by-day plan
5. Save findings to docs/ for future team members

Compatibility

Works with any agent that supports the SKILL.md standard and can execute Python: Claude Code, OpenClaw, Codex CLI, Cursor, Gemini CLI, Cline, Windsurf, Aider. Supports Python, TypeScript, Go (full); Rust, Java (partial). Requires Git for hotspot/churn analysis. Tested on Linux, macOS, Windows.

Tags

code-analysis, refactoring, documentation, onboarding, technical-debt, legacy, code-quality