Skip to content

How I run AI coding agents

I stay in the loop for consequences: I set intent, approve anything risky and read the results.

Status: in daily use · checked Oct 29, 2026

In plain terms

One operator sets intent; coordinator and worker agents execute in isolation; every pull request in the main repositories must pass an independent AI review gate.

flowchart LR B[A brief with a
definition of done] --> W[A worker in its
own worktree] --> H[A handoff with
the evidence] --> R(The independent
reviewer decides):::guard --> M[A named
merger merges it]
flowchart TD B[A brief with a
definition of done] --> W[A worker in its own
worktree] --> H[A handoff with the
evidence] --> R(The independent reviewer
decides):::guard --> M[A named merger merges it]

The habits, in one list

  1. A brief with a definition of done. Every worker gets a goal, the paths it owns, a command whose output proves it is finished, and what not to touch.
  2. Owned paths. Parallel workers receive disjoint owned paths. After each phase, the runner checks the tracked-file diff and fails changes outside the assigned scope.
  3. The independent reviewer decides. In the main repositories, the author never approves its own change.
  4. Name the merger. Every route to a review says who merges it, or a passed change sits.
  5. Decisions are written down. The options that lost are in the record, and the record is amended, not rewritten.
  6. Everything states its age. Pages, figures and claims carry a date and what they were checked against.
  7. Partial means partial. "Built", "staged" and "enforced" are different words, and "I could not check" has a home.

The working model

One human operator sets intent, approves anything risky, and reads summaries. A coordinator agent turns intent into bounded briefs and routes them; workers execute in isolation; in the main repositories a separate reviewer agent reviews what would be merged (how that is trusted). Between them sit the guards in Guard rails and the ledger in Lanes and the run ledger.

The human is deliberately out of the loop for execution and in the loop for consequences: reads are free, writes happen in worktrees, and the owner approves scope and policy. Pushes are two-step, and in the main repositories an independent reviewer is required.

What a good brief contains

Work that goes wrong usually went wrong in the brief. A courier brief states the goal, the paths it owns, the definition of done (a command whose output proves it), what it must not touch, and what to report back. "Dry run first, then apply" is a brief that authorizes the dry run only. Briefs are self-contained because the worker can't see the coordinator's conversation.

Failure modes, and what answered each

What happened The answer
a worker reported success and nothing landed the ledger distinguishes false-done and hollow-done from done; completion needs a result, not an exit code
a worker edited a rendered file and the next render silently reverted it a hook intercepts edits to generated files; the template is the edit surface
an agent hard-reset a shared checkout and wiped a run of reviewed work history-destroying operations are intercepted; work happens in worktrees, and the shared checkout is read-only for agents
a stash hid live code behind a clean status stashes aren't a parking place; parked work lives in a named, dated, never-reaped folder
a guard reported OK while inspecting nothing guards ship with non-vacuity proofs; see Incidents and the fixes they produced
an agent spawned an expensive subagent to search files a hook redirects read-only fan-out to the cheap lane
documentation drifted until it was wrong in dangerous places pages carry state and evidence; stale ones fail CI; see Documentation that stays true

A cost lesson, learned by measuring

The principle for this documentation refresh: use the expensive model to decide and the cheap model to look. Read-only agents produced structured patches and a deterministic script applied them. Coding workers continue to implement bounded software changes in isolated worktrees.

Read the case

A large documentation refresh was first run the "obvious" way: fan the pages out to many frontier-model agents, each with a reviewer. Halfway through, I measured the per-agent usage instead of guessing. It was dominated by the same long context being re-read on every turn of a long tool-using session. Extrapolated over the whole fan-out, the run would have cost far more than the task warranted.

The fix was architectural, not a smaller prompt:

  1. Stop the run and keep what was good. Finished pages that met the bar stayed.
  2. Make the cheap tier produce data, not side effects. Read-only investigators on the cheapest capable model tier verified each page against live state and returned structured patches: exact-match replacements that must match exactly once, plus a status header.
  3. Apply deterministically. A script applies the patches, rejects any that don't match, and runs the same validators CI will run. Failures are re-dispatched with the validator's message.
  4. Keep the frontier model for judgment. It wrote the parts that need care (the public pages, the pipeline), reviewed samples, and decided when the validators were satisfied.

A second case study: the documentation pipeline

