---
name: analyzing-projects-2a150b2475ae
description: Guides systematic project analysis, codebase exploration, and architecture pattern recognition. Use when understanding new codebases, onboarding to projects, or investigating system structure.
license: MIT
compatibility: opencode
metadata:
  category: exploration
  audience: developers
---

# 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

| 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

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

| 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

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

```markdown
## 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

```markdown
## 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
```


---
Source attribution: diegosouzapw
Original project: https://github.com/diegosouzapw/awesome-omni-skill/blob/a6b3c3005cedf056a48b084671c6282426d6e9fc/skills/development/analyzing-projects/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: diegosouzapw
Original project: https://github.com/diegosouzapw/awesome-omni-skill/blob/a6b3c3005cedf056a48b084671c6282426d6e9fc/skills/development/analyzing-projects/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Product Management
Roles: Frontend Developer, Backend Developer, Full-Stack Developer, Product Manager, Technical Product Manager
Specialties: Backend, Frontend
Tools: Tool not specified
Country applicability: Country not specified
Classification basis: Source category, role and specialization labels
Instruction SHA-256: ffb8f3c1f4566ef17c391c4cb7d7117231ca8eacc5bc05e32e578a20d7571d69