Watch the Quito Lambda session: In this talk, Byron Duarte walks through a practical Spec-Driven Development workflow for using AI to understand and modernize an existing application while keeping engineers responsible for scope, architecture, and validation. Watch the full Quito Lambda talk on YouTube.
Modernizing legacy software with AI takes more than asking an agent to rewrite old code. In this Quito Lambda talk, Byron demonstrated how Spec-Driven Development can give AI-assisted modernization a clearer structure, helping teams understand an existing codebase, preserve business requirements, control technical decisions, and validate progress one feature at a time.
The example was a desktop point-of-sale system with customer, product, reporting, and database modules. The application was already working, but users needed access to information from different locations and devices. The goal was not to discard the system immediately. It was to introduce a web interface while keeping the software people already relied on operational.
That distinction matters. An AI coding agent may generate code quickly, but speed does not ensure that it understands years of architectural decisions, hidden business rules, or technical constraints. As we have also found when examining what is working, and what remains difficult, in AI-assisted software delivery, faster generation shifts more responsibility toward context, review, and validation.
Byron’s proposed answer was Spec-Driven Development: a workflow in which specifications become a stable source of context for engineers and AI agents. Instead of relying on a long conversation with a model, the team records its understanding, decisions, constraints, and acceptance criteria in durable project artifacts.
Why legacy modernization needs more than a prompt
A legacy system already contains accumulated decisions, dependencies, conventions, integrations, and compromises. Some remain valuable; others may have become limitations. Teams must distinguish between them before changing the system safely. This discovery is also central to using AI to assess and reduce technical debt, because teams need to understand where change creates value before automating it.
Before defining where a product should go, engineers need an accurate picture of where it is today. They need to identify the components that own central business rules, how data is stored and shared, which integrations constrain the design, and what must continue working throughout modernization.
Without that foundation, an agent can make plausible but incorrect assumptions. It may treat a customer-specific name as part of the product, recommend a technology that conflicts with the existing environment, duplicate existing logic, or overlook a critical dependency.
Long, unstructured AI sessions introduce another problem: decisions compete with implementation details, generated output, and error messages for limited context. Spec-Driven Development moves approved knowledge into specifications that can be reviewed, versioned, reused, and improved. The goal is not documentation for its own sake. It is to give humans and AI the same reliable frame of reference.
Start with guided codebase discovery
The first phase in the demonstration was a guided exploration of the existing codebase. Byron used Repomix to package the repository into a format an AI agent could analyze more efficiently. This helped the agent form an initial view of the architecture, database structure, design patterns, dependencies, and relevant specifications.
That first analysis should not be treated as authoritative. Engineers still need to verify important conclusions against the code, runtime behavior, database, deployment configuration, and the experience of people who use or maintain the system.
For a large codebase, discovery may need to happen by module or business capability. A team might analyze authentication, inventory, reporting, and data access separately before connecting the findings into a broader architecture map. Sensitive files, generated assets, dependencies, and irrelevant build output should be excluded, while schemas, interfaces, configuration, and representative tests may deserve special attention.
Good discovery should also expose uncertainty. If the agent cannot determine whether a rule belongs in the database, application service, or interface, that uncertainty should become a question for the team, not an invitation to guess.
Create a project constitution
The discovery phase supplies the raw material for what Byron called the project constitution: a small set of Markdown documents that captures the shared rules and direction of the work. In the demonstration, it contained three core elements:
- Mission: What the current system does, whom it serves, the business problem, and the modernization objective.
- Technology stack: Languages, frameworks, infrastructure, database, authentication approach, relevant versions, and technical constraints.
- Roadmap: High-level scope, delivery phases, priorities, dependencies, and capabilities explicitly outside the first release.
For the point-of-sale example, the mission was to make business information available through a web interface on multiple devices while keeping the desktop system operational. Initial capabilities included sales reporting, cash-register status, and inventory visibility. This type of transition requires the same discipline as custom web application development: the new experience must account for actual usage, integration boundaries, and maintainability, not simply reproduce the desktop interface in a browser.
Recording exclusions was equally important. Sales entry and external-system integrations were outside the initial scope. Explicit exclusions reduce the chance that an agent broadens the work because a related feature seems logical.
The constitution also captured the chosen direction: reuse the existing data-access foundation and SQL Server database while adding an ASP.NET Core API and React frontend. These were human decisions. AI could help compare options, but engineers remained responsible for deciding what to preserve and where to introduce new boundaries.
Modernization can be incremental or a rewrite
The point-of-sale example illustrates an incremental path: introduce a web interface and API around a system that continues to perform important work. A full rewrite may be appropriate when the existing foundations cannot support the required product, security, scalability, or maintainability goals. Spec-Driven Development does not prescribe one strategy. It makes the chosen strategy, assumptions, and validation criteria explicit.
For this project, the first objective was not to reproduce every desktop capability in the browser. It was to make selected information available through a new web experience. That reduced the initial surface area of change and gave the team an opportunity to test permissions, data access, architecture, and deployment before moving into transactional features. Our guide to choosing a first modernization milestone explores how teams can narrow that decision.
Make clarification and approval part of the workflow
Before writing the constitution or implementing a feature, the agent asked structured questions and presented possible answers for confirmation. This exposed an incorrect inference: the code contained the name of a company where the system had been installed, so the agent initially treated that organization as the intended customer. Byron corrected the assumption and clarified that the product should remain customer-agnostic.
Code can reveal how a system behaves, but it does not always explain why it exists, which behavior is accidental, or what the business needs now. Clarifying questions should cover intended users and permissions, the source of truth when documentation and implementation disagree, mandatory integrations, compatibility requirements, and whether existing business rules should be preserved or revisited.
Human review is therefore not a final check after generation. Product owners, engineers, and users still define the problem, choose tradeoffs, confirm scope, and approve the plan before implementation begins.
Move from direction to feature specifications
Once the constitution was approved, the workflow moved to feature-level execution. Each feature received three supporting artifacts:
- Requirements defining the objective, users, scope, expected behavior, constraints, and exclusions.
- A plan dividing the work into ordered tasks and identifying the components likely to change.
- Validation criteria describing the functional, technical, and integration conditions required for acceptance.
The first feature was intentionally modest: scaffold a backend API that compiled and a minimal React application. Although scaffolding may appear basic, it establishes repository structure, build behavior, frontend–backend communication, and a foundation for cross-cutting standards.
Later features could build on that verified baseline. A reporting feature, for example, might specify which metrics are displayed, where data comes from, how date ranges work, which roles can view the information, and how the team will confirm that web results match the existing system.
This specificity reduces the agent’s decision space and gives reviewers a concrete basis for evaluation. Instead of asking whether a large batch of generated code “looks right,” they can compare it with a defined objective and finite acceptance criteria.
Work in small, verifiable increments
Incremental delivery is especially useful in modernization because teams are learning while they build. Documentation may be incomplete, unexpected coupling may surface, or a simple feature may depend on an undocumented business rule.
Byron described a repeatable cycle:
- Select the next bounded feature.
- Have the agent read the constitution and relevant system context.
- Ask clarifying questions and draft requirements.
- Review and approve the requirements and implementation plan.
- Implement within the approved boundaries.
- Run automated and manual validation.
- If validation fails, return to the plan or specification before continuing.
These checkpoints keep responsibility with the team and make it easier to identify where an incorrect assumption entered the process.
Treat validation as an engineering standard
A specification is useful only when its acceptance criteria can be verified. Depending on the project, quality gates might include a successful build, appropriate unit and integration tests, confirmation that new outputs match trusted legacy results, security checks, performance criteria, logging, and manual confirmation that the feature solves the intended business problem.
In the talk, Byron used code coverage and SonarQube analysis as examples of measurable standards. The point was not to prescribe one tool. It was to define the evidence required before generated work can be considered complete.
These controls turn AI output from a suggestion into an auditable engineering change. The agent may help write code, generate tests, run checks, and explain failures, but the team defines what “complete” means. This principle also appears in our discussion of turning AI pair programming into a reliable process.
Keep specifications useful, portable, and cost-conscious
Although the demonstration used Claude Code, the method is not tied to one assistant. Its durable assets are the constitution, feature specifications, validation rules, and workflow conventions. Keeping those artifacts in version control allows engineers to begin with the same approved context and makes changes to scope visible in Git history.
This approach can also reduce repeated context and cost. Teams can package only relevant repository content, analyze large systems by domain, store approved decisions in concise files, and begin a fresh session after a phase is complete. Stable knowledge persists; temporary errors and experiments do not need to follow every future interaction.
Specifications should remain concise and decision-oriented. More documents do not automatically create more control. Each artifact should answer a practical question: What are we changing? Why? Within which constraints? How will we know it works?
Teams must still consider security and data governance, including what repository content is shared with an AI provider, how secrets and sensitive data are excluded, and which model or deployment options fit the project’s privacy requirements. Production modernization also needs reliable delivery pipelines, monitoring, and recovery practices as part of a broader DevOps and scalability foundation.
The real advantage is disciplined alignment
The strongest takeaway from this Quito Lambda session was not that an AI agent can transform a desktop application into a web product on its own. It was that AI becomes more dependable when the surrounding engineering process is explicit.
Spec-Driven Development connects business intent, technical constraints, implementation tasks, and validation. AI can accelerate exploration, planning, scaffolding, implementation, testing, and analysis. Engineers still provide the judgment: correcting assumptions, choosing architecture, setting quality standards, managing risk, and deciding when a feature is ready.
That balance, automation guided by durable specifications, measurable validation, and human approval, is what turns AI-assisted coding into a repeatable modernization practice.
This article is based on Byron Duarte’s presentation at Quito Lambda. Watch the full session on YouTube.
At Stack Builders, we help organizations modernize legacy software with pragmatic engineering practices that protect business continuity and create room for future growth. Explore our legacy system modernization services or contact our team to discuss your system.