Use case
How to Understand an Unfamiliar Codebase with AI
Use AI coding agents to trace real call paths, map state and dependencies, verify claims against source, and prepare precise onboarding questions.
Verdict
Use AI to trace one real behavior through an unfamiliar repository, with every claim tied to a file, symbol, line, command, or runtime observation. The useful deliverable is a checked call-path map plus unanswered onboarding questions. A polished “complete architecture” summary produced before you can verify it is a liability.
This workflow is for learning what exists before changing it. If the goal is a durable public or internal reference, use the separate technical-documentation workflow. Product selection starts with the AI coding-agent guide or CLI agent shortlist.
Start from a behavior, not the repository root
Pick one question with an observable boundary: “What happens after POST /checkout?”, “Where is this feature flag evaluated?”, or “Which job sends a renewal email?” Record the exact revision, runtime, build command, and available test command. Ask the agent to inspect only at first; disable edits or work in a disposable branch.
Begin with entry points, package boundaries, configuration, state stores, queues, external services, tests, and generated code. Then follow the chosen behavior from input to output. Search imports and callers in both directions. Read dependency injection, middleware, framework registration, build files, migrations, and environment loading rather than inferring them from filenames.
Require an evidence table
Make the agent separate observation from inference. Each important row needs a source pointer and confidence:
| Claim | Evidence required | Useful challenge |
|---|---|---|
HTTP request reaches createOrder | Route registration, middleware chain, handler file and lines | Is another router mounted first? |
| Handler writes an order | Repository call plus transaction and database mapping | Which commit or rollback path wins? |
| Event starts fulfillment | Publish call, topic configuration, consumer registration | Is delivery synchronous, retried, or optional? |
| Test covers the path | Test name, fixture, assertion, exact command | Does it execute production wiring? |
Use “unknown” when runtime configuration, secrets, infrastructure, generated artifacts, or tribal knowledge are missing. Do not let the agent fill those gaps with a conventional architecture.
Trace and verify one call path
Ask for a numbered path containing file:line, symbol, inputs, outputs, side effects, errors, and the next hop. Spot-check every critical transition in source. Run read-only discovery commands and a targeted existing test when the environment allows it. A passing test shows only what its assertions cover; it does not validate the entire map.
Analyze checkout creation at revision 8c31a2f. Do not edit files.
Trace POST /checkout from route registration through authorization,
validation, service calls, database transaction, emitted events, and response.
For every hop, give file:line, symbol, data shape, side effect, error path,
and evidence for the next hop. Label inference and unknowns. List generated,
runtime, or external behavior you cannot inspect. Then propose five source
checks and five questions for maintainers. Do not write a general repo summary.
In a community discussion, Reddit user u/Plastic-Risk-6309 recommended mapping entry points and state, then walking one bug’s call path with file-and-line references to spot-check. That is one practitioner’s method, not measured onboarding evidence, but it directly addresses stale or over-compressed summaries.
Produce an onboarding packet someone can challenge
An illustrative deliverable for the hypothetical checkout example could contain:
scope: POST /checkout at 8c31a2f
entry: api/routes/checkout.ts:42 -> createCheckout
path: auth middleware -> request parser -> CheckoutService.create
-> OrderRepository.insert -> eventBus.publish("order.created")
state: Postgres orders + idempotency_keys; transaction boundary unresolved
checks: route test command; consumer registration search; migration inspection
unknowns: production queue retry policy; owner of fraud rules; dead-letter alert
maintainer questions: Which service owns retries? Is duplicate publish tolerated?
Add a compact dependency diagram only after verifying its edges. Include a reading order for the next engineer: contract, entry point, orchestration, state adapter, consumer, and tests. Store the packet with its source revision so readers can tell when it became stale.
Choose the agent by control surface
Pricing and limits checked October 2, 2026.
| Tool | Best fit here | Current price and limit reality |
|---|---|---|
| Claude Code | Interactive exploration with read access and explicit edit gates | Pro is $20 monthly or $17/month with $200 billed annually. Claude Code shares rolling five-hour and weekly limits with other Claude surfaces; there is no fixed message count. API-key use is metered separately. |
| OpenAI Codex | Isolated repository tasks and reviewable notes in a worktree | Plus is $20/month; Pro starts at $100. OpenAI currently estimates 15–160 GPT-6.1 Sol local messages per five hours on Plus, with task-dependent use; local and cloud share allowance and weekly limits may apply. API billing is separate. |
| Aider | A terminal workflow where a repository map helps choose the next files | Aider is Apache-2.0 software. Its map is selective and token-budgeted, not a complete architecture. Provider API prices, rate limits, and context limits apply. |
Stop when a critical hop lacks source or runtime evidence, the checked-out revision differs from production, generated code is unavailable, tests cannot reproduce wiring, or maintainers disagree about ownership. Convert those gaps into questions before any legacy refactor. If a change follows, require unit-test evidence and a separate pull-request review.
Sources & further reading
Ordered for comparison, not as a universal ranking. Inclusion requires a direct fit with this page's stated workflow.