Systematically explore and present the full architecture, structure, and content of any repository. Use when onboarding to a new codebase, before major refactors, or when the user asks "how does this project work?"
41:T171d,
Provide a comprehensive, structured understanding of a repository's architecture, components, and conventions by systematically exploring its structure top-down.
Follow this top-down algorithm. Each step builds on the previous one.
Read these files first (if they exist):
README.md / README.rst / README.txt
CLAUDE.md / .claude/rules/**
package.json / pyproject.toml / Cargo.toml / go.mod / *.csproj / build.gradle
Extract:
Run a top-level directory listing, then explore 1-2 levels deep in key directories.
# Top-level structure
ls -la
# Key directories (explore selectively)
find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/vendor/*' -not -path '*/__pycache__/*' -not -path '*/target/*' -not -path '*/.next/*'
Classify directories by role:
src/, lib/, app/, pkg/, internal/test/, tests/, __tests__/, spec/.env.example, CI/CDdocs/, doc/dist/, build/, out/, target/docker/, k8s/, terraform/, infra/Identify how the application starts and how data moves through it:
main.*, index.*, app.*, server.*, CLI entry, route definitionsLook for evidence of these patterns:
| Pattern | Signals |
|---|---|
| MVC / MVVM | controllers/, models/, views/ directories |
| Layered | domain/, application/, infrastructure/ |
| Microservices | Multiple services/ with independent configs |
| Monorepo | packages/, apps/, workspace config |
| Event-driven | Event emitters, message queues, pub/sub |
| Plugin-based | plugins/, hook systems, middleware chains |
Identify:
Look for:
.env.example, config/ directoryPresent findings using this template:
# Codebase Overview: {project-name}
## Summary
{1-2 sentences: what this project does and its primary technology}
## Tech Stack
- **Language**: {language} {version}
- **Framework**: {framework} {version}
- **Database**: {if applicable}
- **Key Dependencies**: {top 5-10}
## Directory Structure
{annotated tree showing key directories and their roles}
## Architecture
- **Pattern**: {MVC, layered, microservices, etc.}
- **Entry Point**: {file path}
- **Key Modules**:
- `{path}` — {purpose}
- `{path}` — {purpose}
- ...
## Data Flow
{how a request/action flows through the system, 3-5 steps}
## Development
- **Run**: `{command}`
- **Test**: `{command}`
- **Build**: `{command}`
- **Lint**: `{command}`
## Key Files
| File | Purpose |
|------|---------|
| {path} | {description} |
| ... | ... |
## Conventions
- {notable coding conventions observed}
- {naming patterns}
- {error handling approach}
## Notes
- {anything unusual, notable, or worth highlighting}
git log --oneline -20 reveals recent focus areas.gitignore and CI config — they show what the project considers important| User Intent | Depth | Focus |
|---|---|---|
| "Quick overview" | Steps 1-2 | Structure and stack only |
| "How does this work?" | Steps 1-4 | Architecture and data flow |
| "Full deep dive" | Steps 1-6 | Everything including config and quality |
| "Before refactoring" | Steps 1-5 | Architecture, patterns, and test coverage |
Understanding a codebase is not reading every line — it's knowing which lines matter.