Something funny happened in my work this year. I spend more time writing than coding. Not code comments, not documentation after the fact. I mean specs. Real, careful descriptions of what we want to build, why we want it, and what done looks like.
Ten years ago this would sound like a step backwards. Big upfront documents were the thing agile was supposed to kill. But the world changed. Agents write a lot of our code now. And when an agent writes the code, the quality of the result depends almost completely on the quality of what you asked for.
The bottleneck moved
For most of my career, the slow part of software was building it. We had more ideas than hands. So we optimized everything around the building. Faster frameworks, better IDEs, more developers.
Now the building part is fast. An agent can produce a working feature in an afternoon. The slow part, the part that decides if the project succeeds, is knowing what to build. The bottleneck moved from the keyboard to the head.
Here is the rule I see every week. Good specs multiply AI output quality. Bad specs multiply garbage. The agent does not push back like a senior developer would. It does not say, wait, this requirement contradicts that one. It just builds the contradiction, fast and with confidence. You get your confusion back, implemented, with tests.
So a vague spec used to cost you a confused developer asking questions in standup. Cheap to fix. Today a vague spec costs you a thousand lines of confident wrong code, a pile of tokens burned to generate it, a review that takes hours, and sometimes a bug that reaches a client. The price of being unclear went up.
The old ideas are suddenly modern
The strange and beautiful part is that the best tools for this problem are old. Eric Evans wrote about ubiquitous language more than two decades ago. The idea is simple. The whole team, business people included, uses the same words for the same things. No translation layer between what the business says and what the code says.
When your reader was a human developer, sloppy language was survivable. The developer would ask, oh, when you say account do you mean the login account or the investment account? An agent often does not ask. It picks one meaning and runs. If your spec uses one precise word for each concept, the agent picks right. Ubiquitous language stopped being a nice practice and became an input format.
Same story with Alistair Cockburn and his book Writing Effective Use Cases. A good use case names the actor, the goal, the main path, and the things that can go wrong. That structure was always good for humans. For agents it is almost a programming language. When I write a spec as a clean use case, with the failure paths listed, the generated code handles those paths. When I write a loose paragraph, the happy path works and everything else is a surprise.
I find this a bit poetic. The industry spent years calling this stuff heavy and old fashioned. Now the most modern workflow in software, agentic coding, rewards exactly these skills.
This is my actual job now
When I joined Mawer in April, the role was described as product focused. In practice that means I sit between stakeholders and implementation. I listen to what people need, I ask the annoying questions, I turn the answers into requirements, then architecture, then working software. Some of the implementation I do myself, a lot of it I do with agents.
And I can say honestly that the spec work is where the value is created or destroyed. A morning spent with a portfolio analyst, really understanding their workflow, saves days of building the wrong thing. The agent makes the building cheap. Nothing makes building the wrong thing cheap. Wrong is still expensive, it just arrives faster now.
There is also a risk side to this. In an investment firm, software that does almost the right thing is worse than no software. A clear spec is not bureaucracy here. It is risk control. Every edge case I write down before coding is an incident that does not happen after.
How I write specs in 2025
Nothing fancy. My format is short and boring on purpose.
- What problem are we solving and for whom, in one paragraph.
- The words we use and what they mean, the small glossary.
- The main flow, step by step, like Cockburn taught.
- What can go wrong and what should happen when it does.
- What is out of scope, written explicitly.
That last one matters more than people think. Agents love to add features. If you do not draw the border, they decorate the whole house when you asked for a shelf.
I write it in plain language, the same language the stakeholder uses. Then the spec goes to the agent almost as it is. When the generated code is wrong, the cause is almost always a hole in my spec, not a failure of the model. That was humbling to learn. The machine exposed how unclear my thinking was.
If you want to invest in one skill right now, I would not say prompt engineering. I would say requirements engineering, the unfashionable old name for an unfashionable old skill. Learn to write down what you want with no ambiguity. It was always valuable. With AI it became a multiplier on everything else you do. The teams that can specify clearly will run circles around the teams that just type fast.
Funny how the future arrived and it asked us to write better, not to code faster.
Pax et bonum.