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