
Modern web applications almost always consist of multiple modules and services located in different components or repositories, including microservices, common code, configuration per environment, etc. When it comes to AI-assisted development with a multi-component structure, it becomes harder for AI tools to properly understand the system and make changes efficiently and consistently when implementing entire features. From our experience with AI-assisted development, we identified several challenges that are the most impactful and important from our perspective.
A new feature implementation is usually spread across multiple services and repositories. This means that the agent context is “stretched” over multiple code bases. And since context size is limited, the agent may know well only some parts of the feature e.g. in micro service containing business logic, but miss important details about interfaces or functionality in other micro services the current one is communicating with.
The challenge here is to define feature in a way that, on one hand, accurately describes the desired functionality on level of the entire system and, on the other hand, provides as much details as needed for accurate tracking of interactions and dependencies between services.
As implementation switches from one repository to another, we need to transfer the information about the required code changes between the agents or AI sessions. In the simplest case the information might be generated as prompt by one agent session and copied manually into the dedicated chat or session for the next repository. With more advanced approach, the coordinating agent might pass the information about what functionality should be implemented to another agent in Markdown or JSON format. However, the information passed to the agent often contains only the concrete functionality description. So, some important details might be missing on receiving agent’s side as it might need more context about the code it works on.
Regular prompts in a single AI agent chat session lack structure and repeatability. Each time the work on new feature is started, the way we describe the tasks for AI agent may differ. Some important details might be missing from the feature description, the high-level business requirements mixed with technical ones. This might cause more editing of same code to make it work properly, adding new requirements and constraints at different stags of feature development. One of two very similar features might require twice as much effort and reiteration as the other simply because initially some requirements were unclear or missing when put into prompt for AI agent. This effect is also amplified by nondeterministic nature of generative AI making it harder to achieve consistent level of feature implementation quality. So, the consistency in feature definition is important as makes implementation predictable and complete with minimum reiteration.
The implicit API contracts are undocumented API properties defining what data the requests or responses might contain. For example, some field of response object may be missing from real JSON data under a particular condition. The service might work only because it’s not using that field under some implicit condition baked into business logic or basing on other field values, data from other endpoints, etc. Another example is AI agent incorrectly defining the default value for logically empty response data, like empty vs null value for strings, empty JSON object vs null, etc. In this case the API client assuming that, e.g., a particular object’s field should be null breaks when an empty object is returned instead after the code update.
The more system evolves the harder it becomes for AI to keep track of all the reasoning behind the changes made and how the features were implemented. We either need to continuously update the documentation describing feature details or manually provide a portion of that knowledge required by AI in prompt to understand how feature is integrated with other features or how the old feature should be extended as part of the prompt.
There are several AI-related tools and development approaches that help to resolve the challenges above. In this article we’ll focus on Spec-driven development methodology as currently it’s the most advanced tool almost fully addressing the described challenges.
Spec-driven development (SDD) is an AI-assisted software development methodology in which the specification of each feature is defined before implementation, in a form optimized for AI understanding, allowing the AI to implement the feature code based on the spec.
Each feature specification defines:
- High-level spec: user stories, business requirements, expected behavior, and acceptance criteria. This part should answer the “why” and “what” questions about the feature, but not “how”, which relates to the implementation details.
- Technical-level spec: implementation plan, architecture, technologies, technical approach and constraints, system design details. This part should answer the “how” question about the feature implementation.
The spec should be written with the level of details, precision and descriptiveness sufficient for AI coding agents to consistently and reliably generate code based on it.
In SDD the development workflow consists of several steps. Initially, during the setup, once per project, we create a file defining generic development principles, guidelines and constraints the coding AI agent will follow at every stage of development. After the setup, we can proceed with feature development. The common generic steps of SDD are shown in the diagram below:

The files generated by the SDD workflow should be committed to the repository. As the product evolves and features are added, new specifications are created. The set of all features specs describes the functionality of the whole application, capturing both business logic and implementation details.
In practice, SDD is introduced in a software project as an external application or tool built on top of existing well-known coding agents like Claude Code or Copilot. Such tools use agent skills or a different agent types for the SDD steps.
The generic example structure of typical SDD tool data is shown in the diagram below:

Let’s now take a look at how SDD helps to overcome, or at least mitigate, the challenges we identified earlier. We'll describe it in the context of the SDD workflow in general, independently of specific SDD-enabling tools or frameworks.
The specification and plan determine the context boundaries. The AI agent uses them as a primary source for implementation. This enables precise collection of all the information needed to implement the feature without loading the entire system into the agent’s context.
From the practical point of view, to effectively maintain the context:
With SDD the dependencies between components are explicit. In practice, coordination between them is resolved mostly at the decomposition level:
Here is where SDD works best as it ensures repeatability and consistent structure by design:
It's worth mentioning that SDD itself cannot guarantee that the initial specification is fully complete since AI itself is nondeterministic. It also cannot reveal requirements that initially were not included in the spec. It only provides a convenient mechanism to define the specification iteratively and continuously refine it, making it as complete as possible.
The following principles ensure explicit definition of API interactions and coupling:
However, SDD does not provide a mechanism for automatically discovering implicit dependencies or contracts. The AI will still need to infer those from the code if they are not captured in the plan or when the SDD is introduced into an existing project.
Since SDD is based on feature specs, it naturally captures the knowledge about the project. To efficiently ensure knowledge preservation, we should follow certain rules:
Spec-driven development is a powerful methodology for AI-assisted software development. However, like any other approach or technology, it’s not a silver bullet. It has its pros and cons. On the one hand, it adds overhead related to specification management and spec-designing ceremonies. The SDD tools generate spec-related files that need to be reviewed and maintained in addition to the code itself. On the other hand, this enables achieving more consistent, reliable and repeatable results when writing software with AI agents. It’s a good fit for large-scale multi-component applications. When used properly, it helps to resolve many issues caused by the nature of AI agents. Defining a good specification, following the clear rules when designing specs and a consistent approach to applying the development workflow consistently is the key to making AI-assisted development efficient.
https://github.github.io/spec-kit/reference/agentic-sdd.html
https://developer.microsoft.com/blog/spec-driven-development-ai-native-engineering
https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html

Ready to ship? Let's talk.
Read our blog and stay informed about the industry's latest trends and solutions.
Reach out for tailored solutions and expert guidance.