Give an AI coding assistant enough repository context without overwhelming it

An assistant asked to “add pagination” returns code that uses a different database client, introduces a new response envelope, and ignores the project's authorization helper. The repository may already contain all three patterns. The problem is often context selection rather than lack of code generation ability.

Sending every file is not a reliable remedy. A huge context packet can bury the one route and contract that determine the change. The useful question is: what evidence does the assistant need to reason about this specific behavior? Consider an illustrative account activity page whose API currently returns every event.

Find the entry point by behavior

Start from the user action and trace its path. The activity page calls a client function, that function calls a route, the route applies account authorization, and a query reads events. Search for the visible label or endpoint first, then follow imports and callers. A directory named “services” is not proof that all business logic lives there.

Record the smallest path that explains the current behavior. Include the page or component, request helper, handler, query function, and relevant type. If pagination affects a shared client, include its consumers or a concise list of them. This establishes the blast radius without demanding a complete repository inventory.

Keep file names accompanied by responsibilities. “activity.ts owns the account-scoped query” is more useful than an unexplained list of twenty paths. When a responsibility is uncertain, say so. An uncertain mapping invites inspection; a confident guess invites implementation in the wrong layer.

Include the contract on both sides

A frontend type might say that events have a timestamp, while the server actually returns a string named createdAt. Include real request and response examples with synthetic data. Make empty results, errors, and optional fields visible. The assistant needs the wire contract, not just the most convenient interface declaration.

For pagination, show the current ordering and any stable tie-breaker. If several events share a timestamp, a cursor based only on that timestamp can skip or repeat records. Include the query's ordering fields and the database representation of identifiers. The context should explain why the cursor must encode the chosen boundary.

Include authorization inputs separately from client inputs. Account identity should usually come from the authenticated request context rather than an arbitrary browser-supplied account identifier. The assistant should see that constraint before proposing a reusable helper that accidentally accepts untrusted ownership information.

Supply a neighboring implementation carefully

An existing paginated endpoint can reveal naming, error handling, and cursor conventions. Include it as a reference with a statement of which properties apply. “Reuse the response envelope and cursor validation style; this endpoint has different authorization rules” is clearer than “follow this file.”

Do not treat the nearest example as automatically correct. Legacy code may use deprecated methods or contain the same bug you are trying to prevent. Compare the reference with installed dependencies and current project rules. The assistant can help identify differences, but the reference should be selected intentionally.

Prefer one strong example to several conflicting ones. If the repository contains two patterns, explain which one governs new changes and why. Otherwise the assistant may combine both, creating an implementation that resembles the project while obeying neither contract consistently.

Write a compact context packet

A useful packet contains the goal, current behavior, relevant files, contract examples, constraints, and verification command. Place the acceptance examples near the goal so they remain easy to find. Separate facts from guesses and list unresolved questions explicitly.

For the illustrative activity page, the goal is to fetch bounded pages without changing account isolation. The constraint is stable descending ordering by timestamp and identifier. The response includes events and a next cursor; the first page needs no cursor. The test should prove that equal timestamps do not create duplicates across pages.

Do not paste secrets, customer records, or an entire environment file. Replace values with synthetic equivalents while preserving shape. A fake identifier should still resemble the type the code validates. Removing every meaningful field to “sanitize” data can make the context unusable and encourage the assistant to invent missing details.

Let the assistant request missing evidence

Ask the assistant to inspect the provided path and return a short list of additional files it needs. This gives it room to discover a shared serializer or policy helper without granting an unbounded mandate to rewrite the application.

A practical prompt is: “Implement cursor pagination for this endpoint using the stated contract. Before editing, identify missing evidence that would change the design. Use existing dependencies. Preserve the server-derived account scope. Report callers affected by the new response shape.” This invites investigation while setting clear boundaries.

If the assistant asks for the whole repository, redirect it toward specific uncertainties. “Which import or call path requires more context?” turns a vague request into an evidence request. The guide on explaining unfamiliar code offers a complementary method for checking these mappings.

Verify that the context was understood

Before substantial edits, ask for a brief summary of the current path and intended contract. Compare that summary with the code. If it claims that the browser authenticates database access directly, but the actual route performs authorization, correct the misunderstanding early.

Review the first diff for context drift. New dependencies, renamed envelopes, and duplicated policy checks often indicate that the assistant missed an established pattern. A successful build does not establish consistency with callers. Run the existing client tests and inspect at least one integrated request.

Check the acceptance cases that the context emphasized. Pagination should remain account-scoped, empty pages should have a coherent cursor outcome, and malformed cursors should receive the agreed client error. If these behaviors are missing, adding more unrelated documentation will not help; refine the packet around the misunderstood constraint.

Maintain context as the task changes

Context becomes stale when a contract changes during implementation. Update the packet and remove abandoned assumptions so later requests do not refer to two incompatible designs. A short decision note can be more valuable than retaining the entire conversation.

For larger work, keep a task-specific note with links to source files rather than copying large code blocks that will diverge. Include the revision or branch if multiple checkouts exist. The assistant must know which implementation it is examining.

Focused context cannot replace engineering judgment. It reduces avoidable misunderstandings and makes mistakes easier to spot. The goal is enough evidence for a bounded decision, with a clear way to obtain more, rather than an attempt to compress the whole organization into a prompt.

Sources

GitHub Copilot best practices covers relevant context and checking generated work.

Anthropic: Building effective agents discusses understandable interfaces and composable workflows.