Here is how I used to build software. Open the editor. Write something that compiles. Fix it when it gets ugly. Fast, familiar, and it works when you are the one writing every line.
Here is how I built software with AI for about three days. Open Claude. Describe the thing. Watch code appear. Ask why that bit is wrong. Also a fast loop, in theory — except the AI is extremely good at sounding certain, and I am extremely good at being talked out of things. The loop optimised for conversation, not software.
So I stopped. Closed the editor. Opened a document instead and started writing down what the thing was actually supposed to do.
This went against everything I believe about building software
I need to be straight about how uncomfortable this was. I have practised Agile and DevOps for twenty years. Small slices, ship early, learn from real use, change your mind cheaply. I have run it, taught it, and argued for it in rooms full of people who wanted a Gantt chart. And here I was, writing a specification for a month before a line of code existed. That is waterfall. That is the thing I spent a career arguing against.
So why do it? Because the economics changed. Agile is a hedge against the cost of change: when a human writes the code, rework is expensive, so you take small bets and adjust. When AI writes the code, producing it is nearly free — and the expensive thing moves. The expensive thing becomes deciding what is correct, and finding out three weeks later that it was not.
If I had done this the way I normally would, here is what happens. Build a slice. It works. Build the next slice, and it quietly contradicts a rule the first slice assumed. Fix A, break B. Fix B, break A. With a human team that friction is visible — somebody complains. With AI it is not, because AI will cheerfully implement both contradictory rules, in different places, without ever telling you they disagree. You would be reworking code and workflows forever.
What "writing it down" actually meant
One workflow per session. What screen, what happens, what the person sees, what happens when it goes wrong. And this part matters: it was not dictation. I worked with the AI on every workflow. I would describe the journey, and it would come back with the cases I had not thought about — what if the guardian dies first, what if two people claim the same account, what if somebody revokes access halfway through. Then we would settle the business rule together, and I would lock it.
That is the trade the month bought. A person on their own misses edge cases; a person plus a machine that has read everything misses far fewer. Every rule we settled that way is a rule the code could later be measured against, instead of a rule somebody invented under pressure at midnight.
By 5 May I had thirty-five workflows, a hundred-plus screens described, and a decision record that ran to 1,229 entries. Not one line of it was code. All of it was the thing the code would later be measured against.
Why this is worth a month
Because an hour of deciding saves a day of arguing. Every question you settle before building is a question you do not answer badly, in code, under pressure, three weeks later.
And because of how AI actually fails. It does not usually produce broken code. It produces working code that solves the wrong problem, described confidently, and you do not find out until much later. A written decision is the only thing that catches that, because you can hold the code up against it.
The tool I asked for, and what it turned into
Logging a bug used to mean taking a screenshot, typing out what was wrong and where, and pasting it somewhere. Dozens of times a day, that is most of a day. So I asked for something simpler: let me point at the thing that is wrong.
What came back was a small tool that lives in my browser. I press a button, click anywhere on the screen that is broken, type a line, and move on to the next one. It records what I clicked, not just where.
The part I did not ask for is the part that mattered. Once a bug is captured, fixed and validated, it writes itself into a tracker file — and that file is then read back on every run, so the same class of bug gets looked for automatically from then on. The tool does not just record what broke. It teaches the build what to watch for. It was described to me as throwaway. I am not throwing it away.
The first thing that went wrong was my own tool
Near the end I built a checker to validate the catalogue against itself. It immediately flagged a pile of problems. I spent half a day chasing them before realising most were bugs in the checker, not in the catalogue.
That sounds like wasted time. It was not, because it taught me the thing I needed most: tools have bugs, documents have bugs, and telling them apart is the actual job. I have used that roughly weekly ever since.
The moment the plan stopped being the truth
On 7 May the catalogue cross-checked cleanly: 5,548 references, all resolving. A good day. Except one table claimed a part of the system had five modules, and the real code had none. The plan had not lied — it had described what we intended, and intent had moved on.
So: the catalogue records what we meant to build. The code records what exists. When they disagree, the code wins and the catalogue gets updated. Obvious written down. Not obvious at all at the time.
What I would tell myself on 26 April
Do exactly this, and do not feel bad about the month. If you write code before deciding what the code is for, the AI will help you build something excellent that you then have to throw away.
