The lost art of specification #
Before the industrial revolution, if you wanted a suit, dress or furniture you thought about what you wanted, articulated that thought to a craftsperson and they made it for you. If the person making it was any good then they knew what questions to ask if there were any gaps. Getting that conversation right mattered because if the end result wasn’t what you wanted you’d lose money and a lot of time.
Then manufacturing came along. Now almost everything we buy - from small things like a loaf of Hovis bread to large things like a Ford Galaxy - is at least the millionth version of itself. We browse, compare, and select but we never have to explain how much wheat goes into the loaf or how much torque a prop-shaft needs to withstand.
I’ve spent my career building one-offs #
I started out as a civil engineer. Bridges, tunnels, underground stations. Whatever I was a part of building there was only ever going to be one of those things. Getting the specification wrong didn’t mean we shipped bad feature — it meant we lost millions, wasted months and potentially injured people or worse. You think about the risks before the first concrete is poured and the 24/7 tunnel machine starts to dig.
Then I moved to internet startups - a long story - but still found myself in a world that also builds one thing once. Every SaaS platform, every web product is intended to be unique so you’d think software engineers should be good at planningh. and specifying but oddly they weren’t. Planning isn’t easy, starting to code without a plan is - especially when the pressure is on to deliver.
PRs are not Planning #
I never really understood why the Pull Request was the one quality gate before code goes live. Don’t get ,e wrong, they’re massively useful but by the time that code is in review, the decision about what to build has already been made. If the idea was flawed then time has already been lost and there’s pressure to accept something that’s not really that for purpose. I’m convinced this is a major contributor to technical debt.
So I introduced Method Statements into teams. Before starting a piece of work, spend an hour or so writing down what you’re about to do — not just the happy path but consider the risks from dependencies on other teams, third-party providers you’re not sure about or technology you haven’t used before. When I first came across Method Statements in the construction industry I saw them as a massive beuracratic overhead - I knew how things were built why did I need to write that down on paper for someone else to rubber-stamp ? Well, writing a method statement forced me to write my thoughts down in a coherent narrative. I don’t believe there was a time when I was part-way through that process when I didn’t stop and think “hmm,.. I hadn’t thought about that.”
Sadly writing method statements in sofware never really stuck. The pull of just starting is too strong because planning feels like not-working even when it’s probably the most valuable thing you could be doing.
AI doesn’t read minds #
Then along came AI coding tools like Microsoft’s co-pilot and Anthropic’s Claude. I must admit to being a sceptic at first until Oz my colleague here at shipfastguys showed me how he used Claude - to plan and specify.
Agents will write hundreds, possibly thousand of lines of code so if you want that code to bring value not drift or chaos then you have to be good at telling it what you want - aka a specification:
- the desired outcome;
- users and use cases;
- constraints and exclusions;
- dependencies and assumptions;
- edge cases and failure modes;
- acceptance criteria.
I took to it straight away and have barely written a line of code since. I thought I’d miss coding; I was proud of my skills and enjoyed crafting well structured code but I realised I enjoyed problem solving more and that I too had been caught in the time-consuming trap of code-construction.
What truly sealed the deal for me was when I’d spent a couple of days putting together a spec then building the code was having the stakeholder tell me that, now they see it, that’s not really what they wanted and could it be like this instead (remember where we started with people not being good at articlulating what they want ?). Over an Espresso in my local Costa I rewrote parts of the spec, scrapped the agents code (no emotional attachment there) and within 2 hours I had a pivoted system up, running and fit for purpose.
The teams I see getting consistent results from AI tools are the ones who’ve developed the discipline to specify before they build. Not lengthy documentation for its own sake, but clear thinking about what success looks like, what the edge cases are, and what the thing definitely shouldn’t do.
That’s the skill. It’s not new. We’ve just had a century or so of not needing it, and now we do again.
We run workshops and hands-on sessions to help teams get better at working with AI — including the specification habits that make the difference. Get in touch if that sounds useful.