codebase-analysis

Consiliency's avatarfrom Consiliency

Patterns and techniques for analyzing brownfield codebases. Use when onboarding to unfamiliar code, preparing for refactoring, conducting architecture reviews, or identifying technical debt.

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026
[Architecture Design]

When & Why to Use This Skill

This Claude skill provides a systematic framework for analyzing and understanding complex brownfield codebases. It streamlines the process of onboarding to unfamiliar code by discovering entry points, tracing dependencies, and detecting architectural patterns. By identifying technical debt and generating C4 diagrams, it helps teams conduct thorough architecture reviews and prepare for successful refactoring projects, ensuring a deep understanding of system structure before making changes.

Use Cases

  • Onboarding to unfamiliar codebases: Quickly identify main entry points and project structure to reduce ramp-up time for new developers.
  • Architecture reviews: Systematically detect architectural patterns and anti-patterns to evaluate system health and alignment with best practices.
  • Refactoring preparation: Map out dependency chains and assess technical debt to prioritize refactoring efforts and minimize regression risks.
  • Technical debt assessment: Generate a prioritized inventory of code quality issues with severity classifications for better sprint planning.
  • Automated documentation: Create C4 diagrams and structured markdown reports to document existing system architectures that lack up-to-date records.
namecodebase-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

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