What the Agent Sees Decides What It Builds

Context goes into the agent, and output comes out

When an AI agent gives you a bad result, it is easy to blame the model. But think of a new teammate who is asked to add a feature and is never shown the codebase. Their result would be bad too, and nobody would blame their intelligence.

Most of the time an agent is in that same position. It did a reasonable job with what it saw, and what it saw was missing, outdated, misleading or too much. Looking after that is called context engineering.

What is context engineering?

Context is everything the model reads before it answers: your prompt, the code, docs, tickets, tool descriptions and earlier messages. Context engineering is choosing what goes in, so the model gets what it needs and little else.

A simple definition from Bharani Subramaniam of Thoughtworks, quoted by Birgitta Böckeler, is “curating what the model sees so that you get a better result”. Anthropic adds that context is a limited resource. The more you stuff in, the worse the model gets at using any of it, a problem often called context rot. So a bigger window does not mean you can paste everything.

Five ways context fails

Five ways context fails: absence, poisoning, distraction, confusion and clash

Drew Breunig named four of these: poisoning, distraction, confusion and clash. I would add a fifth, absence, which is when the agent was simply never shown what it needs. It is the one I hit first.

What happened in my work

Two failures: the agent never saw the app, and the old code overrode the requirements

I was building a task management module for store operations, to be added to an existing application. I hit two problems, in opposite directions.

Too little context. We had not thought hard about reusing the existing architecture initially as solution designing was in very early phases, so the agent was never shown the existing application. That application already had its own auth, yet the agent came back with new tables and new data models of its own. It was not careless. It designed a sensible standalone system because it could not see anything else. I only caught it because I read the output closely.

Wrong examples. Once the existing code was in view, the opposite happened. The agent leaned so hard on the old code that my requirements came second. And some of that code was not what I wanted copied:

• Logging. There was no common format. Logs looked like "task updated", and I wanted something searchable like event=task_updated task_id=42 user_id=7.
• Business logic in SQL. Rules were applied inside the query instead of in the application layer. That puts extra work on a database shared across teams. I wanted the query to fetch rows and the code to apply the rules.

The agent treats everything it reads as the house style, including habits the team would drop if it could.

What others do about it

1. Show a good example, not just the existing code. Böckeler’s “Anchoring AI to a reference application” keeps a small, compilable sample of each pattern, such as one well-written controller with proper logging, and has the agent copy it. She also uses it to find “drift”, places where the real code has moved away from the sample. For simple changes like adding a logger she points out that a deterministic codemod tool such as OpenRewrite may be better than AI.

2. Plan first and keep sessions short. Dex Horthy of HumanLayer works in three steps: research, plan, implement. When a session gets long, he has the agent write its progress to a file like progress.md and starts a fresh session from it. His warning is that a wrong understanding at the research step creates far more bad code than one bad line would, so he reviews plans and not only code.

3. Load only what is needed. Böckeler explains that a rule can be scoped to certain files. For example, a rule about SQL style only loads when the agent touches a .sql file. Skills are loaded on demand, and subagents work in their own fresh context. She also suggests growing your rules file slowly, because pasting in a long setup from someone else often leads to instructions that repeat or contradict your own.

4. Pair guides with sensors.

Guides steer the agent before it acts, and sensors check its work afterwards

Böckeler’s harness engineering model is easy to remember. Guides steer the agent before it acts, such as rules, examples and docs. Sensors check its work afterwards, such as tests, linters and type checks. With only guides you never learn whether they worked. With only sensors the agent repeats the same mistakes.

A small example: the guide says “use structured logging”. The sensor is a linter that fails with a message like “use log_event(), not print()", written so the agent can read it and fix the problem itself. When the same mistake keeps happening, the human improves the guide or the sensor.

5. Treat specs with care. Böckeler’s article on spec-driven development separates three levels. In spec-first, the spec is used for one task. In spec-anchored, the spec is kept and updated as the feature changes. In spec-as-source, humans only edit the spec. Her warning is that the extra markdown can be heavy for small changes, and in one trial the agent took notes about existing classes as if they were new requirements and built them again.

What we have put in place

Hooks update the knowledge base, and the agent reads it first

We have made three changes. They are new, so I have no results to report yet.

1. A knowledge base in the repo. One folder with a page per module explaining what it does. It acts as a map.
2. The agent’s instruction file points to it first. The agent reads the map before searching the whole repo.
3. Commit and push hooks that keep the map current. Each commit updates the knowledge base to match the change. Hooks run every time, so nobody has to remember. This also protects against poisoning, because a stale map would make the agent trust wrong information.

