About us
Services

Capabilities

Cloud
Legacy Modernization
Data Platforms
AI & Advanced Analytics
Agentic AI

Industries

Automotive
Finance
Manufacturing
Aviation
Looking for something else?

Contact us for tailored solutions and expert guidance.

Contact
Products

Cloudboostr

Platform

Sovereign AI

Sovereign Cloud

Virtualization

Implementation & support

Databoostr

Use cases

Data monetization

Data regulatory compliance

Fleet management

Industry

Manufacturing

Automotive

Material Handling

Aiboostr

Product

Products

Products

Databoostr

Data Sharing & Monetization Platform

Cloudboostr

Open Cloud Foundation for intelligent workloads

Aiboostr

AI Orchestration & Governance Platform

Use cases

Data monetization

Data regulatory compliance

Fleet management

Industry

Manufacturing

Automotive

Material Handling

Platform

Sovereign AI

Sovereign Cloud

Virtualization

Implementation & support

Product

AI Orchestration

Private AI

EU AI Act

Case studies
Resources

Resources

Blog

Read our blog and stay informed about the industry’s latest trends and technology.

Ready to find your breaking point?

Stay updated with our newsletter.

Subscribe

Insights

Ebooks

Explore our resources and learn about building modern software solutions from experts and practitioners.

Read more
Careers
Contact
Blog
AI
Software development

Spec-driven development: Scaling AI-assisted coding across microservices

Andrii Biehunov
Expert Software Engineer
November 19, 2026
•
5 min read

Table of contents

Heading 2
Heading 3
Heading 4
Heading 5
Heading 6

Schedule a consultation with software experts

Contact us

Why AI coding agents struggle with multi-repository projects

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.

5 Challenges of AI-Assisted Development in Large-Scale Systems

1. Maintaining AI Context Across Components and Repositories

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.

2. Cross-Component and Cross-Repository Coordination

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.

3. Inconsistent Feature Definitions for AI Agents

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.

4. Implicit API Contracts and Hidden Coupling

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.

5. Losing Knowledge as Software Evolves

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.

What Is Spec-Driven Development (SDD)?

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.

What a Feature Specification Contains

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.

The Spec-Driven Development Workflow

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.

SDD Tools and Repository Structure

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:

How spec-driven development solves AI-assisted development challenges

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.

1. Keeping AI Context Consistent Across Repositories

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:

  • All the feature-related files: spec, plan and tasks should be kept in a separate repository that is accessible for every agent working on the project at any point of development. These files are a source of truth for the agents.
  • The feature spec created in the Specify step should define the feature on the system level only, without technical implementation details. The spec should be as clear as possible but also not too specific.
  • The plan files created in the Plan step are split into several parts, one per affected service. Reference the relevant existing code or docs instead of copying them.
  • Since the context is captured in spec and plan, at any point we may start a new AI chat session – one for the whole feature, per task or in the middle of a task implementation.
2. Coordinating AI Agents Across Components and Repositories

With SDD the dependencies between components are explicit. In practice, coordination between them is resolved mostly at the decomposition level:

  • Each task created in the Decomposition step should clearly specify the target repository or component, dependencies on other tasks and its completion criteria.
  • The tasks have a predefined order so that shared parts like API schemas or events are implemented first, followed by the dependent components one by one through the dependency tree.
  • Those tasks that can run in parallel are clearly marked accordingly in the generated task definitions.
  • As tasks describe fine-grained units of implementation, they replace prompt transferring between agents.
  • The agent may mark tasks as done in the tasks file to keep track of the work.
3. Standardizing Feature Definitions with Specs

Here is where SDD works best as it ensures repeatability and consistent structure by design:

  • For every feature the AI agent uses the generic project development principles and guidelines defined once during the SDD tool setup. All the steps from Specify to Implementation are based on these principles.
  • The predefined sequence of steps in the feature implementation process along with reiteration on each step makes the spec structure consistent.
  • The Verify step makes it easy to identify gaps in implementation and fix them through iterative refinements.

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.

4. Making Implicit API Contracts Explicit

The following principles ensure explicit definition of API interactions and coupling:

  • The feature implementation plan is the natural place where the API contracts and coupling between components should be described. Some SDD tools, like GitHub SpecKit, even have a separate directory storing the API contracts created during the Plan step.
  • The generic project development principles should require the agent to document every consumed or exposed API contract in the plan, including optional fields, null vs empty values, default values, etc.
  • In the Plan phase, we may ask the agent to analyze the existing code and find the implicit dependencies related to the new feature being implemented.
  • When an implicit dependency is discovered during the implementation, the AI should be prompted to add it to the spec or plan, so it becomes explicit for other features.

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.

5. Preserving Project Knowledge in Version-Controlled Specs

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:

  • All feature requirements are stored in a version control repository since they serve as a source of knowledge about the current application state and behavior.
  • Spec and plan files are treated as part of the definition of done: a feature is complete only when its specification fully reflects its behavior.
  • When new changes are needed in an existing feature, the prompt used in the Specify step should refer to the existing feature spec. The agent may either update an existing spec or add a new spec containing only the changes required by the feature update, referencing the original spec.
  • In the Verification step, the AI agent should be prompted to compare the spec with the code. If there are any differences, after we review them, the agent should update the spec.

Spec-driven development: Benefits, trade-offs and when to use it

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.

Further reading on spec-driven development

https://github.github.io/spec-kit/reference/agentic-sdd.html

https://speckit.org/

https://developer.microsoft.com/blog/spec-driven-development-ai-native-engineering

https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html

‍

Grape Up guides enterprises on their data-driven transformation journey

Ready to ship? Let's talk.

Check our offer
Blog

Check related articles

Read our blog and stay informed about the industry's latest trends and solutions.

No items found.
View all
Connect

Interested in our services?

Reach out for tailored solutions and expert guidance.

Stay updated with our newsletter

Subscribe for fresh insights and industry analysis.

About UsCase studiesContactCareers
Capabilities:
CloudLegacy ModernizationData PlatformsAI & Advanced AnalyticsAgentic AI
Industries:
AutomotiveFinanceManufacturingAviation
Solutions:
DataboostrCloudboostrAiboostr
Resources
BlogInsights
© Grape Up 2025
Cookies PolicyPrivacy PolicyTerms of use
Grape Up uses cookies

This website uses cookies to improve its user experience and provide personalized content for you. We use cookies for web analytics and advertising. You can accept these cookies by clicking "OK" or go to Details in order to manage your cookies preferences more precisely. To learn more, check out our Privacy and Cookies Policy

Accept allDetails
Grape Up uses cookies

Essential website cookies are necessary to provide you with services available through the website, autosave your settings and preferences, and to enhance the performance and security of the website - you have the right not to accept them through your web browser's settings, but your access to some functionality and areas of our website may be restricted.

Analytics cookies: (our own and third-party : Google, HotJar) – you can accept these cookies below:

Marketing cookies (third-party cookies: Hubspot, Facebook, LinkedIn) – you can accept these cookies below:

Ok