The Rules File That Outlived a 34,161 Commit History

The IIS-URLAuthorization script came first, and it never got a comment explaining why. iisreset, disable a module, move on, ship the ticket. That was 2026-05-22. It was one of two setup commits for the AI teammate. The other was a rules file for how the agent should behave, landing in the shared AI-rules directory. The same repo’s early history, twelve years back, shows us doing the same kind of thing with no name for it. We used trial and error against a deploy hook until it stuck, with no doc and no rule, just a commit message and the next day’s fix if it broke.

The repo is 34,161 commits deep. What sits next to the code now is different.

The rule that predates the bug

Two days after the teammate setup commits, a ticket adds a rules file to the shared AI-rules directory. It describes how work phases should proceed, and it is wired into the project’s agent instructions and the /item skill. It’s a doc checked into source control, and an agent reads it before it touches a ticket. A day later, another ticket does something similar for hotfixes: cherry-pick or recreate-resolution, never back-merge master. It also adds a URL pattern to a rules file that governs URL conventions. Neither exists because a human forgot the rule once. They exist because the agent needs the rule stated somewhere it can read fresh every session. It has no memory of the conversation where we worked the rule out the first time.

That’s the mechanical difference from the human commit history. A human who breaks the “don’t back-merge master” convention learns it by breaking it once and remembers. An agent that breaks it will break it again next session unless the rule is a file. So we started writing rules down as input to a process that runs without continuous human attention.

Where we tried the wrong fix first

The ticket for /sync, a script step, tested this. We wanted it to fail loudly if a merge conflict came up during onboarding, instead of silently skipping a step. We wrote it, committed it, and moved on to the next task.

It got reverted the same day. The revert commit’s message just notes that it undoes /sync’s silent-fail behavior on merge conflict. The loud failure we’d written made no distinction between a conflict that needed a human and one the sync step could resolve itself by retrying against develop. It stopped everything and threw an error string at whoever was running onboarding, agent or not, on cases that should have self-healed. We’d built the safety behavior without checking what fraction of conflicts it would catch and what fraction it would just block. The cost was a full onboarding run failing on something that didn’t need to fail, and a revert commit in the log as the record of it.

The fix that stuck was smaller. A rules file landed in the shared AI-rules directory the same day as the IIS script, and it’s a rules file, not a script. A script encodes one behavior and fails when the world doesn’t match its assumptions. A rules file states intent and lets whatever reads it, agent or person, apply judgment. That was what /sync needed.

The review commit that isn’t a merge

A bug ticket dated 2026-05-20 covers a notification-preferences bug in the opt-in flow. Its commit message says “teammate review feedback on opt-in flow.” The review was a pass run as part of the ticket and folded into the same commit that fixes the bug. The review step is now a stage in the pipeline, so it no longer takes a separate person’s slot on a separate calendar.

None of this shows up as new architecture. The database schema and the branch model (hotfix into master into develop) keep the same shape. You can see it in the same stretch of history. A hotfix ticket gets a fix into one patch release, then the next, then gets reverted once when the merge order was wrong, then redone. What changed is that alongside the ticket commits there’s now a parallel stream of commits whose only purpose is making the next agent session start with the same context the last one ended with. Years of commits taught us what the deploy hook needed. The agent gets only what’s checked into the shared AI-rules directory at the start of the session.

Where the rules live

An AI agent has no memory between sessions, so the conventions it must follow need to be written where it reads them fresh each time. If you bring agents into your engineering work, ask where your team’s rules live today, and whether they sit in a file or only in people’s heads.

dxdev LESSON · paste into your AI coding agent
LESSON: Before A Script Fails Loud, Check How Many Cases Are Actually Self-Healing
SOURCE: dxdev.com/blog/twelve-years-then-an-agent-showed-up
WHAT HAPPENED: The author wrote /sync to stop and throw an error whenever onboarding hit a merge conflict, replacing a silent-skip behavior, and committed it without checking what fraction of conflicts actually needed a human versus could resolve themselves by retrying against develop. It was reverted the same day, with the revert commit message noting it undid the silent-fail-to-loud-fail change. The cost was a full onboarding run failing on conflicts that didn't need to fail. The fix that stuck was different in kind, not just detail: instead of a script encoding one fixed behavior, the team landed a rules file in the shared AI-rules directory the same day as an unrelated IIS-URLAuthorization script, stating intent so that whatever reads it, agent or person, can apply judgment rather than hitting a hardcoded assertion.
THE RULE: Before hardcoding a failure condition into a script, check what fraction of the cases it will trigger on are actually unrecoverable versus self-healing; if the right response depends on judgment rather than one fixed behavior, that logic belongs in a rules document the agent or person can read and apply, not in a script that can only pass or fail.
CHECK MY CODE, then report PASS or FAIL with file:line for each:
      1. Does this script's failure path treat every trigger case identically, even though some of them would resolve themselves if retried or left alone?
      2. Before shipping a change that makes something fail loudly, did you check what fraction of past occurrences would have been false positives under the new behavior?
      3. Is this a case where behavior varies by judgment call (belongs in a rules file an agent re-reads each session) or a case with one correct deterministic response (belongs in a script)?
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.