Every session with a coding agent starts from zero. It doesn’t remember why we picked that data model, what we agreed to leave out, or what we decided last week. Whatever isn’t written down is gone. I’d love to call that a quirk of AI, but it’s also a fair description of me on a Monday morning.
This post is my reflection on working with specs in AI-driven development, and how I plan to use them going forward.
A Quick Note on Process#
This post came out of a 20-questions-style interview with Claude. I sometimes think better while conversing, so it seemed like a fun way to try writing a blog post. Claude asked, I answered, it drafted, and I edited. The opinions and the mistakes are mine. It also corrected me where I’d misunderstood something, which you’ll see in the Naur section.
What a Spec Is (to Me)#
A spec is a markdown file that says what we’re building, what we’re not building yet, and how we’ll know it’s done. It can hold rough user stories and implementation notes that matter later. I used to call it a roadmap, but a roadmap is about when. A spec is about what and done, and that’s why acceptance criteria matter.
In our course we use the AI Hero workflow: a “grill me” session, then a spec, then issues. The grill-me part is the underrated bit. It forces my assumptions out into the open, and it asks about things that seem obvious once mentioned but that I’d have forgotten to say.
Trust, but Read the Tests#
I have the agent develop via TDD, so each acceptance criterion ends up as a test I can read. If the agent writes both the tests and the code, a misunderstanding can hide in both, so I read the tests myself. I also read the spec before implementation, since fixing a wrong assumption there is cheap. Afterwards I manually try a few failure scenarios.
I’ll admit I’ve drifted into a manager-style role. I choose Java so I can follow the code, but so much gets produced that I direct and orchestrate more than I read line by line. That’s why the tests and the spec matter so much.
Where I Got It Wrong#
On my current project I wrote one big MVP spec up front. It was too broad. Some features came out half-baked, and I did double work fixing them. Next time I’ll keep an MVP spec for the foundation (data model, conventions) and write smaller feature specs on top of it, so I can parallelise.
That sounds a bit like waterfall, but the thing that made waterfall painful was waiting months to find out the design was wrong. With agents, that feedback arrives in hours.
I’ve also learned that the agent rarely ignores the spec. The trouble starts when I forget something. If I haven’t told it to ask, it quietly designs that part itself.
For typos and CSS tweaks, I just prompt. A spec should scale with the task.
Naur and the Theory#
My first instinct on Peter Naur’s “Programming as Theory Building” was that it’s about domain knowledge, like a product owner in Scrum. That isn’t quite it. Naur’s “theory” is the programmers’ understanding of the program itself: why it’s built the way it is and how to change it sensibly. He argued it lives in people’s heads, not in the code or the documentation.
So who holds the theory when an agent writes most of the code? I do, and the spec records part of it. The agent only borrows it per session. A human developer who forgets can usually rebuild the theory by working in the system, but the agent has to be handed it every time. A spec is never the whole theory, but it keeps the goldfish from starting blind.
My Advice#
Keep the spec focused on the feature, but add a little context about future work. “Out of scope” tells the agent what not to build, and the future context tells it what not to block. I keep specs after a feature ships, since they carry the why. I delete or update them when they go stale, because an outdated spec can actively mislead the next session.
Wrap Up#
Specs won’t make an agent remember. They make me write down what I’d otherwise keep in my head and forget by Thursday. Next time, I’ll start with a small foundation and let the features build on it.