Spec-Driven Development in a Modular Monolith — AI Skills, Context, and Change Verification

From Principles to Practice

In our previous article, Spec-Driven Development: How to Delegate Implementation to AI Without Losing Control, we covered the fundamentals: specifications, technical plans, task lists, and the rules and skills that guide and constrain AI models. This time, we'll explore how this approach works in a system that has been developed and maintained for years.

AI-generated code must work within an existing architecture, alongside established integrations and business processes.

That's why the greatest value of Spec-Driven Development (SDD) isn't simply faster coding. It's the ability to translate business requirements into concrete tasks, provide AI with the right knowledge, and verify that the results meet agreed expectations.

We'll use an illustrative example: a Magento 2 store and a change that only seems small in scope. If even this change requires several decisions before any code is written, more complex integrations will involve considerably more.

A Small Change, a Real Business Risk

The store displays related products on product pages, such as substitutes. Some of these relationships are maintained manually by the e-commerce team. A new integration is intended to retrieve additional product relationships from a Product Information Management (PIM) system and keep them up to date in the store.

The business goal is straightforward: reduce manual work and provide customers with more up-to-date product information.

The problem arises when synchronization replaces all existing relationships, including those created by employees. The code runs without errors, yet the product page no longer looks the way the team intended.

A similar problem occurs when the PIM returns incomplete data and the integration interprets missing entries as an instruction to delete existing relationships.

Even if sales remain unaffected, this creates a business risk: it changes how products are presented and introduces changes to a live store that nobody approved.

One Rule, a Shared Reference Point for Everyone

In SDD, we begin by defining the expected behavior. For example, the specification might include the following rule:

Synchronization may only delete product relationships that it manages. Manually managed relationships must remain unchanged.

"Relationships it manages" does not necessarily mean "relationships it created." An employee may have taken over a relationship originally added by the integration and subsequently managed it manually.

The specification must therefore define how such ownership transfers work and what happens when the same relationship is managed manually and also exists in the PIM.

That single rule creates concrete responsibilities for everyone involved:

Stage	How the rule is applied
Business requirement	The business defines the goal: automated relationships must not overwrite the team's work.
Specification decision	The business analyst and stakeholders define when a relationship becomes manually managed, what happens when a relationship exists both manually and in the PIM, and how to treat incomplete data from the PIM.
Implementation plan	The developer checks whether the system already distinguishes manually managed relationships from integration-managed ones. If not, they propose a solution.
Acceptance criteria	"After synchronization, all manually managed relationships, including those taken over from the integration, still exist and remain unchanged."
Verification	QA verifies the criterion using test data covering manual, integration-managed, and transferred relationships.

The specification goes beyond defining business rules. It also identifies how those rules should be implemented within the existing architecture: which synchronization mechanisms to reuse, where relationship ownership should be determined, and which existing contracts must be preserved.

The implementation plan translates these decisions into specific, verifiable tasks.

During planning, a question often emerges that wasn't obvious in the original requirement: how does the system know who manages a particular relationship?

The answer should be agreed upon by the team and business stakeholders, rather than left to AI to resolve based on whichever implementation appears simplest.

Before coding begins, the team reads the specification and subjects it to an independent review, for example, using another AI model in a separate session. The goal is to identify incorrect assumptions, missing scenarios, and unnecessary complexity. A human remains responsible for deciding which findings to accept.

Implementation begins once the questions blocking key data and architecture decisions have been resolved, the specification has been checked against the system's current behavior, and every requirement has verifiable acceptance criteria.

If a contradiction emerges during implementation, the team revisits the decision and updates the specification before changing the system's behavior.

The specification does not replace communication with business stakeholders or human responsibility for decisions. It provides a shared reference point.

We treat AI instructions similarly: they are version-controlled alongside the project. This makes it possible to determine which instructions were in place when a particular change was implemented and reviewed. However, storing instructions in a repository does not guarantee that everyone works with exactly the same context.

Context: The Right Knowledge at the Right Stage

AI also needs knowledge of the existing system: its modules, integrations, data model, and testing practices.

A large context window does not guarantee that a model will effectively use every piece of information it receives. As Anthropic explains, the precision of retrieving information from context gradually declines as context size increases, although models vary in how they handle this.

Excessive or inconsistent context increases the risk that the model will overlook a rule concerning manually managed relationships or build a new mechanism alongside an existing one.

That's why we organize knowledge into separate layers:

• Project-wide rules — a concise set of principles loaded for every task. These include requirements that must not be overlooked, such as the rule that deleting or overwriting manually entered data requires an explicit decision in the specification.

• Skills — instructions for particular types of work, loaded when relevant.

• Task specification — either provided by the team or located by the agent according to project rules, together with related decisions and contracts. The goal is to select relevant context, not to prohibit the agent from searching independently.

• System facts — the agent verifies the current state of the relevant components by examining the code and configuration.

Skills are neither an official Magento standard nor a mandatory component of SDD. They can contain procedures, project knowledge, constraints, examples, and references. They can also be shared across projects or extended locally.

We don't load every skill at once.

When designing communication with the PIM, integration and architecture skills are most relevant. When defining deletion rules, knowledge of product relationships takes priority. During implementation, the focus shifts to tests and checks at each step. Once a stage is complete, independent review and functional verification become important.

A skill provides guidance on how to perform a task and which context is needed. However, the agent must still verify the system's current state against the actual code and configuration.

Mapping a Large System

In a large monolithic application, a system map is also useful. It connects business areas — such as catalog, pricing, inventory, and orders — with specific modules, code paths, and contracts.

This is a concise navigation index, not comprehensive system documentation. It must be maintained, and the information it points to must be verified against the code.

For a change involving product relationships, the map directs the agent toward existing catalog synchronization processes and product relationship mechanisms instead of having it search the entire application.

The map does not eliminate the need for human input. The team may still need to point out previous changes or relevant dependencies in a particular area, because an AI agent, just like a developer, can overlook them.

For the business, well-organized context can mean better scope control, fewer revisions, and a lower risk of disrupting existing processes.

It does not guarantee a correct implementation. That still requires testing and review.

From Implementation to Verified Requirements

Generating code does not mean the task has been completed correctly. Each stage of work ends with a check of whether the solution meets the agreed requirements, not just whether it works technically.

In our example, it's not enough that the synchronization retrieves and saves product relationships from the PIM. We check whether it preserves manually managed relationships, handles incomplete data correctly, and introduces no unwanted changes when run again — including on a copy of the real product catalog.

Because the criteria are known before work begins, they translate directly into test and acceptance scenarios.

AI can prepare tests and compare the implementation with the specification, but it should not be the only judge of its own work. Independent review and test results catch the discrepancies.

Readiness for review, merging into the main version of the system, and deployment to the live store are three separate decisions. Before deployment, we also agree on how to restore modified relationships, because rolling back the code will not restore deleted data.

What This Article Does Not Cover

Several related topics deserve separate, more detailed coverage: comprehensive test automation, automated enforcement of project rules, CI/CD processes, retry strategies for failed operations, data security, monitoring, and detailed data recovery procedures.

SDD and structured context management help organize requirements, the knowledge provided to AI, and verification activities. However, they do not replace quality engineering or responsibility for the reliability of a production system.

Conclusion

Developing an existing system with AI requires agreed requirements, carefully selected context, and verification of the results.

The specification gives business stakeholders, analysts, developers, and QA teams a shared set of rules. Context layers and a system map help provide AI with the knowledge needed at each stage, while acceptance criteria make it possible to assess whether a change behaves as agreed.

The value of SDD is not simply writing code faster. It is using the speed of AI while retaining control over what is being built and why.