Codebase Analysis Skill

Systematically explore and understand existing codebases, including entry point discovery, dependency tracing, pattern detection, and technical debt identification.

Variables

quick

standard

deep

markdown

json

c4

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

package.json

index.js

server.js

tsconfig.json

src/index.ts

__main__.py

app.py

wsgi.py

main.go

cmd/*/main.go

src/index.tsx

pages/_app.tsx

See

reference/framework-patterns.md

Common Patterns

models/

views/

controllers/

presentation/

business/

data/

domain/

ports/

adapters/

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