27 lessons from building software with agents
Grouped by the part of the job each one serves.
- A circle is an agent. It does the work.
- A square is something it made or wrote.
- Hollow means it is not there yet.
- Grey means stopped, or wrong.
- A line is a boundary. Nothing an agent makes crosses it.
- Yellow is a person. A yellow line is a gate only they can open.
- You are the yellow dot. When a ring appears, that part is yours.
- That is the whole language. Every story on this site is written in it.
Choose the problem4
- 01The agent interviews me firstBefore any code, the agent asks every question that would change what it builds.
- 02Give the project one source of truthOne document says what the product is, who it is for and which decisions are mine.
- 03Stop building frontend, backend, then databaseThree finished layers can add up to nothing a user can do.
- 04Prove one complete path firstThe first slice exists to show you which of your assumptions are wrong.
Assign the work7
- 05Every slice gets a takeover packetEverything a new engineer would need to take over the work cold.
- 06Git carries truth between chatsChat history is temporary. The repository lasts.
- 08One lead agent, and specialistsOne agent owns the slice. The others get narrow tasks.
- 09Loop or graphA loop improves one task. A graph coordinates several.
- 10What the graph holdsBuilder, tester, security reviewer, checks, an evidence pack and a gate only I can open.
- 12Sequence, loop or graph?Choose the simplest shape that matches the work.
- 26Match the model to the taskThe most capable model does not belong on every task.
Set the boundaries7
- 07More freedom needs more structureThe longer an agent runs alone, the more has to be written down first.
- 11Preparing an AFK runFive things I do before I walk away.
- 13Anatomy of an AFK runIt starts with a contract and ends at a gate. Nothing in between merges without my yes.
- 16Keep secrets out of sightAn agent can read files, terminal output and process details. A secret can be in all three.
- 17Never test against production dataAgents need somewhere they can break things.
- 18Local means localA tool called local reached production, and spent money doing it.
- 19The database must be ready firstCode that deploys by itself must never arrive before the tables it expects.
Judge the result5
- 14Returning at the merge gateI read the evidence, then decide what ships.
- 15What happens after the code worksWorking code starts the delivery. It does not finish it.
- 20Nobody grades their own homeworkA builder's report that it is done is a claim. Someone else decides if it is true.
- 21Over ten times the estimateMy own count said one thing. The provider's count said another.
- 22No feature, no bugThe error went away because the feature went away.