| name | codebase-analysis |
| description | Patterns and techniques for analyzing brownfield codebases. Use when onboarding to unfamiliar code, preparing for refactoring, conducting architecture reviews, or identifying technical debt. |
Codebase Analysis Skill
Systematically explore and understand existing codebases, including entry point discovery, dependency tracing, pattern detection, and technical debt identification.
Variables
| Variable | Default | Description |
|---|---|---|
| ANALYSIS_DEPTH | standard | quick (5min), standard (30min), deep (1hr+) |
| OUTPUT_FORMAT | markdown | markdown, json, c4 |
| INCLUDE_DEBT | true | Include technical debt assessment |
| INCLUDE_DIAGRAMS | true | Generate C4 diagrams |
Instructions
MANDATORY - Follow the Workflow steps below in order. Do not skip steps.
- Start with entry points, not random files
- Trace dependencies before analyzing patterns
- Document findings as you go
Red Flags - STOP and Reconsider
If you're about to:
- Analyze random files without finding entry points first
- Make architectural claims without tracing dependencies
- Skip pattern detection before identifying anti-patterns
- Report technical debt without severity classification
STOP -> Read the appropriate cookbook file -> Follow the workflow -> Then proceed
Workflow
- Quick Assessment: Project size, structure, config files
- CHECKPOINT: Identify entry points (read
cookbook/entry-point-discovery.md) - Trace dependencies from entry points
- Detect architectural patterns
- CHECKPOINT: Verify pattern detection before anti-pattern search
- Identify anti-patterns and technical debt
- Document findings with C4 diagrams (if INCLUDE_DIAGRAMS)
Cookbook
Entry Point Discovery
- IF: Starting analysis of unfamiliar codebase
- THEN: Read
cookbook/entry-point-discovery.md - RESULT: List of main entry points by framework
Dependency Tracing
- IF: Need to understand how modules connect
- THEN: Read
cookbook/dependency-tracing.md - RESULT: Import chains, dependency graph
Pattern Detection
- IF: Need to identify architectural style
- THEN: Read
cookbook/pattern-detection.md - RESULT: Identified patterns (MVC, Layered, etc.)
Technical Debt Identification
- IF: Assessing code quality and debt
- THEN: Read
cookbook/debt-identification.md - RESULT: Prioritized debt inventory
Quick Reference
Entry Points by Stack
| Stack | Look For |
|---|---|
| Node.js | package.json main/bin, index.js, server.js |
| TypeScript | tsconfig.json, src/index.ts |
| Python | __main__.py, app.py, wsgi.py |
| Go | main.go, cmd/*/main.go |
| React | src/index.tsx, pages/_app.tsx |
See reference/framework-patterns.md for complete list.
Common Patterns
| Pattern | Directory Signs |
|---|---|
| MVC | models/, views/, controllers/ |
| Layered | presentation/, business/, data/ |
| Hexagonal | domain/, ports/, adapters/ |
| Microservices | services/*/, packages/*/ |
Output
Standard Report Format
# Codebase Analysis: [Project Name]
## Overview
- **Size**: X files, Y lines
- **Primary Language**: TypeScript
- **Framework**: Next.js
- **Architecture**: [Pattern]
## Entry Points
1. `src/pages/_app.tsx` - Application root
2. `src/api/` - API routes
## Key Dependencies
- [External deps list]
## Architecture Diagram
[C4 diagram if INCLUDE_DIAGRAMS]
## Technical Debt (if INCLUDE_DEBT)
| Issue | Severity | Location |
|-------|----------|----------|
| ... | High | ... |