Context Engineering for Agentic Coding: What Goes in the Prompt and What Goes in the Codebase

Every team working with agentic coding tools eventually runs into the same problem. The agent behaves well in one session and inconsistently in the next. The same developer, working on the same codebase, gets noticeably different quality depending on how much context they happened to include that day.

The instinct is usually to write a longer prompt. That helps for exactly one session. It does nothing for the next developer who picks up similar work, or for the same developer three weeks later who has forgotten which details mattered.

The actual fix is not a longer prompt. It is deciding, deliberately, which context belongs in the prompt and which context belongs in the codebase itself, where it persists regardless of who is working or what they remember to mention.

Why this distinction matters more than it looks

A prompt is ephemeral. It exists for one session, gets whatever the developer thought to include at the time, and disappears once the task is done. If the same context is needed again next week, someone has to remember to include it again, or rediscover it the hard way.

A codebase is persistent. Anything encoded in the code itself, in its structure, its naming, its documentation, or its conventions, is available to every developer and every agent session from that point forward without anyone needing to remember to mention it.

The practical implication is straightforward. Context that will be needed repeatedly should live in the codebase. Context that is genuinely specific to a single task, and unlikely to matter again, can reasonably live in the prompt.

Most teams get this backwards. They accumulate a set of tribal knowledge about their own codebase that every senior developer holds in their head and every agent session has to be manually reminded of, because nobody has taken the time to write it down where the agent, and future developers, can actually find it.

What belongs in the codebase

A short architecture document, kept close to the code it describes rather than buried in a wiki nobody opens, closes this gap. It does not need to be long. It needs to answer the question a new developer or a fresh agent session would actually ask: why does this look like this, and what would break if it looked different.

Encoding these directly, as comments near the relevant code or as a dedicated known issues document referenced from the code, means an agent working in that area is far less likely to reintroduce a problem the team has already paid for once. This is one of the highest value additions a team can make to a codebase working with agentic tools, because it converts a one time expensive lesson into a permanent, reusable asset.

Where a convention exists for a specific reason, rather than by accident, stating that reason somewhere accessible helps an agent apply it correctly rather than following it superficially. A style guide that explains why a rule exists is more useful to an agent than one that states the rule alone, because the reason tells the agent when the rule genuinely applies and when an exception might be reasonable.

What belongs in the prompt

The test for where something belongs

A useful question to ask about any piece of context: if I did not mention this, and the agent got it wrong, whose fault would that be.

If the answer is the codebase's fault, because the information needed to get it right was available nowhere except a developer's memory, that context belongs in the codebase. If the answer is genuinely nobody's fault, because this was a reasonable judgement call specific to this task that could not have been anticipated, the prompt is the right place for it.

Applying this test consistently produces a codebase that gets more agent legible over time, rather than one that depends on an ever growing prompt to compensate for what the code itself does not communicate.

What this looks like in practice

A team that has done this well tends to have a small number of artefacts, kept close to the code rather than in a separate system nobody checks. A short architecture rationale document. A known issues or failure modes log that gets updated when incidents happen rather than only during a retrospective. Consistent naming with the reasoning documented where it is not obvious.

None of this needs to be extensive. It needs to be current, accessible from where the code actually lives, and treated as a living asset that gets updated when something new is learned, not a one time documentation exercise that decays the moment it is written.

Teams that invest in this find that agent output quality improves broadly, not just for the specific tasks the documentation was written for, because the agent is drawing on persistent, reliable context rather than whatever a given developer happened to remember to include that day.

The underlying principle

Prompts are for what is true about this task. Codebases should hold what is true about this system. Confusing the two means either writing the same context repeatedly in every prompt, which is wasted effort, or omitting it and hoping the agent infers correctly, which is where quality becomes inconsistent.

The developers who get the most reliable results from agentic tooling are not the ones who write the longest prompts. They are the ones who have done the work of making their codebase itself a better source of context, so the prompt only has to carry what is genuinely specific to the task in front of them.

At Navigaite, we place AI Native contract developers who understand this distinction and bring it with them into every codebase they work in. A developer who improves how a codebase communicates its own context leaves a team better off long after the engagement ends.

See what we do