The design documents (high-level and low-level) also live in that folder, next to the code they describe.

Get Aadish N’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

One lesson came from planning. I exported our Confluence requirements page to PDF and attached it to a prompt. That worked, but a PDF is a snapshot, and it goes out of date the moment someone edits the page. Keeping the design in the repo helps with that.

Beyond the repo: suggestions

So far we have only worked on the repo side, with the knowledge base and hooks. We have not tried anything below yet. These are suggestions, based on the articles above, for making the rest of the delivery toolchain easier for an AI agent to use. Agents are increasingly connected to tools like Jira, Confluence and GitLab or GitHub, so a vague ticket or an outdated page can mislead an agent just as a missing repo map does.

One test sits behind all of them: could a new joiner act on this without asking anyone? If not, an agent probably can’t either.

Jira tickets: write a spec, not a reminder. Say why the change matters, what “done” looks like, and where to read more. A simple template is Why, What, Done when, Links and Out of scope.

• Before: “Add validation to signup form.”
• After: “Reject invalid emails at signup, because bounced welcome emails hurt delivery. Done when invalid emails return a clear error and tests cover it. See the signup design page.”

Keep each ticket to one problem, and keep its status honest.

Merge requests: explain the reasoning. Future reviewers, and future agents, read the description to understand intent. A useful template is What changed, Why, Alternatives not chosen, How it was tested and Links. The “alternatives” line matters most, because it stops someone from undoing a deliberate choice.

• Before: “Fixes bug.”
• After: “Fixes duplicate tasks when a user double clicks Save. I added a server-side check instead of disabling the button, because the API can be called from other places too.”

Confluence: keep pages current and easy to find.

• Give important pages an owner and a “last reviewed” date.
• Label pages as current or deprecated, and delete old ones. A missing page is safer than a confidently wrong one.
• Keep a short glossary of domain terms, such as “Task: a unit of work assigned to a staff member.”
• Record big decisions in a few lines each: what we chose, why, and what we rejected.
• Keep lasting knowledge (principles, contracts) apart from status updates that expire.

Data and schemas: say what values mean.

• Before: status: int
• After: status: 0 = draft, 1 = published, 2 = archived

Keep a simple data dictionary with an owner and a source for each important field, and update it in the same change as the schema.

Keep one source of truth. Avoid the same information in three places, and link instead of copying. A split that makes sense is to keep requirements in Confluence, work items in Jira, and anything that changes with the code, like design notes, in the repo. This is also the lesson from my PDF export: a copy is a snapshot, and snapshots go stale.

Connect tools carefully. Böckeler notes that an agent can reach Jira or a knowledge tool through an MCP server or a skill, such as a skill that explains how to fetch a ticket. Every tool you add takes up space in the agent’s context, so connect only what the task needs.

Keep the agent’s instruction file short (AGENTS.md or CLAUDE.md). One study of these files found agents do follow them, but task success did not improve much overall. Write down only what the agent cannot work out from the code, and add a line when it makes the same mistake twice.

What I do not know yet

I do not know if the hooks will keep the knowledge base accurate over months, or how often the agent will still slide back to the old patterns. Böckeler’s warning about an “illusion of control” applies here: a rule in a file is only a hope until you have watched the agent follow it. Next I want to add a sensor, such as a check on log format that gives the agent a clear message when it fails. I will write a follow-up when I have real results.

For now, the lesson is simple. When an agent gives you a bad result, check what it was shown before you blame the model.

Further reading

• Birgitta Böckeler, “Context Engineering for Coding Agents”: https://martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html
• Birgitta Böckeler, “Harness Engineering for Coding Agent Users”: https://martinfowler.com/articles/harness-engineering.html
• Birgitta Böckeler, “Anchoring AI to a reference application”: https://martinfowler.com/articles/exploring-gen-ai/anchoring-to-reference.html
• Birgitta Böckeler, “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl”: https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html
• Kief Morris, “Humans and Agents in Software Engineering Loops”: https://martinfowler.com/articles/exploring-gen-ai/humans-and-agents.html
• Anthropic, “Effective Context Engineering for AI Agents”: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
• Drew Breunig, “How Contexts Fail and How to Fix Them”: https://www.dbreunig.com/2025/06/22/how-contexts-fail-and-how-to-fix-them.html
• Dex Horthy, “Advanced Context Engineering for Coding Agents”: https://humanlayer.dev/blog/advanced-context-engineering
• “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?”, arXiv 2602.11988