Context budgets for coding assistants in large repos

Why big repos confuse coding assistants

Large repos give coding assistants too many possible explanations for how the system works. The model sees old patterns, half-finished migrations, duplicate helpers, legacy endpoints, and several ways to solve the same problem. If you ask a narrow question and send all of that, the model has to guess which parts matter.

That guess often fails in a very specific way. The answer looks tidy, sounds confident, and still misses the real contract the code has to follow. The assistant may latch onto a file that looks related but has nothing to do with the task, copy a pattern the team stopped using months ago, or edit code that should stay untouched.

This is why context budgets matter so much in large repos. The limit is not just tokens. It is attention. Every extra file competes with the files that actually define current behavior, and weak signals can drown out the useful ones.

A common mistake is treating more context as better context. Teams dump whole folders into a prompt because they want the assistant to "understand the project." In practice, that usually makes the answer worse. The model starts blending unrelated modules, pulling in the wrong types, or solving the wrong problem.

Mixed context produces code that feels plausible but does not fit. You might get a new function that matches the team's naming style and formatting, yet ignores the API schema, the test setup, or the business rule that controls the feature.

Take a billing change. The assistant usually does not need the whole monorepo. It needs the route handler, the request and response types, the service that owns billing logic, and the test that shows current behavior. That smaller packet gives the model a much better shot at a safe answer.

When teams use coding assistants in a large repo, focus beats volume. The model writes better code when you feed it the files that define the contract and the files you plan to change. Everything else increases the odds of a confident wrong answer.

What belongs in the prompt

Most teams send too much. The model then spends attention on files that do not control the change, and the answer gets fuzzy.

Start with the files that define the contract. Depending on the task, that might be an API spec, shared types, an interface, a schema, a validation rule, a test that locks behavior, or component props that other code already depends on. If you are changing a payment endpoint, the OpenAPI file, request and response types, validation rules, and the failing test matter more than the rest of the billing folder.

Then add only the files the task touches right now. In a mixed stack like Next.js with Go or Python services behind it, that might mean one handler, one UI form, one shared type file, and one migration. That is often enough for a first pass.

A small pattern example can help, but only if it truly matches. One nearby file might show naming, error handling, or test style. After that, extra examples usually add noise.

A lean prompt often has four parts: the contract file, the implementation file you will edit, the test that proves the change, and one nearby example that follows the same pattern.

Leave out folders that do not shape the decision. Old experiments, generated clients, build output, copied vendor code, and broad utility directories usually waste tokens. Huge logs and long CI files do the same unless the task is about deployment or debugging.

Good context feels a little narrow. That is not a flaw. The assistant does better when it can see the rules, the active files, and one clear precedent.

How to build a useful context packet

Start with the work item, not the code. A ticket, bug report, or change request tells the assistant what changed and why. Without that, it tries to infer the goal from whatever files you send.

Next, pull in the files that define the contract. These usually include request and response types, schema files, interface definitions, validation rules, and any short spec that fixes behavior. They tell the model what must stay true.

After that, add the code that carries the change today. Pick the controller, service, component, job, or query file you expect to edit. If the task touches one endpoint and one validator, send those. You do not need half the folder just because it sits nearby.

Tests matter more than many teams think. One or two relevant tests often beat ten extra source files. Tests show expected behavior in concrete terms, and they expose edge cases that a quick code scan can miss.

Add one short instruction before the files. Keep it plain and specific. A sentence like "Add a status filter to the orders endpoint. Keep the response shape the same. Update tests for invalid values" gives the assistant a clear target without wasting space.

A small team can build this packet in a few minutes. If a developer needs to add a field to an API response, they can usually send the ticket, the response type, the handler, the serializer, and the test that checks the JSON shape. That is enough for a focused answer.

Refresh the packet as the task moves. If a simple UI tweak turns into a database change, swap in the migration, schema, and repository code. If the task shifts from feature work to a failing pipeline, remove product files and add the CI job, script, and error output. Stale context quietly drags the model off course.

Which files usually matter most

When an assistant sees the whole repo, it often grabs the noisiest files instead of the ones that define the job. You usually get better results from a small set of files that answers two questions: what shape must this code follow, and what changed right now?

API schemas and shared types usually deserve a spot first. They define field names, enums, null rules, and response formats. If you need to add a property, those files show where that property starts and where it has to end up.

Boundary files matter too. Service interfaces, repository methods, component props, and event contracts tell the model what the rest of the code already expects. Without them, the assistant may invent a new calling pattern that breaks existing code.

Nearby tests often explain behavior better than comments. They show expected output, error handling, and awkward edge cases that a happy-path read will miss.

Config files only matter when they can change runtime behavior for the task at hand. Feature flags, route config, dependency injection setup, build settings, and lint rules can turn correct-looking code into broken code. If they do not affect the change, leave them out.

Recent diffs can also help. They reveal current naming, fresh rules, and local conventions. If the team renamed accountId to customerId yesterday, the assistant should follow that move instead of bringing the old name back.

For a checkout update, four files often beat forty: the OpenAPI schema, the TypeScript types, the failing test, and the latest relevant diff in the billing module. That packet tells the model what the request should look like, what callers expect, what counts as correct, and what the team already changed.

If you only have room for a few files, start with the contract file, the boundary interface, the nearest test, and the most recent change that touches the same area. Those usually carry more signal than a full repo tree or a long paste of unrelated helpers.

