Understanding your codebase

You do not need to read every file before using an agent. With 4RGE, the reliable order is the same as onboarding with a teammate — just faster:

Ask → map → verify → then edit.

This lesson covers how to explore a repo — new project, new service, or a corner you have never touched — without turning exploration into a reckless refactor. Understand first, change second.

What this page is for

Who this page is for

The explore loop in four moves

The agent is a fast tour guide, not an oracle. Your editor and tests stay the source of truth — Hallucination & limitations.

Explore before you edit

Agents can edit on the first message — that does not mean they should. Wide changes on code you have not oriented to are how teams get surprise diffs and broken conventions.

Say "inspect only" or "no file changes yet" when you want exploration. That keeps the run focused and saves context for when you actually implement.

Ask like a teammate

Good exploration prompts sound like Slack messages to someone who knows the repo:

Start narrow (one flow, one feature, one error). Go broad only after you have an entry point. If you know a symbol or file name, say it — that gives the agent a precise target. If you only know the feature name, describe behavior and let the agent search.

How the agent finds code

You describe what you need; the agent searches and reads — it does not magically hold the whole repo in memory — Context.

You do not need to run search commands yourself. For large surveys, a summary back to your main chat is intentional — it keeps the thread readable. If you need a specific file, ask to show the path or @ mention it — Prompting.

Anchor when you can

When you know where to start, attach it:

Open the right folder — repo root vs one package in a monorepo — so search stays in the tree you care about. Wrong root is the #1 "agent can't find my code" issue.

Example explore prompts

Copy, edit, and paste. Say "inspect only — no file changes" when you want read-only exploration.

Monorepo orientation:

Inspect only — no file changes.
What are the main packages in this monorepo and what does each own?
Then walk one flow: login → session storage → protected API route.
Show file paths for each step.

Find where behavior lives:

Where do we validate JWTs on incoming API requests?
List the middleware or handler files and who imports them.
Inspect only.

Before changing something:

I'm about to change UserService.updateProfile.
Who calls it, what tests cover it, and what would break if the signature changed?
Show evidence (file paths). No edits yet.

Learn the existing pattern (before building):

Show how we already implement coupon/discount logic — files and flow.
I want to add discount codes at checkout using the same pattern.
Inspect only; summarize in bullet steps.

Verify a claim:

You said checkout calls PricingService.applyDiscount.
Open that file and quote the handler — confirm callers with search results.

When the map is clear, start a new run with implementation — Developing features. For @ mentions and attachments, see Prompting.

Build a mental map

Use the agent to compress orientation into something you can remember:

Take notes or save the agent's summary in your team's docs. The next person (or your next run) starts ahead — you do not need to re-explore from zero every time.

When the map feels clear enough to change one thing safely, switch to a new run with a scoped implementation ask — Working with agents.

Verify — don't memorize the chat

Exploration answers can sound authoritative and still be wrong — Hallucination & limitations.

Treat exploration like a tour guide, not a source of truth. Your editor and tests are the truth.

What good exploration looks like

Habits that work

1. Questions before refactors — always.
2. Read-only first on unfamiliar code — explicit "no edits."
3. One flow per run — auth today, billing tomorrow.
4. Name symbols when you know them — faster than vague feature words alone.
5. Copy patterns — "match existing X" beats greenfield invention.
6. New run to implement — exploration context is noisy for clean diffs.
7. Verify key claims — especially before deleting or moving code.

Leads: encourage new hires to spend their first agent sessions exploring with these prompts before assigning production edits.

Where to go next

Questions about understanding code?