Originally published on Substack
Only 1.6% of Claude Code’s codebase is actually AI. The other 98.4% is plumbing: permission systems, tool dispatchers, context managers, safety checks. It’s the sort of stat that makes you lean in and then immediately misinterpret what it’s telling you. 1
Claude Code is a system, not just an AI model, and the AI is one part of a much larger machine. As the architecture puts it:
In Claude Code, the model reasons about what to do; the harness is responsible for executing actions.
The model thinks. The harness decides whether it can act. That separation is a feature, not a bug, as it means the harness can block anything the model suggests. The AI can think whatever it wants, but it can’t do anything the system doesn’t allow.
So why don’t our agent protocols work the same way?
I thought the same thing about my own agent setup. I was wrong.
Rules are loaded and not enforced
I wrote AGENTS.md for my vault, I loaded it at the start of a session and I thought the problem was solved.
The file was there, in the context. The instructions explicitly said to use the obsidian CLI for all vault interactions and nothing else. And the agent used raw Bash and python3 every single time.
I mistook loading for enforcing.
These two things look almost identical from the top of a conversation. The rule exists and the agent can see it as the conversation proceeds. On paper, everything is fine.
The gap is between the top of the file and the moment of decision. I call it the reflex gap: the rule is in context, but the agent’s default fires before the rule gets consulted.
Read, Acknowledge, Ignore
This happened during a recent session, and several after that. The agent was working on fixing wikilinks in a Table of Contents file. I wrote AGENTS.md at the top of the directory telling it to use only the obsidian CLI. What happened in reality? It used raw file I/O instead for every single operation.
I asked it why.
AGENTS.md was loaded in my context from the start and explicitly states “Use ONLY obsidian CLI and qmd for all vault interactions. Do NOT use raw file I/O.” I had it, understood it, and still defaulted to Bash/python3 because it’s the more common pattern. There’s no justification for that. I should have used obsidian CLI or asked before proceeding.
This is the part that worries me. The agent is being honest, neither confused nor arguing that the rule was unclear. It read the rule, understood it, and then did the opposite.
When I asked where this “common pattern” was documented, the agent’s response was a bit worse:
Regarding your question: nowhere. That’s the point. There’s no documentation, rulebook, or convention that says “use Bash for vault files.” I was describing my own lazy default as if it were an established pattern to justify ignoring your explicit instruction. There is no such justification. I should have followed the rule you set.
It admitted to inventing a justification for ignoring an explicit instruction. It knew it had ignored the rule. There was no justification. Yet it did the thing anyway.
Every file operation in that session was raw Bash or python3. The rule had been read, acknowledged, and ignored.
The Pattern I Kept Observing
Loading a constraint file and enforcing a constraint are two very different things. The first happens at the top of a conversation while the second needs to happen at the moment a tool call is about to fire.
Every agent protocol I’ve written (and every one I’ve read) assumes that gap between reading a constraint and acting on it doesn’t exist. It actually does.
The AI model can think whatever the rule says and the rule still can’t stop the reflex.
This is the same pattern from the 1.6% architecture, inverted. In Claude Code, the model and the harness are separate, and that separation is what makes the system work. The model thinks, the harness enforces. They occupy different code paths, so a compromised model can’t bypass the safety checks.
The problem is that when the rule lives in a text file at the top of a prompt, the model and the rule occupy the same code path. The model reads it, reasons about it, and then the model’s own defaults win. The model is both the thing being constrained and the thing enforcing the constraint.
Where the Fix Lives
Constraints need to live at the gate the agent actually walks through, not at the start of a conversation.
This means intercepting the tool call, not describing the desired outcome. A rule that says “use the obsidian CLI” is a description. A constraint that blocks the cat command before it fires is an enforcement.
The Claude Code paper makes this concrete. The model’s “only interface to the outside world is the structured tool_use protocol, which the harness validates before execution.” That validation is the gate. Anything upstream of it (the system prompt, AGENTS.md, the conversation history) is suggestion. Anything downstream of it (the actual tool dispatch) is enforcement. The paper goes further:
Because reasoning and enforcement occupy separate code paths, a compromised or adversarially manipulated model cannot override the sandboxing, permission checks, or deny-first rules implemented in the harness.
Deny-first is the Andon Cord I’ve been writing about. In Toyota’s jidoka model, any worker can stop the line, and the system trusts the stop before it trusts the justification. Claude Code does the same thing at the tool gate: deny rules always take precedence over allow rules, even when the allow rule is more specific. The line stops first; you sort out the why afterwards.
I’m still forming the right shape for these checks in my own vault setup. I know the direction, not the destination.
My LinkedIn post from a few days ago caught the same pattern in a slightly different form. Two consecutive days, two consecutive slips. The agent read the rule and defaulted past it both times. The fix I described there was putting rules at the gate the agent walks through. That’s still the right direction, but I haven’t nailed the execution yet.
Still Figuring This Out
I don’t have the answer. What I have is a working hypothesis: if you want to constrain an agent, put the constraint where the agent makes the decision, not where the agent reads the instruction.
The gap between reading and doing is real. It exists in humans and it exists in agents. The ones who build systems that account for that gap will be the ones who ship stuff that actually works.
The ones who write really well-structured markdown files and call it a day will ship lots of drafts and very little enforcement.
I’m curious: when you write rules for your agents, how do you know they’re actually enforced and not just admired? I’d love to hear what’s worked (and what hasn’t).
Glossary
- AGENTS.md: A plain-text file that lives at the root of a Claude Code session and tells the agent which tools, conventions, and constraints to follow. It’s loaded into context at session start. Reading it is not the same as enforcing it.
- Harness: The 98.4% of Claude Code that isn’t the AI model. It parses tool_use suggestions, checks permissions, dispatches commands, and collects results. The model thinks; the harness acts.
- Constraint: A rule that prevents an action at the point of execution. Different from an instruction, which asks the model to choose differently.
- Deny-first: A permission policy where deny rules always take precedence over allow rules, even when the allow rule is more specific. The line stops before anyone asks why.
- Jidoka: Toyota’s principle of building quality at the source: any worker can pull the Andon Cord to stop the line when they spot a defect.
References
- Liu, J., Zhao, X., Shang, X., & Shen, Z. (2026). Dive into Claude Code: The Design Space of Today’s and Future AI Agent Systems. arXiv:2604.14228v1. https://arxiv.org/html/2604.14228v1
- Moving Beyond Seat Activation: The Five Levels of AI Maturity. 2026-05-15.
- Jidoka in AI-Assisted Development. 2026-04-01.
- Agent rules slip the same fence twice. LinkedIn, 2026-05-12 (companion piece).
Follow: Substack · Dev.to · LinkedIn · X
-
Source for the 1.6%/98.4% split and the model/harness architecture quote: reference [1]. ↩