Agents and Background Work

The important part is not speed. It is that the agent can run your code and read the result, which means it can correct itself without you relaying error messages back and forth.

Agents succeed when there is a machine-checkable definition of done, and drift badly when there is not.

1. 1
   Good: “make the failing tests pass”

   Unambiguous finish line the agent can check itself.

2. 2
   Good: “fix every type error in this directory”

   The type checker is the judge, not the model's taste.

3. 3
   Good: “add tests until this file is covered”

   Measurable, and low risk if imperfect.

4. 4
   Bad: “improve the code quality”

   No definition of done, so it will keep going and touch everything.

5. 5
   Bad: “redesign the homepage”

   Aesthetic judgement it cannot verify. You will get changes you did not want.

Three failure modes are specific to something that acts across many steps without you watching each one. None of them show up when you are approving every change by hand, because you would have caught them at step one.

1. 1

   A wrong step compounds

   It misreads one function on step two and builds the next eight steps on that misunderstanding. By the time it reports back, the diff looks coherent and is wrong throughout, not just at the point of the original mistake.

2. 2

   Cost and time run away

   A model that has not converged does not know it has not converged. Left alone it keeps trying variations, and every attempt spends tokens and minutes whether or not it is getting closer.

3. 3

   A destructive action, taken confidently

   Deleting a directory it decided was unused, force-pushing over a branch, dropping a table to “clean up” a migration. Unless you have set it up to ask, it does not ask permission first — it explains afterwards why it seemed reasonable at the time.

An agent runs commands on your machine and edits many files without pausing. Do four things before letting one loose.

1. 1

   Scope what it is allowed to touch

   Point it at the directory the task is actually about. Treat anything destructive — deleting files, force-pushing, touching production data — as requiring your explicit approval, never the agent's own judgement.

2. 2

   Commit first, always

   A clean tree means the entire run can be discarded with one command.

3. 3

   Work on a branch

   So even a committed mess costs nothing to abandon.

4. 4

   Give it the check command

   Its stopping condition should be your real verification, not its own opinion of doneness.

The tests in src/lib/pricing.test.ts are failing. Fix the implementation in src/lib/pricing.ts so they pass.Do not change the tests. Run npm run check when you think you are done. If it fails,keep going. If you get stuck on the same error twice, stopand tell me what you tried.

Note the last sentence. Without a stop condition, a stuck agent will keep trying, and each attempt piles more changes on top of the previous failed one.

A git worktree is a second checkout of the same repository in another folder, on its own branch. That lets an agent work in one folder while you work in another, with no conflicts:

$ git worktree add ../myapp-agent -b agent/fix-pricing$ cd ../myapp-agent# let the agent work here while you keep working in the original $ git worktree remove ../myapp-agent    # when finished

An agent run produces a large diff you did not watch being made. Review it differently from a change you steered.

1. 1
   Read the full diff on GitHub

   Not in the terminal transcript. You want the finished state, not the narrative.

2. 2
   Check for scope creep first

   Files it touched that have nothing to do with the task are the strongest signal something went sideways.

3. 3
   Verify the check actually passed

   Run it yourself. “It says it passes” is not the same as it passing.

4. 4
   Look for deleted tests

   The fastest way to make tests pass is to remove them. Confirm the count went up, not down.