Lessons from real-world failures using spec-driven development Lessons from real-world failures using spec-driven development Lessons from real-world failures using spec-driven development

AI-native development, specifically spec-driven development (SDD), is increasingly seen by developers as a ‘silver bullet’ for getting meaningful value from AI, promising faster delivery, cleaner abstractions and flawless alignment.

But for those of us actually doing the coding, the reality is a little messier (or at least, it has a bit of a learning curve).

It’s not completely unusual for specs to drift or agents to misinterpret intent, and we sometimes need to throw away entire implementations and start again. However, none of this is a failure - it’s all part of the development process.

Enterprises getting the most value from AI development don’t avoid mistakes. Instead, they embrace mistakes as part of the process and build systems to learn - and recover - from them quickly and deliberately. Below are five of the most common pitfalls, or ‘failure modes’, we’ve seen recently, and the keys to rapidly fixing them.

One of the most expensive mistakes you can make is also the hardest to notice until it’s too late. You follow the SDD process perfectly - your spec is highly detailed, and the generated implementation is remarkably clean. But the output is completely wrong.

This happens when developers jump into writing specs before they truly understand the core problem. I once spent three days building a full spec and implementation, only to find my baseline assumptions about the system were incorrect. The SDD process worked flawlessly, but the inputs weren't correct.

Why it happens: Spec-driven development amplifies clarity, but it ultimately doesn’t prevent you from building the wrong thing. If your understanding is shaky, SDD will scale that shaky foundation into a fully-realised, incorrect system.

The fix: Introduce a dedicated learning phase to the development process. Use this to run research spikes, prototype multiple approaches, build disposable proofs of concept and iterate with stakeholders to map the problem space - all before you start writing a formal specification.

Key learning: SDD is an execution tool, not a discovery tool, so use it only after you have a firm grasp of what you’re building.

If spec-driven development works so well for complex features, we should use it for every ticket, right?

Wrong.

SDD doesn’t always scale down well, because writing specs, generating implementation plans and validating AI outputs takes time. For minor tasks, the process overhead of SDD can eclipse the actual work. Developers who apply SDD to simple refactors or UI tweaks can spend more time managing the AI than actually delivering value.

Why it happens: Teams often overcorrect. They discover something that works well and start applying it everywhere, even when it adds unnecessary overhead.

The fix: Match your approach to the complexity of the task. High-performing teams now operate across a spectrum of AI methods, depending on the use case:

• Tiny changes (e.g., UI tweaks) or rapid prototyping: building an exhaustive prompt that contains a small spec of the change required, and/or using plan mode is usually faster here.
• Medium-large changes: The full SDD flow.

Key learning: The goal isn’t to force a rigid pro cess, it’s to apply the right level of structure to the problem at hand.

Traditional, deterministic systems have straightforward specs - you define the inputs, outputs and business rules. But AI agents break this model.

When you build an agentic system, stakeholders often have high-level goals, but no clear picture of the required interaction patterns, processing times or behaviour under uncertainty. Early attempts to formally spec these systems almost always fail.

For example, a client might say: “We want an AI agent that gives us insights from our data”. But what does that actually mean in practice? Should it respond instantly or take time to reason? What should it show while it’s processing? How should users refine their queries?

Now asking the right questions is vital, but sometimes these details only become clear when you see the system in action.

Why it happens: With AI interfaces, behaviour isn’t predefined - it emerges through interaction. And until users try it, they can’t fully articulate what they need. In other words, you don’t know what you need the system to do until you’ve seen what it can do.

The fix: Prototype the experience first. Build rapid, interactive prototypes and run live iteration sessions with stakeholders. Use real-time feedback loops to demonstrate the behaviour before you try to lock it down in the spec, and only formalise it once everyone agrees on the experience.

Key learning: When you're building something entirely new, the challenge isn't just defining the system, it's understanding what the system should do in the first place. Until stakeholders see something tangible, they can’t fully articulate what they need. As the age-old saying goes, “You don’t know what you don’t know!”

This failure is subtle but incredibly costly. It often starts with a minor omission in a spec; perhaps you leave out a specific database requirement. Instead of pausing, the model fills in the gap with a default assumption that works in general, but might not fit your use case. The implementation plan expands this assumption into a detailed architecture, and the code generation bakes it into dozens of files. If you only review the output at the very end, you can lose hours or days unwinding the mess to find the root cause.

Why it happens: AI systems don’t leave gaps. If you don’t specify a detail, the model assumes it for you.

The fix: Review early and often. Always review the spec and the implementation plan before execution begins. It can feel tedious to go through a markdown file, but catching a one-line assumption early is vastly less costly in terms of time and effort than refactoring a massive codebase.

Key learning: Small errors at the spec level compound exponentially downstream, so it’s important to catch them before code is written.

Our fifth failure mode is about alignment. When developers write specs in isolation - without input from product managers or designers - the specs reflect a narrow, purely technical view of the system. This isolation breeds mismatches between what the business needs and what the AI builds.

Why it happens: We tend to treat specs as purely technical artifacts, rather than understanding they are also business agreements.

The fix: Treat the spec as a shared collaboration surface. High-performing businesses use specs as a live discussion board between engineering, product and design teams. When everyone aligns on the spec before generation starts, you see fewer downstream corrections and much lower rework rates.

Key learning: The spec is a technical blueprint, but it also plays a vital role as an alignment mechanism for the whole team.

As we mature in AI-native engineering, our behaviour shifts. We stop forcing rigid processes, and we slow down upfront to move faster later. We learn to choose the right level of rigour for the task.

We’re all learning as we go, which is the beautiful thing with engineering in general, and AI-native in particular. It’s never been about getting things right the first time.

What I would advise is to shorten the feedback loop where possible. We try something, learn quickly, adjust our approach and try again. Sometimes that means throwing code away or rewriting a spec from scratch.

The teams getting this right aren’t the ones avoiding mistakes, but instead they’re catching them early, before they compound. If you take one thing away, it’s this: don’t try to move faster, but do try to validate sooner. Because in AI-native development, speed only matters when you know you’re heading in the right direction.

If you’re navigating similar challenges in your organisation, we can help. Nearform designs processes that make AI-native engineering more predictable… and more effective. Feel free to get in touch!