rafaelcmm

Spec-first with AI agents: what I delegate and what I keep

AI agents plan, build, test and review my code. Approvals and anything sent in my name stay with me. These are the rules, and the evidence I ask for.

Hand-drawn website wireframe in a grid notebook beside an orange pen on a white desk
  • ai-agents
  • spec-first
  • code-review
  • claude-code
  • workflow

I let AI agents plan, write, test and review code. What I don't hand over: approvals, anything that goes out under my name, and the right to see every judgment call an agent makes for me. That line is written down as rules. My ai-dotfiles setup installs them for Claude Code, Copilot and Cursor, and the agents load them before they edit anything.

Nothing gets built before there's a plan

The first rule is plan first, then build, and the rules spell out what building means: writing product code, scaffolding, installing dependencies, creating a project, invoking an implementation skill. Reading and exploring don't count, so an agent can look around as much as it wants before it has a plan.

By spec I mean that written plan: what gets built, the constraints it has to respect, and how each piece will be checked. For a small change it fits in a chat message. For this site it is a file in the repository, and I approved it before any code was written. The site it produced has its own post.

A chat message and a file are very different amounts of paperwork, though. The next rule decides which one a request gets.

Three paths, the same checks

Before planning, the agent states which of three paths the request takes:

  • Spike: a feasibility question whose output is thrown away. Two or three sentences on the question and the probe, a nod, then run it.
  • Bounded: a well-scoped change to a flow that is already understood. A short design in chat, my approval, then the change. No spec file.
  • Architectural: new components, a new subsystem, or a changed public interface. A written design, a written plan, acceptance criteria for each TODO, and specialists on each part.

The path changes how much gets written down, not what gets checked. Approval before anything goes out, the testing TODOs, evidence of completion, the documentation step and the two final reviews, security and documentation, run the same on all three.

Two more rules keep the classification honest. If two paths fit, the agent takes the heavier one. And the classification only moves up: if a bounded task turns out to be architectural halfway through, the agent says so and switches. It never moves down.

Every TODO says how it will be checked

Every code change becomes a TODO list with three classes: implementation, testing and final checkup. Testing is never optional. Each TODO has an owner, a scope, acceptance criteria and a verification step.

An agent that picks up a task works from that task's brief. So plans carry three parts written for the brief, and the plan for this site has all three:

  • A ## Global Constraints block, under that exact heading, holds the project-wide requirements (version floors, naming rules, platform limits) so they can be pasted into every task brief. In this site's plan, that is where "no analytics, no cookies" and "no runtime calls to any third party" live.
  • Each TODO says what it takes from earlier TODOs and what it hands to later ones, so the names one task produces match the names the next one uses. On this site it is a column in the TODO table, with entries like the ProfileCard component.
  • A Review Focus section lists inputs the spec implies but no test covers yet. One of them: a post that exists only in Portuguese must stay out of the English blog and leave no broken alternate link.

"Done" is a claim until I see the evidence

This is the part I review most closely. A TODO is complete only with evidence produced in that session:

ClaimEvidenceNot evidence
Tests passThe test command's own output, zero failuresAn earlier run, "should pass"
Build succeedsThe build command, exit 0A clean linter, logs that look fine
Bug fixedThe original symptom, retestedCode changed, failure assumed gone
Delegated work landedA diff in version controlThe agent saying it succeeded

The last row matters most when agents delegate to other agents. A subagent's "done" is a claim. I read the diff.

The agent also runs the project's whole test suite, not only the files it touched, and names every failure it sees, including ones its change didn't cause.

Reviews happen once, at the end

Security review and documentation review run once, after implementation and testing are finished, not after every TODO. Reviewers are advisory: a finding that misreads the code gets reasoned pushback instead of a fix, and the pushback is written down.

Fixes go to a single agent that gets the whole list of findings, never one agent per finding. A round is one fix plus one re-review limited to the open findings. After five rounds, or once the same issue has been disputed three times, or when two reviewer outputs come back malformed, the agent stops and hands the decision to me.

Two rules about code that already exists

Before deleting or simplifying code, the agent applies Chesterton's fence: find out why it was written. It needs at least one concrete source for the original intent (git history, an issue, how callers use it), a statement of what behavior stays the same, and a test or equivalent check on that path. If it can't explain the code, it doesn't remove it.

Files stay small too. A logic file of up to 300 lines passes; between 301 and 500 lines the agent splits it in the same task; above 500 it adds nothing unrelated until a split plan exists.

What never leaves my hands

Anything carrying my name

A push, a pull request comment, a review, a message, a release: the agent drafts it locally, hands it over and says plainly that nothing was sent. Writing the draft is free. Sending it waits for me. An authorization has to name the action, covers only that one instance, and lapses if the draft changes afterwards. It doesn't pass from one agent to another either: a subagent can't send something because its caller thought it was allowed.

A general "go ahead" doesn't stretch that far. The agent never pushes to a default branch, replies to a human reviewer or publishes to a registry on its own, and it never approves or merges work it produced.

Every judgment call comes back to me

When an agent decides something on my behalf, it records a Ruling: line with what it decided, why, and what it costs if wrong. Those lines come back in the final report.

Where the rules live

If you want to try these rules on your own agents, they ship with ai-dotfiles, and every one of them sits in the repository's static/ folder.