Use when building a mental model of an unfamiliar repo. Trigger phrases: "how does this codebase work", "walk me through this project", "explain the architecture", "what does this service do", "trace how a request flows", "where does X live in the code", "onboard me to this repo", "I need to change Y, what does it touch", "map out the layers", "give me the tour". Reads the source to map architecture layers, trace execution paths end-to-end, and surface key abstractions + dependencies. Do NOT use for external library or framework docs (use docs-agent), for comparing approaches or tech choices (use research-agent), or for planning a concrete change (use writing-plans).
Systematic codebase analysis: maps architecture, traces execution paths, identifies patterns, and documents dependencies to give you a working mental model fast.
af context # project fingerprint: name, language, build system
af status # recent commits — what's actively changing?
Then scan:
ls -la # top-level layout
cat README.md # stated architecture
cat CLAUDE.md 2>/dev/null # engineering conventions
Key questions:
Identify the layers and name each one. Common patterns:
| Pattern | Layers |
|---|---|
| Web app | Routes → Handlers → Services → Repository → Database |
| CLI tool | Command parser → Command handlers → Core logic → I/O |
| Library | Public API → Internal modules → Utilities |
| Event-driven | Producers → Queue → Consumers → Side effects |
For each layer: which directories/files implement it? What does it receive and what does it return?
Pick the most important user action (a web request, a CLI command, a library call) and trace it end-to-end:
Grep to find function definitionsDocument as a numbered sequence:
1. Request hits POST /api/tasks → TaskController.create()
2. Controller validates input → TaskSchema.parse()
3. Service creates record → TaskService.create()
4. Repository persists → db.insert(tasks, ...)
5. Returns created task
Look for:
# Find exported types/interfaces
grep -r "^export (type|interface|class)" src/ --include="*.ts" | head -20
# Find dependency wiring
grep -r "new " src/ --include="*.ts" -l # constructors (DI candidates)
Write a brief summary covering:
You have enough when you can answer:
Stop before you've read everything — goal is a working model, not complete knowledge.