codebase-analysis

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

1. [ ] Quick Assessment: Project size, structure, config files
2. [ ] CHECKPOINT: Identify entry points (read cookbook/entry-point-discovery.md)
3. [ ] Trace dependencies from entry points
4. [ ] Detect architectural patterns
5. [ ] CHECKPOINT: Verify pattern detection before anti-pattern search
6. [ ] Identify anti-patterns and technical debt
7. [ ] 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 | ... |