Working with coding agents

Jovanus Hartono

I work with coding agents every day. These are the rules I've written down for them, many of them right after one did something I didn't want.

Asking and doing

  • Treat a question as a request for an answer. "Can we do X?" should get an answer, maybe a sketch, and then a stop. The work starts on a clear go.
  • Anything other people will see needs that go first: opening or merging a pull request, writing to the issue tracker, running a migration, changing infrastructure. That holds even when it's easy to undo.
  • Problems found halfway through a task come back in chat. The agent doesn't file tickets for them.
  • When a step needs a secret, ask who should run it. Either the agent runs it and the value ends up in the transcript, or I run one command myself.
  • Ask only when the answer changes the work. Otherwise pick the reading the code supports best, say which one, and carry on.

Showing the work

  • Check every UI change in a real browser, at desktop and phone width, before anyone reviews it. Then hand over a short numbered list of what to look at, riskiest first.
  • For visual work, show an ASCII mockup before writing code.
  • For a behaviour change, show a before and after table of what the user will see, one row per outcome. I once approved a change from a prose description and reverted it the same day, once I saw what it did.

Reporting

  • Lead with the outcome, and use bullets over paragraphs.
  • Cut it by half, then state the result. How it got there rarely matters.
  • Explain a mechanism in one sentence and a small diagram, then stop.
  • Teach a new infrastructure idea with an everyday object first. A security group is easier to picture as a guest list on a door.

Memory

  • Save every correction with the reason behind it, so the next session already knows. One of mine is a single line: "I prefer not to use Zustand unless I really need to."