The Agent Did Not Need More Context

The agent did not need more context. It needed a smaller write boundary.

That is the change I would make first to an agentic engineering workflow that keeps producing plausible but dangerous failures. The instinct is usually to add repository instructions, more files, more examples, or a larger model. Those can improve a decision. They do not stop a correct decision from being written into the wrong checkout.

I have been looking at this through the routine that publishes this site. The job runs from a shared temporary directory. It checks whether a portfolio repository can be reused, synchronizes it to the remote branch, edits one source file, commits that file, and pushes. The intended mutation is narrow: prepend one blog object to constants.ts.

The filesystem is wider than that intention. A build can regenerate feed.xml, sitemap.xml, or a metadata cache. Another scheduled job can be using a neighboring checkout. A failed push can leave a local commit behind. A broad staging command can collect any of those changes under a commit message that describes only one of them.

The agent can understand every one of these facts and still make the wrong write. Understanding is not containment.

Context answers a different question

Context helps answer: what should I do?

Boundaries answer: what am I physically able to change?

Those are different controls, and I have been treating the first as if it implied the second.

A long instruction file can say that only constants.ts should be committed. It cannot prevent a command like git add -A from staging a generated file. A model can know that two routines share /tmp/agents/professional-portfolio. It cannot prevent a concurrent routine from resetting that directory unless the workflow gives each run a private path or puts a lock around the checkout.

This is the same distinction as a limit on an order versus a risk limit. One describes the desired action. The other constrains the possible action. If the latter exists only as prose, it is not a control. It is a hope that the executor will remember.

The smallest useful boundary

For this routine, the write boundary should be a fresh per-run directory. Clone the repository into a path that no other run knows. Read the source there. Edit constants.ts there. Stage constants.ts by name there. Push from there. The directory should disappear only after the commit has either reached the remote or the failure has been made visible.

That design buys three properties immediately.

First, another routine cannot reset the checkout underneath the current run. Second, an unrelated generated file cannot enter the commit through a working-tree-wide staging command. Third, the diff is scoped to the artifact named in the job, so inspection has a meaningful target.

The tradeoff is not zero. A fresh clone takes time and consumes temporary disk. A private directory does not solve two runs pushing different commits to the same branch at the same time. That still requires a rebase-and-retry policy, or a queue, or a failure that reaches an external alert. But it removes one class of race instead of pretending that a paragraph about concurrency removed it.

What the agent should be allowed to see

There is a second boundary around read access. More context is not always more observability. It can make a run better at finding a topic while making it worse at identifying which evidence supports the post.

I want the routine to read the brand voice, the recent archive, and the standing preferences. I do not want it to silently turn every file in the parent workspace into a source of claims. The relevant evidence for a blog post should be explicit: the current repository, the files named by the routine, and any external source used for a dated fact.

That makes a claim auditable. If the post says a build passed, the run should be able to point to the command and its output. If it says a tool shipped, the run should point to a dated primary source. If it says nothing happened, that should mean the routine checked the relevant data, not that the prompt happened to contain no exciting material.

The goal is not to hide information from the agent. It is to stop an unmarked inference from becoming a published fact.

The check I trust most

The strongest guard is not a better instruction. It is a postcondition that fails against the artifact.

After the edit, compare the staged file list with the allowlist. Verify that the new id occurs exactly once. Verify that the body parses as the expected type. Verify the rendered route exists. Verify the remote branch contains the commit after push.

Each check closes a different gap. None asks the model whether it believes the work is complete.

That is the standard I want for agentic systems generally. Use the model for judgment where judgment is required. Use the filesystem, version control, and external state to enforce the edges. A model can choose a bad topic. A boundary can prevent it from publishing to the wrong channel. A model can miss a comma. A parser can reject the file. A model can report success too early. A remote commit check can disagree.

The useful question is not how much context the agent received. It is what remains impossible after the agent is wrong.

For a trading system, that might be an order above a notional cap. For a deployment system, it might be a write outside the release directory. For this blog routine, it is a commit that contains anything beyond the one source file the job was created to change.

Context improves the odds. Boundaries define the damage. I would like my agent workflows to be designed around the second number.