The failure is social before it is technical
The pattern repeats across teams. Someone turns on an agent, watches it work, and then one day the read-only dropdown is gone, or the agent keeps editing while they are still reviewing the first diff. An hour later the branch has forty changed files, half of them unrelated, and nobody can say why src/legacy/ was touched.
The complaint that follows is always the same shape: I no longer know this code, or how it works.
That is not really a bug in the agent. It is a policy that was never written down, being discovered one incident at a time.
A better prompt does not fix this
The instinct is to write a longer prompt: “do not modify unrelated files, do not delete tests, do not touch the deploy config.” It works for the rest of the session and then evaporates.
A prompt is per-session and per-person. A file in the repository is read by every session, every teammate and every agent you switch to — and, crucially, it can be reviewed like code. The team argues about the rules once, in a pull request, instead of every time an agent surprises somebody.
Four guardrails, in the order they pay off
1. A rules file. AGENTS.md (or CLAUDE.md, or whatever your agent reads from the project root) states what “done” means: the commands that verify a change, the paths that are off limits, and the things the agent must never do on its own. Keep it short enough that a human reads it too.
2. Permission lists. Three lists, and the shape matters more than the syntax:
| List | What belongs there | Example |
|---|---|---|
| allow | read-only inspection, plus the test/lint/build commands the project already uses | Bash(pnpm test:*) |
| ask | anything that rewrites history, installs packages or reaches the network | Bash(git push:*) |
| deny | secrets, production config, deployment pipelines, destructive shell commands | Read(./.env) |
Anything not listed should fall back to asking a human. The failure mode to avoid is a permission set so permissive that nobody reads it.
3. Protected paths. Secrets, production configuration, database migrations and CI definitions should be named explicitly, both in the rules file and in .gitignore. This turns a judgement call into a mechanical check, which is the only kind of check that survives a deadline.
4. A pre-merge review checklist. Guardrails cannot judge design, so the checklist covers what they cannot: is the diff the size the task deserved, were tests deleted or loosened, was error handling swallowed, does every number in the summary trace back to a command output.
The guardrails generator produces all four from a short form — commands, allowed paths, protected paths, and the rules you want enforced — and switches language with the page.
What guardrails do not do
It is worth being blunt about the limits, because overclaiming is how teams end up trusting the wrong thing:
- They do not review design. A change can be in scope, pass every test and still make the architecture worse.
- They do not make the agent honest, only constrained. An agent that cannot push can still write the wrong thing locally.
- They do not replace git discipline. Branch protection and small commits remain the real rollback mechanism.
- They do not stop a determined human. Someone will eventually edit the deny list to get unblocked — that is why the config is worth reviewing.
Treat them as blast-radius control: the point is that a mistake costs a revert, not a weekend.
Make it a habit
The most useful ritual is boring: after every incident where an agent did something surprising, add one line to the rules file and one rule to the deny list. Within a month the file describes how your team actually works, and new agents inherit it for free.
Two supporting habits help: ask for the working, not just the answer (“list the files you changed and why”), and verify before the meeting rather than after — a check that takes minutes beats a correction email that takes hours.
If your reports also contain numbers the agent produced, the AI number checker covers the other half of the same problem: figures that look right and have no source.