Codebase discovery

Codebase Discovery

State only what files or command output show. Scale the depth to the task: a one-line fix needs the file, its callers and its tests; a plan, a design or an estimate needs the whole loop below.

1. Rules and intent first

• Read the instruction files that apply: AGENTS.md, CLAUDE.md, CONTRIBUTING, README, nested ones in the folders you will touch, and the docs or ADR folder. They override your habits.
• Read the intent documents (PRD, spec, roadmap, design notes) and summarize what the project is meant to be before reading code. The README often describes the intended architecture, not the current one; check it against the code.
• Collect the commands the repo defines for build, test, lint, typecheck, run and migrate (package scripts, Makefile, CI workflow). Use those, not guesses.

2. Scan

• Stack from the manifests and lockfiles: languages, frameworks, versions. Production dependencies are the runtime stack; dev dependencies are tooling.
• Layout: apps, packages or modules and what each owns. In a monorepo, map each workspace separately; the root may hold no source.
• Entry points: server start, routes, CLI commands, workers, scheduled jobs, UI bootstrap.
• Configuration: where environment variables are read; the example env file lists them. Never print secret values.
• Resolve path aliases to real folders before describing structure. Ignore generated output (dist, build, .next, generated folders).

3. Investigate what the task touches

• Trace one real request or use case through every layer it crosses: entry point, validation, business logic, data access, external calls, response or UI.
• Data: migrations or schema, models, the tables and fields involved, and which code writes them. Name the database from the manifest, not from a variable name.
• Boundaries: external APIs, queues, caches, storage, the auth provider, and where each is wrapped.
• Conventions: naming, error handling, logging, imports, test layout, copied from neighboring code.
• Every use of what will change: callers, imports, string references, config keys, tests, docs.
• Risk: files that change most often in git history and code without tests are fragile; git log and blame explain surprising code before you remove it.

4. Validate with evidence

• Every claim in a plan or report points to a file path or command output. Do not claim an architecture the folders do not show.
• Keep three lists: confirmed, unknown (to find out or test early), and decisions that need the team's intent (ask).
• When code and documents disagree, the code shows what runs; report the mismatch.
• Check the starting state: does it build, do the tests pass? Record failures that existed before you began.

Output

• Keep findings in your plan or report: relevant modules with paths, the flow, the data touched, the commands, the rules that constrain the change, risks and open questions.
• Write a notes file only when the task asks for one, and then only one.

Before you finish

• Instruction files and intent documents read; intent summarized.
• Commands taken from the repo; starting state of build and tests known.
• The flow, data and boundaries the task touches traced in the real code.
• Every use of what changes found.
• Each claim backed by evidence; unknowns and questions listed.