OpenSpec and spec-first AI work, but they don’t fit every team

𝗢𝗽𝗲𝗻𝗦𝗽𝗲𝗰 𝗮𝗻𝗱 𝘀𝗽𝗲𝗰-𝗳𝗶𝗿𝘀𝘁 𝗔𝗜 𝘄𝗼𝗿𝗸, 𝗯𝘂𝘁 𝘁𝗵𝗲𝘆 𝗱𝗼𝗻’𝘁 𝗳𝗶𝘁 𝗲𝘃𝗲𝗿𝘆 𝘁𝗲𝗮𝗺 Spec-first development and OpenSpec absolutely have a place.

When I first read OpenSpec, I loved the core idea: requirements in the repository, give agents a persistent knowledge base, keep business intent close to the code. I already do this with other documents like ADRs to help agents. This felt incredibly powerful so had to try when pushed up my list by a colleague.

So I tried it on a large, mature application: multiple domains, 10,000+ tests, substantial unit and E2E coverage, ADRs, engineering docs.

My assumption was simple: point an agent at the repo, reconstruct the requirements, drop them into OpenSpec, done.

It didn't fit.

The problem wasn't OpenSpec. It was the 𝗦𝗼𝘂𝗿𝗰𝗲 𝗼𝗳 𝗧𝗿𝘂𝘁𝗵

I had only the tests. They describe what the application actually does and drive a fully automated regression suite. If I introduce another layer saying what the system 𝘀𝗵𝗼𝘂𝗹𝗱 do, what happens when the two disagree?

I kept going anyway, and this is where it became useful.

I had agents mine the codebase and build a requirements catalogue from existing behaviour. That gave me:

🔹 Clear feature documentation 🔹 BDD-style GIVEN / WHEN / THEN scenarios 🔹 Better navigation for humans and agents 🔹 Visibility of gaps and weakly tested behaviour

All valuable, but one boundary I couldn't automate around:

I can infer 𝗪𝗛𝗔𝗧 the software does. I cannot reliably infer 𝗪𝗛𝗬 the business wanted it to do that.

Those are different things. Retrospectively inventing business intent just to make an existing repository fit felt like work without enough value.

More importantly, the experiment clarified how I actually build software.

I'm not really spec-first. I start with a feature and a direction, iterate on the plan, design and implement with agents. I get something visible quick, learn, change it, and once the behaviour right, I 𝗵𝗮𝗿𝗱𝗲𝗻 it with automated tests.

My flow is closer to: 👉 Build → Learn → Iterate → Harden

OpenSpec feels much more natural when an organisation wants to define full requirements and behaviour before implementation. In that environment, I can see it being extremely powerful.

But many startups and SMEs work through discovery. They don't always know exactly what they're building until they've built some of it.

So I didn't change my process to fit OpenSpec.

I took the parts that fit: ✅ Requirements in the repo ✅ Clearer feature documentation ✅ BDD scenarios ✅ A navigable knowledge base for agents

Tests remain the strongest description of what my existing application actually guarantees. The requirements an agent read optimized replica.

I still like OpenSpec, just not for this system.

Maybe that's the better question for all these new AI development tools:

Not “Is this a good way to build software?” But: 𝗗𝗼𝗲𝘀 𝘁𝗵𝗶𝘀 𝗺𝗮𝘁𝗰𝗵 𝘁𝗵𝗲 𝘄𝗮𝘆 𝘄𝗲 𝗮𝗰𝘁𝘂𝗮𝗹𝗹𝘆 𝗯𝘂𝗶𝗹𝗱 𝘀𝗼𝗳𝘁𝘄𝗮𝗿𝗲?