Skip to content
TODD BROWN
« Writing

Every pitfall I pre-wrote a rule for, my agent still needed reminding about

I built the creature-battler game — parked now, waiting on an automated 2D-art pipeline — starting in October 2024, about five months before LEGION first appeared in March 2025. The toy came first. It is entirely because I was messing around with making a toy that I developed the skills necessary to build the advanced machinery I later developed.

One of those skills was writing design documents precise enough for an agent to implement and cover with headless tests. The battle math — damage formula, agility bands, type chart, part stat budgets — was designed and balanced in a spreadsheet first. The technical design document said its values were "derived and verified against the original spreadsheet prototype," and that spreadsheet-first discipline was then specified precisely enough for Claude to implement and prove with tests.

About the same time I was starting this work in late 2024, the major labs and vendors were publishing the basics of agent orchestration: ReAct had established the reason → act → observe loop in October 2022, AutoGen and LangGraph had launched for multi-agent coordination in 2023 and early 2024, and SWE-agent had shown in May 2024 that the environment around the model mattered as much as the model itself. The industry was converging on the insight that the model alone wasn't the product — you needed orchestration, state, tools and control structures — before it had a common name for it.

I wrote rules for the agent across several design documents. I wrote them in plain English, I wrote them as technical constraints, and I attached them to the project. Then, on 20 March 2026, I ran a dedicated refinement audit to see what the agent had actually shipped.

The problems the audit found

The refinement audit on 20 March 2026 found and fixed four production bugs, the same day.

First: a "DEV ONLY"-marked function that unconditionally purged all active-tier creatures from the database on every app launch. The rule said development-only utilities should never run in production. The agent shipped it live anyway.

Second: a forced-switch bug that always gave the enemy a free turn, regardless of whether the player's switch was voluntary or forced by a knockout. The design doc specified the correct behavior; the implementation diverged.

Third: missing defensive-stat flags that silently disagreed with the design spec. The spreadsheet prototype had the correct values. The agent's code did not match.

Fourth: a SQL-injection-shaped string-interpolation weakness — user input assembled directly into a query string instead of using parameterized queries. The security rule was written. The code ignored it.

On the same day — 20 March 2026 — an autonomous Planning → Execution → Refinement → Execution chained sprint sequence took the engine's test count from 651 to 1,725. The agent could write tests. It could pass them. It still shipped bugs the rules explicitly prohibited.

The problems the agent found and fixed in one session

The audit didn't just surface problems I pointed out. The agent, given the directive to refine and improve the codebase, found six real issues on its own and fixed them in the same session.

It found a stat-calculation bug where creature stats were being computed incorrectly under certain part-slot combinations. It found a UI state bug where the battle screen didn't update properly after certain sequences of actions. It found an edge case in the type-effectiveness lookup that returned the wrong multiplier for dual-type interactions. It found a memory leak in the procedural-generation pipeline that accumulated object references across multiple creature spawns. It found inconsistent rounding behavior between the spreadsheet prototype and the production damage formula. And it found a race condition in the turn-resolution sequence that could occasionally let both creatures act in the wrong order.

None of those were in the risk register. None were called out in the design docs. The agent found them, described them, and fixed them — all in the same refinement pass that also corrected the four bugs I'd explicitly written rules against.

What it means

A rule an agent has to remember is a suggestion, even when it's written down, even when the agent agrees with it. A rule the tooling checks before the action is a boundary.

When an agent keeps breaking a rule you already wrote down, the fix isn't a firmer sentence in the prompt. It's a check that runs first and can't be argued with.

I learned this again later in 2026, working on LEGION. An agent broke a heredoc-handling rule three times in one afternoon, so I had it write a pre-execution hook that refuses the command if the rule is violated. LEGION's standing version now: observe freely, change production only with a flag the script itself demands, never touch the destructive things.

Back in April 2025, early in LEGION's own build, I'd already found that agents ignored an onboarding handbook even when the file was attached. The fix then was both layers: the file attached by tooling, and a prompt rule telling the agent to read it. I wrote at the time: "it looks like the problem is not that the file is not being included, it is that the AI defaults to not reading it unless it is prompted to do so."

Around March 2026, discussing an email-handling agent, I sketched the next step: you run a huge batch of emails into markdown files in a codebase, then you have a reasoning model inspect all of the emails and look for incorrect responses or edge cases, and then you have that reasoning model update the rules. You test the responses in a dev environment and only give it email permissions when it passes a certain threshold of quality. But the whole time the rules of engagement are being modified and improved.

The through-line from 2025 to now: a prompt rule on top of tooling, because tooling alone was ignored. Rules kept in plain files, audited by a reasoning model, and permissions granted only past a quality threshold. Rules that matter get enforced in tooling before the action.

The creature-battler is parked on one named, specific condition — an automated 2D-art pipeline good enough to produce the game's art. The tech and game engine are fully functional and tested. Last recorded figure: 1,725 Godot tests, 0 failures, and 608 Python tests for a procedural NPC-art side track. 7,483 lines of GDScript production source, 3,970 lines of GDScript test code. Sixteen numbered risks tracked in a risk register.

The game taught me to write rules an agent could follow. The audit taught me that writing the rule wasn't enough.