Codebase Report

Codebase Report

Core Insight: Understanding is ephemeral. Documents survive context compaction.

The Problem

You explore a codebase, build a mental model, then context compacts. This skill produces reusable artifacts that survive.

Differs from codebase-archaeology: Archaeology = understanding. This = producing a document.

THE EXACT PROMPT

Produce a Comprehensive Technical Architecture Report for this codebase:

1. Executive summary (what is it, key stats)
2. Entry points (main, routes, handlers)
3. Key types (3-5 core domain objects)
4. Data flow (input → processing → output)
5. External dependencies (DBs, APIs, critical libs)
6. Configuration (env, files, CLI, precedence)
7. Test infrastructure

Include file:line references. Output as markdown I can reference later.

Quick Start

# Option 1: Auto-scaffold (fills what it can detect)
./scripts/scaffold-report.py /path/to/project > ARCHITECTURE.md

# Option 2: Manual exploration
cat README.md AGENTS.md 2>/dev/null | head -200
ls src/ lib/ cmd/ pkg/ 2>/dev/null
rg "fn main|func main|if __name__" --type-add 'all:*.*' -l | head -5

# Then fill template from references/TEMPLATE.md

Report Modes

Quick Scan (Minimal)

Quick architecture overview:
- What is it? (1 sentence)
- Entry points (list)
- 3 key types
- Main data flow (1 diagram)
Keep under 150 lines.

Output Structure

# [Project] - Technical Architecture Report

## Executive Summary
[What + stats in 3 lines]

## Entry Points
| Entry | Location | Purpose |
|-------|----------|---------|

## Key Types
| Type | Location | Purpose |
|------|----------|---------|

## Data Flow
[ASCII diagram + 2-sentence description]

## External Dependencies
| Dependency | Purpose | Critical? |
|------------|---------|-----------|

## Configuration
| Source | Priority | Example |
|--------|----------|---------|

## Test Infrastructure
| Type | Location | Count |
|------|----------|-------|

Full template: TEMPLATE.md

Delegation Pattern

For large codebases, delegate exploration:

Use the codebase-explorer subagent to explore this codebase.
Return structured findings, then I'll compile the final report.

The subagent explores in read-only mode and returns findings in report-ready format.

Anti-Patterns

Integration

With Hooks

Auto-generate report stub on new project:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "if echo \"$TOOL_INPUT\" | grep -q 'git clone'; then ./scripts/scaffold-report.py . > ARCHITECTURE.md; fi"
      }]
    }]
  }
}

With Other Skills

References

Scripts

Subagents