Skip to content
Alex Hollyman

Working with AI agents

I work primarily with AI code agents.

The process, start to finish

This is a working model of how a change gets from a spec to my sign-off. Run it, step through it one stage at a time, or make a task fail review and see what happens to it.

The finished run: each task tested, reviewed and through the gates, then signed off by me.

Ledger

Task Tests Verdict
Add export endpoint 4 passed Approved
Form validation 4 passed Approved
Types for the new field 2 passed Approved
Diagram of the process. A spec I have agreed becomes a plan, and the plan becomes tasks. An implementer agent works each task test-first on the files it owns, and a separate reviewer agent reads its diff. Approved tasks wait at the gates: type-check, build, tests and screenshots. The whole branch then gets a final review, and I sign it off. The task names, file names and test counts are made up for the model. The token meters illustrate the idea that each agent has a budget and its context is finite; they are not measurements.

The rules agents work under

Each project has a guidelines file that the agents read before anything else. It sets the rules for the work: every change is covered by an automated test, the formatter is run on changed files, and nothing is added to the dependencies or moved in the directory structure without my approval. Larger projects add a rule file for each area, such as testing, components or queues.

Tools for looking things up

The agents also get a tool server. With it they can search the framework documentation for the versions that are installed, read the database schema and run read-only queries, so they look things up where they would otherwise have to guess. 

# Project guidelines

Read this file before you start a task.

## Tests
- Every change must be covered by an automated test.
- Run the smallest set of affected tests.
- Never delete a test without approval.

## Before you finish
- Run the formatter on the files you changed.

## Ask first
- No new dependencies without approval.
- No changes to the directory structure without approval.

## Rules by area
- rules/testing.md
- rules/components.md
- rules/queues.md
An example written for this page, in the form of the guidelines files I use.

Spec, plan, task brief

Work starts from a dated spec that I agree before any code is written. It covers the goal, the decisions already made, the backend, types and frontend work, the tests, and what is out of scope. The spec becomes a plan and the plan becomes tasks. Each task gets a brief that names the files it may touch and the interfaces it must meet.

Spec

Plan

Task brief

yyyy-mm-dd-export-new-field.md

  • Goal
  • Decisions
  • Backend becomes the task: Add export endpoint
    May touch
    api.phpExport.php
    Must meet
    The response type in api.d.ts
  • Types becomes the task: Types for the new field
    May touch
    field.tsapi.d.ts
    Must meet
    The field as the spec defines it
  • Frontend becomes the task: Form validation
    May touch
    Form.vuerules.ts
    Must meet
    The Field type from field.ts
  • Tests In every task, written first
  • Out of scope Not in any task
An example, not a real spec. The file name shows the pattern: the date it was agreed, then what it is for.

Implementing and reviewing are separate jobs

An implementer agent works a task test-first: it writes the test, sees it fail, then writes the code until it passes. It finishes with a report containing the evidence, the test failing and then passing, and its own review of the change. A separate reviewer agent, which did not write the code, then reads the diff for that task. A ledger records the commits, test counts and verdict for each one.

Gates and the final review

Before a branch is finished, the type-check and the build must pass. For interface work, screenshots must be taken and looked at. Some projects have a single command that runs all the verification scripts. The whole branch then gets a last review by the most capable model, and after that by me. Managing token use across several models is part of the job.

Parallel work and file ownership

Where tasks do not overlap, several agents run at once. Each one is told which files it owns, with one rule: only edit files you own, and report any change you need elsewhere. Separate working copies keep the agents from colliding.

Agent B needs a change in a file that belongs to agent C. It is not allowed to make the edit, so the request goes to the lead as a note.

What stays with me

I decide the architecture, I approve the spec before work starts, and I sign off the result. My grounding in a range of programming languages means I can use agents confidently on unfamiliar frameworks and languages, and still understand and validate what they produce.

I remain responsible for the architecture, the technical decisions and the quality of the work I deliver.