How Much Context to Give an AI Coding Agent
A three-tier framework (task, repo, domain context) for scoping what to hand an AI coding agent, with a worked example of under- and over-context failure modes.
How Much Context to Give an AI Coding Agent
How much context to give an AI coding agent before a task depends on the task, not on a fixed rule of thumb like "more is always better." Too little and the agent invents a function that already exists three files away. Too much and it drowns a small, well-defined task in unrelated code, gets slower, and starts making changes outside the area you actually asked about. The right amount is the smallest set of files and constraints that make the task unambiguous, which is usually less than people assume. This is one piece of working effectively with AI coding tools generally, not a rule specific to any single one of them.
Three tiers of context, not one blob
Treat context as three separate layers rather than one pile of pasted files. Most of the judgment call is deciding how much of each tier a given task actually needs.
Tier | What it is | When it matters most |
|---|---|---|
Task context | The specific file(s) being changed and their immediate callers/callees | Every task, always include this |
Repo context | Conventions: naming, folder structure, how errors are handled elsewhere | Larger features, anything touching a new area of the codebase |
Domain context | Business rules a file comment won't tell you: pricing logic, compliance constraints, why a weird workaround exists | Anything where getting it subtly wrong is expensive |
A one-line bug fix in an isolated utility function needs task context and nothing else. A new feature that touches five files across the app needs task and repo context. Anything involving money, permissions, or a business rule that isn't obvious from the code needs all three, and skipping domain context here is the single most common cause of a technically-correct change that is still wrong.
Under-context: what it actually looks like
Not a crash, usually. The agent produces working code that quietly duplicates something that already exists, or reinvents a pattern the rest of the codebase doesn't use. A support-ticket status field gets implemented as a free-text string when every other status field in the app uses a shared enum. It runs, it passes a quick look, and it is now the one place in the app that will drift out of sync the next time someone updates the shared statuses.
The fix is not "paste the whole codebase." It is pointing at the two or three files that establish the pattern you want followed, explicitly: the existing enum, one file that consumes it correctly, and the file being changed. That is normally enough for the agent to follow the convention instead of guessing at one.
Over-context: the less obvious failure
Pasting an entire large file, or several unrelated ones, to be safe has a real cost beyond token usage. The agent has to weigh irrelevant code against the actual task, and on a genuinely large context window it tends to hedge: touching more than you asked for because a nearby function looked related, or missing the specific instruction buried in the middle of a long prompt. This is the same effect behind
why an AI coding agent reads so many files in the first place, agents lean toward gathering more context rather than less when the task is ambiguous, and a vague prompt with a huge pasted context makes that worse, not better.
A concrete example
Task: fix a bug where a discount code applies twice on the checkout page.
Too little: paste only the checkout component. The agent fixes the symptom in the UI, but the actual bug is in a shared cart-total calculation used by both checkout and the cart preview, so the preview still double-applies the discount.
Too much: paste the entire checkout module, the payment provider integration, and the user account system, none of which touch the discount logic. The agent spends its reasoning on code that was never the problem and has more surface area to accidentally change.
Right amount: the cart-total calculation function, its two call sites (checkout and preview), and the discount-code model. That is the actual blast radius of the bug, and it is what the agent needs to fix it in both places instead of one.
Finding that blast radius before you prompt, rather than guessing at context size, is the actual skill here. Search for every place the function or field in question is used before starting, not after the agent has already made a partial fix.
Repo-level conventions: give them once, not every time
If your codebase has real conventions, naming patterns, a preferred state management approach, how errors surface to the user, write them down once in a project-level instructions file most AI coding tools support, rather than re-explaining them in every prompt. This is the same principle as
naming variables so an AI coding agent understands your codebase: context you bake into the code and the project setup once is context you never have to paste again.
When you genuinely don't know what's relevant
Sometimes you are working in a part of the codebase you didn't write and don't fully understand yet. In that case, the right first task is not the fix itself, it is asking the agent to explain the area before changing it. See
how to get an AI coding agent to explain a legacy codebase for that as a distinct first step, and treat its output as the context-gathering pass for the real task that follows, rather than skipping straight to a fix with a guess at what matters.
The same instinct applies to planning any feature before generating code for it: know the shape of what you're touching first. See how to plan your data model before building an app with AI for the broader version of that discipline, applied before the data model exists rather than after a bug is found in it.
A rule that holds up in practice
Include everything the change could break, and nothing it can't.
Everything it could break means tracing usages, not guessing. Nothing it can't means resisting the urge to paste a whole file or module for safety when the actual change is narrow. Both halves take the same five minutes of looking before you prompt, and both save more time than they cost.
Frequently asked questions
Does a bigger context window mean I can stop being selective?
No. A larger window changes what fits, not what helps. Irrelevant code in the context still competes for the agent's attention regardless of how much room is technically available, and unfocused context is a common reason a well-resourced agent still produces an unfocused change.
Should I include test files as context?
Yes, when they exist for the code being changed. Existing tests are some of the highest-value context available: they show the intended behavior precisely, including edge cases a docstring won't mention, and they tell the agent what "still works after this change" actually means.
How do I know if I under-scoped the context after the fact?
The agent invents something that already exists elsewhere, ignores an established pattern, or asks a clarifying question that reveals it didn't see a relevant file. Any of those is a signal to add the specific missing piece and retry, not to start over with everything.
Is it different for a brand-new feature versus a bug fix?
A bug fix needs precise task context around the actual defect. A new feature needs more repo context up front, since there is no existing implementation to point at, and the risk shifts from missing a related file to producing something that doesn't match how the rest of the app is built.
How did this land?
About the author
Developer Advocate
Steve builds something with Swarmz every week and writes up what worked, what broke, and what he'd do differently. Tutorials and hands-on guides are his lane.
