Analyzing Projects

Systematic approaches to understanding codebases, identifying patterns, and mapping system architecture.

When to Use This Skill

Onboarding to a new codebase
Understanding unfamiliar code before making changes
Investigating how features are implemented
Mapping dependencies between modules
Identifying architectural patterns in use

Core Analysis Framework

The 5-Layer Discovery Process

Layer 1: Surface Scan
  └─ Entry points, config files, directory structure

Layer 2: Dependency Mapping
  └─ Package managers, imports, module relationships

Layer 3: Architecture Recognition
  └─ Patterns (MVC, hexagonal, microservices)

Layer 4: Flow Tracing
  └─ Request paths, data flow, state management

Layer 5: Quality Assessment
  └─ Test coverage, code health, technical debt

Phase 1: Surface Scan

Entry Point Discovery

Start by identifying how the application launches:

Look for standard entry files:
- main.*, index.*, app.*, server.*
- cmd/ directory (Go)
- src/main/ (Java)
- bin/ scripts
Check configuration files:
- package.json (scripts.start, main)
- Makefile, Taskfile
- Docker/Compose files
- CI/CD configs (.github/workflows/)

Map directory structure:

Quick heuristics:
├── src/           → Source code
├── lib/           → Internal libraries
├── pkg/           → Public packages (Go)
├── internal/      → Private packages (Go)
├── tests/         → Test files
├── docs/          → Documentation
├── scripts/       → Build/deploy scripts
└── config/        → Configuration

Initial Questions to Answer

What language(s) and framework(s)?
What's the build system?
How is the app deployed?
Where are the main entry points?

Phase 2: Dependency Mapping

Package Manager Analysis

File	Ecosystem	Key Sections
`package.json`	Node.js	dependencies, devDependencies
`requirements.txt` / `pyproject.toml`	Python	direct dependencies
`go.mod`	Go	require blocks
`Cargo.toml`	Rust	dependencies
`pom.xml` / `build.gradle`	Java	dependencies

Internal Module Relationships

Trace imports from entry points

Build a mental model of layers:

Presentation Layer (routes, controllers, views)
      ↓
Application Layer (services, use cases)
      ↓
Domain Layer (entities, business logic)
      ↓
Infrastructure Layer (database, external APIs)

Identify shared utilities imported across modules

Phase 3: Architecture Recognition

Common Patterns to Identify

Pattern	Indicators	Typical Structure
MVC	controllers/, models/, views/	Clear separation of concerns
Hexagonal	ports/, adapters/, domain/	Dependency inversion
Microservices	services/, docker-compose	Independent deployable units
Monolith	Single large app, shared DB	Everything in one deployment
Serverless	functions/, handlers/	Event-driven, stateless

Architecture Questions

How are concerns separated?
Where does business logic live?
How are external dependencies abstracted?
What's the data access pattern?

Phase 4: Flow Tracing

Request Path Analysis

For web applications, trace a request end-to-end:

HTTP Request
    ↓
Router/Routes (maps URL → handler)
    ↓
Middleware (auth, logging, validation)
    ↓
Controller/Handler (orchestrates)
    ↓
Service/Use Case (business logic)
    ↓
Repository/DAO (data access)
    ↓
Database/External API

State Management Analysis

For frontend applications:

Where is state stored? (Redux, Zustand, Context)
How does data flow? (unidirectional, bidirectional)
What triggers re-renders?

Phase 5: Quality Assessment

Code Health Indicators

Indicator	Good Sign	Warning Sign
Test coverage	>70% coverage	No tests, or tests ignored
Dependencies	Recent versions	Major versions behind
Documentation	README updated	Stale or missing docs
Build time	Under 2 minutes	Over 10 minutes
Error handling	Consistent patterns	Swallowed exceptions

Technical Debt Markers

TODO/FIXME comments
Disabled tests
Large functions (>50 lines)
Deep nesting (>4 levels)
Duplicated code blocks
Hardcoded values

Analysis Strategies by Goal

Goal: Make a Bug Fix

Find where the bug manifests
Trace back to the root cause
Understand the affected area only
Check for related tests

Goal: Add a New Feature

Find similar existing features
Understand the patterns they use
Map the modules that need changes
Identify integration points

Goal: Full Codebase Understanding

Complete all 5 phases
Document architecture decisions
Create a mental map of key flows
Identify ownership areas

Parallel Analysis Pattern

When exploring a large codebase, parallelize by module:

Spawn subagents for each major area:
├─ Subagent 1: Analyze src/auth (authentication module)
├─ Subagent 2: Analyze src/api (API layer)
├─ Subagent 3: Analyze src/db (data layer)
├─ Subagent 4: Analyze src/ui (frontend)
└─ Subagent 5: Analyze tests/ (test patterns)

Synthesize findings into unified architecture view.

Output Templates

Quick Architecture Summary

## Project Overview
- **Language**: [Primary language]
- **Framework**: [Main framework]
- **Architecture**: [Pattern identified]
- **Entry Point**: [Main file]

## Key Modules
| Module | Responsibility | Key Files |
|--------|----------------|-----------|
| [Name] | [What it does] | [Files]   |

## Data Flow
[Request lifecycle diagram]

## Notable Patterns
- [Pattern 1]: [Where/how used]
- [Pattern 2]: [Where/how used]

Onboarding Checklist

## Getting Started
- [ ] Clone and install dependencies
- [ ] Run the app locally
- [ ] Run the test suite
- [ ] Trace one request end-to-end
- [ ] Find where [core feature] is implemented

Anti-Patterns to Avoid

Analysis Paralysis - Don't try to understand everything before starting
Ignoring Tests - Tests often document expected behavior
Skipping Config - Configuration reveals deployment context
Surface-Only - Don't stop at directory structure
Assuming Patterns - Verify patterns, don't assume from naming

Quick Reference

SURFACE SCAN:
  entry points → config files → directory structure

DEPENDENCY MAP:
  package manager → import tracing → layer identification

ARCHITECTURE:
  pattern recognition → separation of concerns → abstractions

FLOW TRACING:
  request path → data flow → state management

QUALITY CHECK:
  test coverage → code health → technical debt

analyzing-projects