analyzing-projects

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:

1. Look for standard entry files:

   • main.*, index.*, app.*, server.*
   • cmd/ directory (Go)
   • src/​main/ (Java)
   • bin/ scripts

2. Check configuration files:

   • package.json (scripts.start, main)
   • Makefile, Taskfile
   • Docker/​Compose files
   • CI/​CD configs (.github/​workflows/)

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

Internal Module Relationships

1. Trace imports from entry points

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

3. Identify shared utilities imported across modules

---

Phase 3: Architecture Recognition

Common Patterns to Identify

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

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

1. Find where the bug manifests
2. Trace back to the root cause
3. Understand the affected area only
4. Check for related tests

Goal: Add a New Feature

1. Find similar existing features
2. Understand the patterns they use
3. Map the modules that need changes
4. Identify integration points

Goal: Full Codebase Understanding

1. Complete all 5 phases
2. Document architecture decisions
3. Create a mental map of key flows
4. 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

1. Analysis Paralysis - Don't try to understand everything before starting
2. Ignoring Tests - Tests often document expected behavior
3. Skipping Config - Configuration reveals deployment context
4. Surface-Only - Don't stop at directory structure
5. 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