| name | codebase-viewer |
| description | Structured codebase intelligence: directory tree with roles, entry points, dependency graph, test coverage map, and annotated 'here be dragons' warnings. Lean single-file variant — full version (adds a defined reading-order output): `continuous-learning:codebase-cartography`. |
| triggers | ["view codebase","map the code","codebase overview","show me the architecture","explore this repo"] |
| version | 1.0.1 |
| model | sonnet |
| category | understand-codebase |
Codebase Viewer
Produces a structured codebase map — not a file listing but an annotated architecture view with entry points, dependency flow, test coverage, and danger zones.
Philosophy
Jumping into a new or unfamiliar codebase without a map is how hours disappear. File listings tell you what exists; this skill tells you what matters — where execution starts, where complexity accumulates, which corners have been skipped in testing, and which files will burn you. The output is a decision-ready orientation document, not a directory dump.
When to Use
- Onboarding to a codebase you haven't touched before
- Resuming work after a long gap on a project
- Before dispatching build agents so you scout first-hand (not off a spec)
- Code review or audit where you need structural context, not just diff hungers
- Identifying where to focus refactoring or test investment
- Any time someone asks "how does this repo fit together?"
Do NOT use for repos you know intimately and just need to read a single file — this skill is oriented toward whole-codebase orientation, not targeted lookup.
Workflow
1. TREE
Generate directory structure (2-3 levels deep) with role annotations:
- Each directory gets a one-line role description
- Mark directories as: source, test, config, docs, build, generated, vendored
- Flag empty directories and their likely purpose
- Respect .gitignore — skip node_modules, vendor, build outputs
2. ENTRY
Identify entry points — where execution begins:
main functions (Go, Rust, Python)- CLI command handlers
- HTTP route registrations
- Event listeners and subscribers
- Scheduled task definitions
- Test suites (as secondary entry points)
3. DEPS
Map the dependency graph:
- External dependencies from go.mod / package.json / Cargo.toml / requirements.txt
- Internal package import relationships
- Circular dependency detection
- Heavyweight dependencies (large transitive dep trees)
4. TESTS
Scan for test coverage:
- Which packages/directories have test files
- Test-to-source ratio per directory
- Packages with zero tests (flag as risk)
- Test patterns in use (unit, integration, e2e, benchmark)
5. PATTERNS
Identify architectural patterns:
- Clean architecture / hexagonal / onion (ports-and-adapters)
- MVC / MVVM
- Microservice boundaries
- Monolith with internal module separation
- Event-driven / message-passing
- Repository pattern / service layer
6. DRAGONS
Flag areas of concern — severity-labeled:
- CRITICAL: Files >1000 lines, circular dependencies, hardcoded secrets
- WARNING: Files >500 lines, deeply nested code (>4 levels), TODO/FIXME density >5 per file
- INFO: No tests for package, outdated dependencies, unused imports
7. CONTRACTS
Identify interfaces and API boundaries:
- Go interfaces and their implementors
- HTTP API surface (routes, methods, request/response types)
- gRPC / protobuf definitions
- Event schemas
- Configuration contracts (env vars, config files)
8. REPORT
Produce structured codebase map as markdown:
- Header with repo name, language, size metrics
- Each section from above as a headed section
- Summary statistics table (files, lines, packages, test coverage %)
9. SUGGEST (optional, only if requested)
Based on findings, suggest 3 high-value improvements:
- Highest-risk dragon to address first
- Biggest test coverage gap
- Most impactful architectural improvement
Reading Rules
- For files >50KB: use Grep to find relevant sections, then read with offset/limit
- Never read files >200KB in one shot
- Check file size with wc -c before reading large files
- Prefer targeted reads over full-file reads for analysis
Common Pitfalls
- File listing ≠ architecture map. Don't just emit
ls -R output. Every section should add annotation, not just enumeration.
- Skipping the DRAGONS step. It's tempting to stop at the pretty tree. The danger-zone audit is often the most actionable output.
- Reading large files whole. A 3000-line file read entirely to find one entry point wastes context. Grep for
func main or the framework's router registration instead.
- Marking everything CRITICAL. Severity labels lose value if everything is red. Reserve CRITICAL for genuine hazards (hardcoded secrets, circular deps); use INFO liberally.
- Inventing test coverage numbers. If the tool can't count test files precisely, say "no test files found" rather than estimating a percentage.
Example
A Go microservice repo. The skill produces:
- TREE:
cmd/server/ (entry), internal/handler/ (HTTP layer), internal/store/ (DB), pkg/models/ (shared types), docs/ (OpenAPI specs)
- ENTRY:
cmd/server/main.go → registers HTTP router, loads config, starts listener
- DEPS: external —
chi, pgx, zap; no circular internal imports detected
- TESTS:
internal/handler/ has tests; internal/store/ has zero test files (flagged INFO)
- PATTERNS: Clean architecture — handler → service → store, no cross-layer imports
- DRAGONS:
internal/store/queries.go at 1,100 lines (CRITICAL); 3 TODO comments in internal/handler/auth.go (INFO)
The output is a single markdown document a new contributor can read in five minutes to understand the system.
Quality Checklist
Related Skills
convergence-checker — checks memory health and index freshness; useful after a codebase-viewer run reveals the local memory is staleadr-writer — once the architecture is mapped, write ADRs for the key structural decisions foundscout-writer — produces targeted scouts into specific subsystems after the top-level map is done
