We need to stop writing markdown files to tell our coding agents how to behave. On a recent project, our repository accumulated a dense layer of instructions: CONTRIBUTING.md, AGENTS.md, CLAUDE.md, style guides, and runbooks. The theory was sound. We wanted the agent to understand our logging conventions, keep functions small, and run tests before pushing code. In practice, the agent read all of it, summarized it, quoted sections back to us, and then proceeded to ignore half of it.
Markdown documents are recommendations, not constraints. When you write "Use the existing logging conventions in the repository," the agent has to parse ambiguity. Which conventions? Where? When you write "Use small functions," the agent has to guess your exact threshold. This reliance on agentic judgment is where pipelines break down. The model wants to be helpful, so it looks at a rule requiring snake_case, spots a legacy file using camelCase, and decides the style guide might be outdated. It exercises discretion where you wanted mechanical obedience.
01Why Natural Language Fails as a Guardrail
Coding agents are inherently designed to be exploratory and open-ended. They take a vague prompt, generate a patch, run tests, and loop until something works. This loop is great for greenfield prototyping. It becomes a liability when you need repeatability. If you want the same refactoring applied across twenty files or a deploy process to execute in a strict sequence, vague prompts and sprawling documentation folders fail.
We watched an agent process a rule requiring its text output to follow standard plain-English technical writing constraints, limiting sentences to twenty words or fewer. The agent read the rule, said it understood, and then generated long, convoluted paragraphs anyway. Nothing in the prose forced an immediate check. The rule was just another token in the context window.
02Forcing Deterministic Execution Through Code
If you want predictable output, you have to take interpretation out of the loop. That means replacing documentation with executables. Instead of telling an agent to "follow the coding style," you point it to ./scripts/lint.sh and ./scripts/format.sh. Instead of asking it to "do the refactoring safely," you have it run an ast-grep, jscodeshift, or sed command.
Deterministic actions eliminate guessing. The agent runs a script and receives a binary pass or fail outcome. If the script fails, the agent sees the exact error output without needing to interpret intent. You transition from teaching the agent what you prefer to translating those preferences into hard code. You cannot execute a markdown document, but you can run a Makefile target, a shell script, or a test suite.
03Structuring the Agent Box
We now structure our agent environments around rigid command surfaces. A Makefile with explicit targets like make setup, make lint, make test, and make build gives the model zero room for philosophical debate. The agent does not need to understand our software architecture. It just needs to execute make lint and fix whatever fails.
This shifts the engineering focus from trying to make the agent smarter through more documentation to making the execution environment unambiguous. The agent remains clever within its boundaries. It reads test failures, makes targeted patches, and re-runs the commands. However, it cannot step outside the box. The guardrail is no longer a polite request in a .md file. It is a script that either exits with status zero or stops the pipeline cold.
