When an AI coding agent makes a poor decision, the first reaction is often to improve the prompt or switch to a more capable model. Sometimes that helps. But many failures have a more basic cause: the agent does not have the context a competent engineer would use.
It does not know why a service is structured in a particular way. It cannot find the decision that explains a dependency. It does not know the team’s testing conventions or which parts of the system are sensitive. The knowledge exists, but it is scattered across documentation, code, tickets, chat history and people’s memories.
This is why context engineering is becoming an important part of AI system design. The job is to make the right information, tools and constraints available at the right point in a task.
Context is more than a longer prompt
A prompt is an instruction. Context is the environment in which the instruction is interpreted. For an engineering agent, that environment may include:
- Repository guidance: build instructions, coding conventions, test commands and contribution rules.
- Architecture knowledge: system boundaries, service ownership, data flows and decision records.
- Examples: representative implementations and tests that demonstrate what good looks like.
- Task information: acceptance criteria, issue history, relevant incidents and product constraints.
- Tools: source control, issue trackers, CI, documentation and observability systems.
- Permissions: explicit limits on what the agent can read, change, execute or approve.
Dumping all available information into a context window is not the answer. Too much irrelevant information can make retrieval noisy, increase cost and obscure the detail that matters. The objective is useful, timely context — not maximum context.
Turn repeated work into reusable skills
Many engineering tasks follow a recognisable pattern. Investigating a bug, preparing a pull request, updating a changelog or triaging a dependency alert all involve a sequence of steps, expected evidence and boundaries.
These practices can be captured as reusable agent skills: instructions and supporting resources that describe how to perform a particular task. A good skill is specific enough to be useful, small enough to maintain and explicit about when the agent should stop.
There is an important distinction between a reusable skill and a permission. A skill can explain how to deploy a service; it should not automatically grant the agent production deployment rights. The host environment and tool configuration must enforce permissions independently of the instructions.
Context engineering as an architectural discipline
In a mature system, context should be designed and governed much like APIs and data contracts.
Make ownership explicit
Someone should own the accuracy of repository guidance, service documentation and reusable skills. Stale instructions are worse than missing instructions because they can give an agent confidence in the wrong approach.
Version the knowledge
Keep important instructions and skills close to the code they describe. Review changes through normal pull requests. When architecture changes, the corresponding guidance should change too.
Retrieve selectively
Use task-specific retrieval to find relevant documentation, code examples and decisions. Keep the agent’s working context focused, and record which sources influenced important decisions.
Evaluate the result
Test context changes against representative tasks. Does the agent choose the right service? Does it follow the team’s conventions? Does it run the right tests? Does it avoid restricted actions? A context file that reads well is not necessarily an effective one.
A practical starting point
Choose one repeated engineering workflow. Ask an experienced engineer to document the steps they actually follow, including the questions they ask, the tools they use and the evidence they expect. Turn that into a short skill and add the minimum repository context needed to execute it.
Run the same representative tasks with and without the new context. Compare correctness, review rework, task completion time and the number of times a human must intervene. Keep the skill only if it improves the outcome.
The knowledge layer of the AI-native organisation
As agents become more capable, an organisation’s ability to express its knowledge clearly becomes a differentiator. The codebase is no longer just instructions for a compiler and a record of what developers built. It is also a source of context for systems that can act on the organisation’s behalf.
That does not make architecture less important. It makes the knowledge around architecture more operational. The organisations that invest in clear decisions, reusable practices, well-defined tools and enforceable boundaries will be better placed to use agents safely and consistently.
The next model upgrade may improve what an agent can do. Better context determines whether it can do the right thing in your environment.