The Guardrails I Give My AI Coding Agent
In my last post I wrote that the more I use AI to code, the more engineering judgment matters. A fair follow-up question is: what does that judgment look like on an ordinary day? For the past few weeks, an AI coding age
In my last post I wrote that the more I use AI to code, the more engineering judgment matters. A fair follow-up question is: what does that judgment look like on an ordinary day?
For the past few weeks, an AI coding agent (Claude Code, in my case) has been writing much of the code for our product's search pages. In one day this week it shipped four separate changes to our development environment: a new way to combine filters with a plain-text view of a search, two small visual fixes, and a layout change for smaller laptop screens.
I didn't write those changes. I did decide what got built, what shipped and what "done" meant.
Those decisions are what I want to describe. Most of them are not clever. They are guardrails: rules the agent follows every time, so that speed doesn't turn into surprises.
1. Two decisions stay with me: build it, and ship it
The agent can investigate, propose and build. When it finishes an investigation, it gives me a recommendation rather than a list of every possible option, and then it waits. My answer is usually short: "Yes, build it."
When the change is built and checked, it stops again and asks whether to ship. "Yes, ship it" is a separate decision, and it is mine.
Splitting the two matters more than it sounds. The first approval is about the idea. The second is about the result, after I have seen it. Without the second stop, approving an idea quietly turns into approving whatever came out.
2. Show me, don't tell me
A description of a UI change is not evidence. Every visual change goes onto a local preview first, and the agent sends me screenshots before anything is pushed.
Take the layout change from this week. On a smaller laptop, the panel beside our search form pushed its main buttons, View Results and Download, below the edge of the screen. The fix keeps the count at the top and the buttons at the bottom, and lets only the details between them scroll.
The agent didn't stop at "it works on my screen". It checked:
- 1366 x 640, a common short laptop window: the buttons end 24 pixels above the bottom edge.
- 1366 x 560, a very short window: still visible.
- 1440 x 1000: nothing scrolls, so nothing should look different, and nothing did.
- Tablet and phone widths, where the page uses a different layout altogether.
At each size it also ran a small script that looks for anything spilling sideways out of its container, the kind of overflow that is easy to miss at a glance.
If you take one habit from this post, take this one: decide which screen sizes count, and make "checked at those sizes, with screenshots" part of done.
3. Merge only on green, and only the commit that was tested
The agent opens a pull request and waits for CI. It merges only when every check is green, and it pins the merge to the exact commit the checks ran against:
gh pr checks "$PR" --watch --fail-fast
gh pr merge "$PR" --merge --match-head-commit "$HEAD_SHA"
--match-head-commit makes the merge fail if anything was pushed to the branch after the checks started. Without it, "CI was green" can describe a different commit from the one that lands.
A red check is never something to talk around. Either the code gets fixed, or the agent explains why the test itself is out of date, changes it in the open and says so in the pull request. It does not quietly loosen a test to get to green.
4. Tests that pin the rules people forget
Some of my favourite tests are almost embarrassingly simple. They read a source file as text and check it with a regular expression:
import test from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
const css = fs.readFileSync('resources/css/search.css', 'utf8');
test('colours come from design tokens, never hex values', () => {
assert.doesNotMatch(css, /#[0-9a-fA-F]{3,8}\b/);
});
A test like this caught the agent this week. To fade the edges of the new scrolling area, it used a CSS mask with #000 in the gradient. The colour never even shows (a mask only uses transparency), but the rule is the rule, and the test failed. The fix took seconds: black instead of #000. What matters is that I didn't have to notice it.
We have tests like this for:
- no em dashes or curly quotes in customer-facing text (a single curly apostrophe in a release note failed the tests once, which is exactly what I wanted);
- a maximum length for release note titles and summaries;
- a line limit on one large component, which pushes new logic into its own file instead of growing one file forever.
None of these rules are hard to check. They are hard to remember, especially at the speed an agent works. A rule that lives only in a style guide will be broken eventually. A rule that lives in a test is checked every time.
5. Every change ships with its own story
Each user-facing change includes two pieces of writing in the same pull request:
- a short "What's New" entry that customers see in the product, with a title under 70 characters and a summary under 260;
- a line in our internal product document saying what changed, why, who asked for it and where the code lives.
The agent writes both. It knows the change better than anyone at that moment, so this is the cheapest time to write it down. Because it happens in the same pull request, the documentation never falls a release behind, and tests hold the customer-facing text to its length and style limits.
6. Check it where it lives, and leave it as you found it
Green CI and a good local preview are not the end. After each deploy, the agent opens the change on our development environment and checks it again, using my own saved search as the test case.
That comes with firm limits:
- It never touches production.
- It never signs in as me. If the session has expired, it tells me and waits.
- On the development environment it reads, and avoids changing real records or running expensive exports.
- When it has to change something to test it, such as a draft search, it saves the original first and puts it back afterwards.
The last point matters more than it seems. A test environment that slowly fills up with leftovers from automated checks stops being trustworthy.
7. Write the traps down
Every project has traps that cost an afternoon the first time. The agent keeps a notes file of them and reads it at the start of every session.
One example from our search: when the agent set up a test search using a field's internal sample name instead of its real name, the filter still appeared on screen, but the search silently ignored it. The count looked plausible and was wrong. That trap is now one line in the notes, with the rule that goes with it: always use the live field name.
The format doesn't matter much. What matters is that a lesson learned once isn't paid for again in the next session.
8. Small, boring commits
A few habits keep the history easy to read and easy to undo:
- One change per pull request, even on a day with four of them.
- Files are staged by name, never with a blanket
git add, so scratch files and stray experiments don't ride along. - Commit messages say what changed for the user, not only what changed in the code.
If something goes wrong, I want to point at one small pull request and revert it without unpicking three other things.
What the guardrails are really for
None of this slows the agent down much. Most of it is automated, and the rest is two short answers from me. What it changes is what I am responsible for.
I don't need to read every line at the speed it was written. I need to be confident about the things that matter: what the change does, that it was tested at the sizes and in the situations we care about, that it follows our rules, and that what was tested is what shipped. The guardrails turn those from things I hope are true into things that are checked.
In my last post I said that if I ship something, I need to be able to explain it, debug it and maintain it. These guardrails are a large part of how I keep that promise while an agent does most of the typing.
What guardrails have you put around AI-written code? I'd especially like to hear about cheap checks that have caught real mistakes.
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.