A realistic example from a product team

A product team needs a small checkout change: a discount should apply only to full-price items, not to items that already have a sale price. The repo is large, with billing code, account logic, admin screens, email templates, and several services that have nothing to do with this rule.

Most bad answers start with an oversized prompt. The assistant sees half the repo and starts guessing how discounts connect to invoices, user roles, or back-office tools.

For this task, the team keeps the prompt tight. They send the pricing types used at checkout, the discount calculation code, the checkout tests that cover totals and line items, and one short note with the new rule.

That is enough. The assistant can see the input shape, the expected output, and the place where the rule lives.

It does not need the billing service, because billing charges the final amount after checkout already finishes. It does not need auth files, because user identity does not change the math. Admin files stay out too, unless the task also changes how staff create discount rules.

With that smaller prompt, the answer usually stays inside the pricing contract. The assistant updates the discount function, keeps the return type the same, and adds or edits tests for mixed carts. A cart with one full-price item and one sale item now gets the discount only on the eligible line.

This is where tight context pays off. The model has less room to wander, so it makes fewer broad edits and fewer risky assumptions.

Teams that work this way often get code that is easier to review. The change stays small. One rule changes, two tests move, and billing stays untouched.

Mistakes that waste context

The fastest way to get a messy answer is to send too much code. In a large repo, dumping whole folders into one prompt makes the model chase side paths. It starts reasoning about old utilities, shared tooling, or unrelated services, and the answer loses focus.

Mixed versions of the same logic cause a different problem. A team might include the current checkout service, a refactor branch from last quarter, and a deprecated handler kept around for rollback safety. The assistant now sees several versions of the truth at once. It may copy the wrong payload shape, reuse dead fields, or suggest a fix in code nobody plans to keep.

Leaving out tests is expensive. Comments say what people hoped would happen. Tests show what the code has to do today. If a test expects a 409 response, a specific error message, or a retry after a timeout, that file defines behavior more clearly than a long description ever will.

Another common mistake is sending helper files without the files that define the contract. Utility code can explain formatting or shared helpers, but it rarely tells the assistant what inputs, outputs, and rules matter. Start with the schema, interface, type definitions, failing test, or handler under change. Add helpers only if the main files call them directly.

Stale context is easy to miss when the task shifts. You start by fixing a bug in a serializer, then discover the real issue sits in request validation. If you keep the old files and keep adding new ones, the prompt turns into a scrapbook. Stop, trim it, and rebuild around the new task.

One long chat can create the same problem. People keep an assistant session open for hours, then wonder why answers start to drift. Once the goal changes, or once the model starts mixing old assumptions into new work, start fresh.

A simple check helps before every prompt: which files define behavior now, not which files seem related? That one filter cuts noise quickly.

How to make this routine

Good context selection should not depend on who happens to ask the assistant that day. Teams get steadier results when they treat it like any other engineering habit: documented, shared, and easy to repeat.

A short repo map helps more than most people expect. It does not need to explain the whole codebase. It only needs to answer a few practical questions for common tasks: where bug fixes usually start, which files define each API, where tests live, and which configs can change behavior.

Each domain area should also have a clear set of contract files. In payments, that might be the request schema, the service interface, and the integration test that shows expected behavior. In auth, it could be the middleware, token format, and permission rules. Once teams label these files in a lightweight way, people stop guessing.

Store a couple of prompt templates where the team already works. One can fit bug fixes. Another can fit small features. Keep them plain: task, expected behavior, files included, files excluded, and what the assistant should not change.

A simple routine is enough:

• pick the task type
• load the matching prompt template
• add the contract files for that area
• add only the files touched by the current change
• reset the chat when the task or domain shifts

Teams should also review bad AI answers without turning it into a blame exercise. Look at the prompt, the file set, and the result. Many failures come from the same two causes: missing contract files or too many noisy files. Once you trace mistakes back to context, this becomes a team skill instead of personal trial and error.

This is also the pattern Oleg Sotnikov talks about in his AI-focused CTO work at oleg.is: give the model the contract, the local logic, and the proof. If the task is narrow, the context should be narrow too.

What to do next

Start with one narrow workflow and test the idea there first. Bug fixes are a good place to begin. Small refactors work too. Both have clear tasks, short feedback loops, and fewer moving parts than a large feature.

Write down the files that count as the contract for that area. Keep the list short on purpose. For a bug in an API endpoint, that might be the handler, the request and response types, one test file, and the schema or interface that other code depends on. If a file does not define behavior or affect the task, leave it out.

Then measure something the team can see without arguing about it: do answers get to a usable draft faster? If people need fewer retries, fewer follow-up prompts, or less manual cleanup, the context is tighter and more useful. If results still drift, the contract list is probably too vague or too large.

This does not need a long process document. A one-page note in the team space is enough. The goal is to make repo context selection easy to repeat, not perfect.

For teams that rely on coding assistants every day, this habit adds up fast. Ten minutes spent choosing the right files can save much more time in rework and review.

If you need help setting up that kind of workflow, Oleg Sotnikov offers Fractional CTO and startup advisory work focused on practical AI-driven development and automation. That is often useful when a team needs outside help defining contract files, prompt rules, and a lightweight process that people will actually keep using.

Keep the method simple enough that people will use it next week. If it feels heavy, it will die. If it fits into the way your team already fixes bugs and ships code, it will stick.