‹  Research

Case study · Skills · Hooks · Subagents

Agent tooling

Rules written down for an AI agent don’t change how often it repeats a mistake. Mechanisms do. This is the set of hooks, checks and reviewers that enforce how I work across every project — and the count that showed why.

Status

Personal, in daily use

Period

March – September 2026

Stack

Bash · Python · Node · Claude Code · Codex CLI

Source

Private

A rule broken a second time becomes a mechanism — a script, a hook, a grep in a gate — not a third paragraph.

Each mechanism sits at the moment the mistake happens, not in a document the agent is supposed to remember.

1Problem

Working with coding agents every day, the same mistakes kept coming back after they had been written into the instructions. A process kill by pattern that also killed the command running it. A commit and a push chained together, so a rejected commit still pushed. Two parallel tasks editing the same three files, so the release could not merge. “Done” said while the layout checks were still red.

Each one had a rule against it. The rules were read, agreed with, and broken again.

2Question

Do written rules reduce how often the agent needs correcting?

Measured on my own history with the agents: every message, every correction, before and after each rule was introduced.

3Findings

Rates per 100 agent replies, before → after the rule.

20–35 per 100Corrections per hundred replies stayed in this band across 1,421 of my messages and 339 correction episodes. No overall trend.
4.4 → 2.0“Decide before writing code” — a rule that changed one concrete step — halved its class of correction.
1.5 → 0.3“Production only through staging” — also one concrete step — nearly removed its class.
0.9 → 1.2“Check a name where it is defined” — a rule asking for more care — made no difference. Nor did the one about branches: 1.6 → 2.3.

The rules that worked replaced a step. The rules that asked for attention did not change anything. That is what moved the effort from writing instructions to building the mechanisms below.

4Mechanisms

  1. Principles, loaded by context

    One global file of working principles, plus frontend and backend rules that load only when a matching file is open.

  2. A guard before every command

    Blocks the specific commands that caused incidents: pattern kills, commit-and-push chains, pushes to the main branch without an explicit override, deploys from a non-main ref.

  3. A guard before every edit

    Before a file is changed, it is checked against other branches and worktrees from the last three days. An overlap blocks the edit until it is acknowledged with a reason, which is logged.

  4. A gate before “done”

    A turn cannot end while the interface checks are red — only in projects that opted in, after the first version blocked turns that never touched the frontend.

  5. Scenario and regression checks

    The browser checks from frontend-quality: states, tap targets, pixel regression against committed baselines, motion, performance.

  6. Independent reviewers

    A read-only interface verifier and a code reviewer run in a fresh context, after the work, and do not fix what they find.

  7. One set of rules for two agents

    A script compiles the same instructions into Codex CLI’s AGENTS.md, so both agents work under the same principles.

5What it cost

The first version of the end-of-turn gate was wrong in the way this whole project warns about: 8 of its first 11 blocks came on turns that had not touched the frontend, at about five seconds each. It was narrowed to turns that changed interface files. A check that cries wolf is worse than none — people stop reading it.

A green check means “not broken”, not “good”.working principles

6Limitations

  • The parallel-branch guard is wired into one project’s repository, not yet into every one.
  • The Codex sync is one-way and covers instructions only, not hooks.
  • The study is small: short windows for the later rules and part of the early history missing.
  • If a guard itself fails, it lets the action through rather than blocking work.