Codebase Onboarding with Coding Agents

Coding agents are useful onboarding partners because they can read the current repository instead of relying on old documentation.

The goal is not “explain the whole repo.” The goal is to answer focused questions with file-backed evidence.

Start With Focused Questions

Weak prompt	Better prompt
Explain this repo	Map the request path for user login, with files and functions
How does auth work?	Find where access tokens are created, refreshed, stored, and invalidated
What should I know?	List the top five conventions I need before editing `src/api/`
Summarize recent work	Summarize my last 20 commits and group them by feature area
Where do I add this?	Find the existing pattern for adding a new settings page

Focused questions keep the context window useful and reduce generic summaries.

Onboarding Workflow

Orientation: ask for the repo structure and the main runtime entrypoints.
Flow tracing: pick one workflow and trace it through files.
Convention extraction: ask what patterns repeat in nearby code.
History check: use git history to understand why confusing code exists.
Task rehearsal: ask where a small change would go, but do not edit yet.
Save durable notes: add only stable, reusable facts to project memory.

Prompt: Trace A Flow

Trace the login flow from route entrypoint to session creation.

Return:
- the files and functions involved
- the order they run in
- where errors are handled
- what tests currently cover this flow
- what is unclear or missing

Do not edit files.

Prompt: Learn A Local Pattern

I need to add a new settings page.

Find two existing settings pages, compare their structure,
and tell me the pattern I should follow.
Include file paths and any tests I should update.
Do not implement yet.

Prompt: Use Git History

Use git history to explain why `TokenRefreshService` changed recently.
Summarize the relevant commits and link them to current code behavior.
Do not modify files.

What To Save

Save only stable onboarding findings:

build and test commands
module boundaries
naming conventions
non-obvious architecture decisions
known local environment requirements

Avoid saving:

file-by-file summaries
stale TODO lists
long tutorials
information the agent can cheaply rediscover
personal notes that should stay local

Good Output Contract

For onboarding answers, ask the agent to include:

file paths
function or class names
confidence level
commands it ran
assumptions and open questions

This makes the answer easier to verify and prevents the agent from sounding certain about code it did not inspect.