Grounding with Your Codebase
Point the model at the real files and symbols it needs so answers match your codebase instead of a generic guess.
TL;DR
- Ground answers in your real code by referencing the actual files, symbols, and examples.
- Let the tool retrieve relevant files just-in-time rather than pre-pasting everything.
- Verify the model used your real code, not an invented version with the same names.
Reference Reality
Name FilesPoint at the exact files the task concerns.
"Update src/auth/session.ts and its
test."Name SymbolsReference the real functions and types by name.
"Use the existing `getSession` and
`AuthError`."Point At A PatternCite a canonical file to imitate for consistency.
"Follow the structure of
src/features/orders."Just-In-Time Context
Let It RetrieveHave the agent read referenced files when a step needs them.
"Read the files you need; don't
guess their contents."Lightweight PointersGive paths and symbols, not the full text, when the tool can fetch them.
"Relevant: src/db/schema.ts,
`User`, `Order`."Stay FocusedPull in only what the current step requires.
Read per step, not the whole repo
up front.Use Search Well
Locate UsagesAsk it to find where a symbol is defined and used before changing it.
"Find all callers of `formatMoney`
before you change it."Map Before EditHave it survey the relevant area before editing blindly.
"List the files involved in checkout,
then propose changes."Respect BoundariesScope retrieval to the relevant directories.
"Search only under src/payments."Verify Grounding
Ask What It ReadHave it list the files and lines it actually used.
"Which files did you read for this?"Quote The SourceMake it cite the real lines it relied on.
"Quote the current signature of
`getSession`."Confirm No InventionCheck the referenced code actually exists as described.
Open the file; does it match what
the model claimed?Tips
- Reference files and symbols by name so an agent can open exactly what it needs.
- Point at a canonical implementation to copy, so new code matches established patterns.
Warnings
- Models reconstruct plausible versions of your code from names; confirm against the real files.
- Dumping the whole repo into context buries the relevant parts and degrades the answer.
In Practice
Instead of describing your code, you reference the real files and symbols, let the agent retrieve them, and require it to confirm what it read, so the change is built on your actual codebase.
- The prompt names the exact files and symbols the change touches.
- It tells the agent to read them rather than guess their contents.
- It asks the agent to find callers first, so the change is safe.
- It requires the agent to confirm what it read, exposing any invention.
Task: add an `expiresAt` field to sessions and enforce
it on validation.
Ground yourself first:
- read src/auth/session.ts and src/db/schema.ts
- the relevant symbols are `getSession`, `createSession`,
and the `Session` type
- find every caller of `getSession` before changing it
Then propose a plan. Follow the patterns already in
session.ts. Do not guess the contents of these files;
read them. When you present the plan, quote the current
`Session` type and `getSession` signature so I can
confirm you're working from the real code.FAQ
It means the model's answer is based on your actual files, types, and patterns rather than a generic reconstruction. You achieve it by referencing real files and symbols, letting the tool read them, and pointing at canonical examples, so the output fits your project instead of a textbook version.
Prefer just-in-time retrieval for agents that can read the repo: reference the file or symbol and let the tool pull it in when needed. Paste manually in chat tools that cannot see your files. Either way, give the specific references, not the whole repo.
Rather than loading everything up front, the agent keeps lightweight references (file paths, symbol names) and reads the actual content only when a step needs it. This keeps the context window focused and lets the model work in large codebases without drowning in irrelevant code.
Check it. Ask which files it read and have it quote the relevant lines, then confirm against the source. A model can produce a confident answer about a function it never actually saw, inferred from the name, so verify before trusting.