The Agent Disobeyed and Was Right

Ask a model why it did something and you get a plausible story, not a record. The only trustworthy account is a reconstruction: what was demonstrably in the context window at the moment of the decision, and which of those inputs could actually have produced it. Run that on a decision that went unusually well and you get something more useful than praise, which is a list of conditions specific enough to recreate deliberately.

The Accident

In a working session this August, a Claude Code agent did something I had not explicitly asked it to do. It hit the same need twice, back to back: converting a client deliverable into a themed PDF. Instead of writing a throwaway script for the second one, it opened an existing tool of mine (a renderer that turns Markdown into themed HTML and PDF, and JSON into editable slide decks), extended it to cover the new case, ran the tool's existing consumers to confirm nothing broke, and mentioned the change in one line.

That is the behavior I want most from agents: recognizing that a recurring need belongs in shared infrastructure, not in another one-off. No one had designed the inputs as one coordinated system to produce it. I noticed the result after it happened. The question that mattered wasn't "did the agent do well." It was: what caused this, and can it be made repeatable?

What Was Actually in the Context Window

I reconstructed the session from what was demonstrably in context, not from asking the model why it did what it did (introspection from an LLM is a story, not a log). Five inputs were present. They had accumulated through separate decisions, not as one designed system.

No single input explains it. Remove the imperative and there's no pattern to follow. Remove the package.json line and the pattern has nowhere to land. Remove the memories and the agent doesn't know the tool exists. Remove the second occurrence and extending anything would have been over-engineering.

Five Working Hypotheses

Generalizing from the reconstruction gives five candidate principles. I want to be precise about their status: they come from one session, they're being actively confirmed or killed in a separate design thread, and any of them may turn out to be an artifact of that one afternoon. They are hypotheses that happen to be load-bearing.

1. Imperatives may fire where facts inform. Input 1 is a command. Input 4 is a fact. In this session, the command was the apparent behavioral driver. Almost everything in my memory system is a fact.
2. Repetition may beat storage. Input 1 was re-injected by a hook nearly every turn. Input 4 was retrieved once. This session suggests that re-injection can keep a relevant rule available when an older stored fact fades from attention.
3. A rule may need an address. Input 1 gave the pattern, but input 2 gave the place. In this case, a behavioral rule without a concrete target would have resolved to nothing actionable.
4. Conflicting rules need explicit resolution. More on this next, because it's the twist.
5. Unchecked rules decay. More on this too, because I have the receipts, and they're mine.

The Behavior Fired Against the Rules

Here's the part that keeps this from being a success story. My global instructions, loaded into every session, contain a rule I wrote deliberately and still believe in: surgical changes. Touch only what the request requires. The request was a PDF, not a PDF tool.

By the letter of the always-loaded instructions, the agent misbehaved. The outcome I liked happened against the global rule, but in line with the more specific renderer rule. The two rules had never been given a precedence rule or clear scopes. The specific rule won. I liked the result, but its precedence was accidental rather than designed. That's hypothesis 4 with a specimen attached: until conflicts are resolved explicitly, the system is not reliably controlled regardless of what else gets built on top.

What Happens to Rules Nobody Checks

Hypothesis 5 came from auditing my own environment, and it was humbling. Years ago I wrote structural rules for my knowledge vault: good, specific, imperative, and with a named enforcement mechanism. Auditing them against reality:

Naming conventions ignored. Files the rules explicitly prohibit, sitting at the root. The template folder the rules point to: empty. And the enforcement mechanism named in the document had itself decayed, which is the detail that closes the loop. A rule that nothing checks doesn't just fail; the checker fails with it.

The freshest specimen arrived while I was writing this up. An agent confidently repeated a stored memory, "zero scope markers exist in this directory tree," while two such markers had been sitting on disk for five days. A stored fact had outlived reality and was trusted over the filesystem it described. Whether the reader is a human or an agent, an unverified claim converges on the same state: false, and still being cited.

Contract and Carrier

So now I'm designing the whole environment around this deliberately, and the frame that survived contact with the evidence splits every behavior into two parts.

The contract is the behavior stated precisely enough to be checkable. For the tool-extension case:

That contract needs one more rule to coexist with surgical changes: surgical changes are the default, and tool extension is an explicit exception when the candidate contract is met. An agent should not have to infer that precedence from two conflicting imperatives.

The carrier is everything that puts the contract in front of the agent at the right moment: the global rules file, per-directory rules, skills, hooks, the memory system, project scaffolding, and one instrument I'd been treating as housekeeping: structure itself. File layout, naming, and marker files decide what an agent finds, and what it finds decides what it does. Discoverability isn't tidiness. It's the delivery mechanism.

The audit makes one constraint non-negotiable: a solution that is only a document will decay exactly the way my vault rules did. Whatever gets built has to prefer mechanisms that check themselves: hooks that verify a rule fired, audits that run on a schedule, markers that something actually consumes.

The Loop That Isn't Built

The end state I'm designing toward, stated honestly as a direction and not a capability: an environment that notices its own successful accidents.

The original behavior was discovered by a human, after the fact, reading a transcript. The aspirational version is infrastructure that detects when a session has organically produced a reusable pattern (a need met twice, a tool quietly extended, a convention that held) and flags it for promotion into the permanent environment. The meta-loop: the same shaping machinery, pointed at its own output, asking to keep what worked.

None of that exists yet. What exists is one good accident, five hypotheses, a contract under test, and an audit that proves the naive version (write it down and hope) fails on contact with time.

The environment was already shaping behavior before I was paying attention. The next question is whether it can be made to do so deliberately, rather than by accident.