Navigating Legacy Codebases: 5 Takeaways from Implementing SDD with Open Spec

Spec-Driven Development (SDD) isn’t exactly “breaking news” anymore. However, in my experience, there’s a massive gap between understanding the theory and actually executing it efficiently in a large-scale project.

Photo by Nick Fewings on Unsplash

As an engineer who work on a legacy codebase with over 10 years history, I realized that poorly planned SDD is often less efficient than simple prompt engineering.

This article isn’t a tutorial on Open Spec or SDD : plenty of great docs exist for that. Instead, I want to share my honest lessons learned while trying to make SDD work within a massive legacy codebase.

I currently use the Open Spec framework. Unlike SpecKit, it offers a more flexible structure and straightforward steps that make it much easier to “plug” into existing legacy systems. It also pursues the idea of “living documentation” — you can use the archivecommand after development to maintain a single source of truth. Plus, it plays well with various LLMs, so you aren’t locked into a specific AI ecosystem.

Takeaway 1: Choosing the Right Battles for SDD

The first thing I learned? Not every task needs a full SDD treatment.

The keyword for SDD is new business logic. This is where an engineer’s understanding of architecture and business decisions is most critical. You need to define the design decisions and, more importantly, human-defined boundaries (scope).

Another great use case is architectural refactoring. Even though we strive for “Clean Architecture,” real-world code is often a series of trade-offs based on business goals. SDD allows the engineer to keep the steering wheel, providing a structured definition that ensures the AI executes within a standardized framework.

Conversely, for straightforward bug fixes or simple UI tasks, I still prefer a Research -> Plan -> Implementation (RPI) flow. AI is already incredibly strong at tracking tech stacks and codebases; we don’t need to over-engineer the process.

[embed]This video introduce RPI style very well, highly recommend

*My rule of thumb for using SDD:

1. Do I have confidence that I can align the AI’s understanding with mine in just three prompts?
2. Is it possible for the AI to grasp the full context just by reading the codebase?*

If the answer to both is No, that’s your cue to use SDD.

Takeaway 2: Boundary Context is Everything

When facing a legacy codebase, it’s easy to burn through tokens forcing an AI to read “fat” singleton objects.

The beauty of SDD is that we can use natural language to define the Boundary Context. We can tell the AI,

”You’ll get specific values from this object; don’t bother digging deeper.”

This is where your knowledge of the system architecture becomes a superpower. You define the data flow and current limitations, giving the AI “hints” that save reasoning resources.

Think of it as writing a natural language Interface for the AI agent. You define what matters and hide the legacy complexity that would only confuse it.

Takeaway 3: Tools Change, Intent Stays

The AI landscape moves at a breakneck pace. SDD as a concept is barely two years old, yet we already have a dozen “hot” tools.

However, the core remains the same: Intent-Driven Development. Whether you use Open Spec, SpecKit, or something else, the engineer’s job is to clarify:

What are we doing? Why? How do we verify it?

For a spec to actually work with AI, it needs to cover:

• Definition of Done (DoD)
• Design Approach
• Decisions & Trade-offs
• In/Out of Scope
• Edge Cases

Stop focusing on how to tell the AI to write every line of code. Focus on how to let the AI know what the correct result looks like.

Takeaway 4: Spec Reviews are as Vital as Refactoring

Open Spec’s “living document” feature is great — it summarizes your collaboration into documentation. But we have to be careful: Outdated documentation is technical debt.

AI helps us produce faster, which also means we can produce “debt” faster.

*To keep things lean, I ask myself two questions before archiving a spec:

1. Would a future engineer (or a future AI) need this specific context to understand the system later?
2. Does this document bridge a significant knowledge gap?*

If the answer isn’t a solid Yes, don’t let it clutter your codebase.

Takeaway 5: The Role of the Engineer

I’m writing this last part for my future self. Sitting here in 2026, about 2.5 years into my career, I find myself constantly reflecting on my value in this AI-driven era.

I don’t have all the answers for where the industry is heading, but I do know this: Software engineers are, first and foremost, problem solvers for people. I entered this field because I love solving real-world problems.

AI might be a better “implementer” than I am, but as engineers, we are the ones who understand how to bridge the gap between human needs and AI execution. If we can find the right balance in this partnership, we can expand our “defensive range” and unlock ideas that were previously held back by platform limitations.