Map structure and find relevant code so you can work effectively in an unfamiliar repo.
When to Activate
- User asks "where is X?", "how is this structured?", or "how does Y work?"
- Onboarding to a new repo or area
- Planning a change and needing to find entry points and dependencies
- Before implementing a feature (find where to add code and what to call)
Work Process
- Root layout — Inspect repo root: README, CONTRIBUTING, license, and dependency/manifest files (package.json, requirements.txt, go.mod, Cargo.toml). Note: language, framework, and main scripts (start, test, build). List top-level directories (app/, src/, lib/, tests/, docs/, scripts/) and infer purpose from names.
- Entry points — Identify how the app runs: main file (index.js, main.py, cmd/server), server bootstrap, or config that wires modules (e.g. Next.js app directory, Django ROOT_URLCONF). Follow from entry to key subsystems (routes, services, DB).
- Naming and conventions — Use naming patterns to infer purpose: *Controller, *Service, *Repository, api/, components/, hooks/, handlers/. Search for domain terms the user cares about (e.g. "payment", "auth", "export") in file paths, directory names, and symbol names.
- Trace dependencies — For the area of interest: what does it import or call (internal libs, external packages)? What imports or calls it? Use grep/search for symbol names, file names, and route paths. Build a minimal call graph in words (e.g. "Route → Handler → Service → Repository").
- Tests — Locate tests (*_test, *.spec, test/, tests/). They document usage and boundaries. Integration or E2E tests show how pieces connect and what the system does from the outside.
- Config and env — Config files, env docs (.env.example, README), and feature flags. They reveal services, endpoints, and toggles that affect behavior.
- Synthesize — Produce a short map (top-level structure + where main features live) and, for the user's question, list relevant files/modules and how they connect. Suggest "to change X, start in Y; then consider Z" and point to tests or docs.
Approach by Question Type
"Where is feature X?" — Search for domain terms (X, synonyms) in paths and symbols. Check routes, handlers, or entry modules. Follow imports to the core logic. Check tests that mention X.
"How does Y work?" — Find the entry point for Y (route, CLI command, job). Trace flow: request/input → handler → service → storage/external. Read tests for expected behavior. Summarize in 3–5 steps.
"Where do I add Z?" — Find the layer that owns similar functionality (e.g. new endpoint next to existing in api/, new component in components/). Check how similar features are structured (naming, files, tests). Recommend file and pattern to follow.
"What is the structure?" — From root and entry points, list top-level dirs and their role. Name main subsystems (auth, orders, reporting). Point to README or architecture doc if present. Do not claim completeness; say "from the explored areas" and suggest where to look next for more detail.
Deliverables
- Short map — "Top level: src/app (routes), src/lib (services), src/components (UI). Auth in src/auth; API routes in src/app/api; DB access in src/lib/db."
- For a specific feature or question — List of relevant files or modules; 1–2 sentence flow (e.g. "POST /orders → OrderController.create → OrderService → OrderRepository.save"). Optional: 2–3 bullet call chain or data flow.
- Next steps — "To change X, start in file Y; tests in Z. See also [doc or module]." If the codebase is large, suggest where to look next (e.g. "For permissions, see src/auth and middleware.").
Rules
- Prefer reading code and config over guessing. If the repo has an architecture doc, ADRs, or CONTRIBUTING, use them.
- Do not claim full completeness for a large repo; frame as "from the explored areas" and suggest follow-up exploration if needed.
- Use the project's own terms and module names when describing structure (e.g. use their "OrderService" not a generic "business logic layer" if that's what they call it).
- Search systematically — Use grep/search for symbols, paths, and domain terms; open key files and skim; do not rely on a single file to describe the whole system.
Checklist
- Root and manifest reviewed; stack and entry points noted
- At least one entry point traced into the relevant area
- Domain terms searched; relevant files listed
- Dependencies (imports/callers) traced for the area of interest
- Tests or docs used to confirm usage and boundaries
- Output includes map and/or flow and next steps
Anti-patterns
| Anti-pattern | Better approach |
|---|---|
| Describing one file as "the whole app" | Trace from entry to several modules; summarize layers |
| Guessing without opening files | Open and skim key files; use search to find references |
| Inventing structure (e.g. "typical MVC") | Describe what the repo actually has (their dir names, their patterns) |
| No next steps | Always suggest "start here" and "see also" so the user can act |