An audit of the documentation site found that its build had been failing every cycle for days while the site kept serving old content. The health check only tested that a page existed.

Read the case

The rebuild followed the same habits as everything else here:

  • One repository, two editions instead of one site with masking on top: an internal edition for the operator, and a public edition assembled only from opt-in pages and scanned before it is allowed to replace the last good build.
  • Atomic swap. A failed build never replaces the site that is serving.
  • Freshness as a contract. Every page states its state, last-verified date and evidence; stale pages fail CI, and the site shows the same information in a banner.
  • Generated runbooks for alerts whose link pointed nowhere, built from the live rule definitions and never overwriting a hand-written page.
  • Tests for the tooling itself, including a leak test that has to fire on a planted violation before it is trusted.

The team edition: roles, owned paths and gates

If this were a team of people and agents, the structure would be the one it already has. Roles are addressed by name, not by connection detail, so a message reaches whoever holds the role.

Role Does Doesn't
Operator (a person) sets intent and policy, approves anything irreversible, holds the keys run the changes by hand
Fleet coordinator (the coordinator agent) triages, decides the lane, dispatches, verifies results, names who merges decide a merge alone
Builder (a worker agent) owns a defined area for a defined task, in its own worktree touch another builder's paths
Fixer picks up failures and the follow-ups from review widen scope without saying so
Checker (the independent reviewer) reads or runs the change and records a decision on the exact version write the change it checks
Merger one named role per pull request merge anything not named to it

The coordination rules below came from things that went wrong.

  • Owned paths. Each lane declares the files it may change. This is how several builders work in one repository without a collision, and the check afterwards is mechanical (orchestration).
  • Review gates. In the main repositories, a change passes the automated checks and then a checker's recorded decision on the exact version. A push after a pass voids it, so a builder tells the coordinator before any further push to a reviewed change.
  • Name the merger. Recently, a batch of changes that had all passed review sat for hours because every message said "review only" and none named who would merge. Every brief and every route now names the merger, and a pass without one is treated as unfinished.

Decisions are written as records with the rejected options (selected design decisions). Every page and figure states its age and its source (documentation that stays true). Between them, a new person, or a new agent, can find out why something is the way it is without asking.

One operator surface

Everything I do to run the fleet goes through one command-line tool: dispatching and resuming workers, read-only scouts, handoffs, session messaging, the rollback timer, pushing, diagnostics. It has about 260 commands (as of Oct 26, 2026). One tool means one place for guards and audit, one thing to teach a new agent, and one place where a missing capability shows up as a missing command and not as a hand-run shell sequence. The cost is that the tool is itself a product that needs tests and a changelog, and it does.

A delivery story, from brief to merge

This site was delivered the way I would deliver to anyone, which makes it a checkable example. The sequence, by date:

Date What happened
October 22 An independent review of the earlier site produced a long list of findings, in order of importance.
October 23 From the review I had a written brief drawn up. It set what to build first, gave the exact wording for the Home opening and for the definition of Autonomation, and listed what must never appear publicly, such as private infrastructure details and client information. The new pages were then written from scratch, working from my résumé and my internal documentation, keeping how things work and leaving out private names and exact settings. Every build was scanned for banned names, and for private addresses and credentials, and failed if it found any.
In between Independent checkers read and ran the changes. One pass was static, one executed the checks and planted violations to prove they fail, and each owner decision in the content was traced back to the words I had actually typed. Figures were moved into one values file, with a test that fails the build on any number typed into a page.
October 26 An audit compared the build with the review line by line. Every item became done, scheduled, deliberately skipped with a reason, or waiting on me. The scheduled work was built as a second change on top of the first, so the version the checkers had reviewed did not move.
Merge A checker's decision on the exact version, a named merger, and a plain merge. No bypass.
Release I sign it off myself.

One thing went wrong on the way, and it is in the record: a builder pushed to a branch after the checkers had passed it, which voided their passes and cost a re-run. Builders now tell the coordinator before any further push to a change that has been reviewed.

What is still hard

  • Agents are good at looking and at bounded change; they are worse at knowing what they don't know. The status vocabulary includes unverified so that "I could not check" has a home that isn't "works".
  • The guards multiply. Each is justified by an incident, but the set needs pruning as much as growing.
  • Cost routing depends on measurement discipline that has to be repeated, not configured once.