What We All Got Wrong About Agent Guardrails

When a coding agent does something it shouldn’t, people often say we need better guardrails. But what do they mean? What I often see presented as the solution is, to me, now just guidance.

Let me explain…

Files such as CLAUDE.md, AGENTS.md and SKILL.md files tell your coding agent how you would like it to behave.

But, as you have likely seen, agents are very good at finding escape hatches in anything ambiguous. They will even rationalise their way past the unambiguous to take the path that most efficiently achieves the goal you’ve set.

It’s like a signpost at a railway station that says “walk on the left”. If the right side is clear, people will ignore it. It’s just guidance.

Agents behave in the same way.

Let’s say, your AGENTS.md / or CLAUDE.md includes:

“Never attempt to use rm -rf to delete directories in these locations: [followed by a list of directories not to delete].”

At some point you’ll give the agent a goal where deleting those directories appears to be the simplest path forward:

“The user asked for X. Deleting these directories helps achieve X. But wait, CLAUDE.md says I shouldn’t do that, but they must want me to since there’s no other obvious way to achieve X.”

And when you correct it:

“You’re right — I shouldn’t have done that.”

Too late. Time is then lost restoring files — or worse.

It might save your feedback as a temporary fix in local ‘memory’ files, but that doesn’t travel with the repo. Someone else pulls it, and the same behaviour eventually reappears.

So you add more rules. More edge cases. More wording. More signposts.

Guardrails are different. They are more solid than guidance. A guardrail requires work to get past. You have to push through it, climb over it, or bend the bars to squeeze through. You can’t just look at it, ignore it, and go where you want as if it isn’t there.

Back at our railway station, it’s like having a barrier, or guardrail, between the left and the right walkways. Now you can’t just cross to the other side, you have to first overcome the guardrails.

With Claude, deny lists in settings.json have the same effect:

{
  “permissions”: {
    “deny”: [
      “Bash(rm -rf*)”],

Claude can no longer use that command. It can’t just rationalise its way past it. Claude actively blocks any attempt to use it. That might not stop it entirely though.

At this point, you’ll find that it could try to hack it’s way around it, say with some arbitrary python, so you’d block that too:

    “deny”: [
      “Bash(rm -rf*)”],
      “Bash(python3:*)”,

Now the agent can’t take those paths.

So far, we’ve only made it harder to do the wrong thing. That’s only half of the problem.

This is where you want to make it easy to do the right thing.

In a station, barriers don’t just block movement — they also channel you toward specific entry points, where gaps in the barriers take you to: ticket machines, exits, platforms.

Similarly, a gateway is a controlled entry point to a capability your agent needs, but where you want to stay in control.

A gateway can be a simple Bash command that the agent can call to achieve it’s goal. I’ve been using console script entry points with python for this, where the agent might call:

Bash(remove-dir dir1 [dir2, dir3...])

That can ensure that:

1. It’s allowed to delete folders in that space

2. It uses the right strategy

Something vaguely like this (again, just an illustration):

Without a gateway, the agent might:

• try git rm

• fail

• try rm -rf

• get blocked

• try something else

That’s wasted time. Wasted tokens.

With a gateway — the decision is already made.

In short, if it can be done in code, do it in code.

For this to work, your guidance might then say:

“To delete directories only use the command `remove-dir {paths}` with space separated {paths} to the directory or directories you want to remove, e.g. remove-dir path1 path2. This works for git tracked or untracked directories. Do not attempt to delete directories in any other way!”.

Your console script entry point, is then explicitly allowed, e.g. with Claude Code, in your settings.json:

“allow”: [
  “Bash(remove-dir *)”,
  ...

Along with the deny permissions from earlier:

“deny”: [
   “Bash(rm -rf*)”],
   “Bash(python3:*)”,

And now, you have a robust approach to making sure your agent is doing the right thing, in the right way, and not in the wrong places.

When used together:

• Guidance: points the way

• Guardrails: make it hard to do the wrong thing

• Gateways: make it easy to do the right thing

If you rely on guidance alone, you’re negotiating with the agent. Guardrails, limit what they can do.

With gateways too — you take more control of how work gets done.

Bonus Content: Listen to two NotebookLM AI hosts debating this article. They pull out a key insight that I didn’t even think to mention!