---

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

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

See reference/framework-patterns.md for complete list.

Common Patterns

Output

Standard Report Format

Copy# 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 | ... |