How to Adopt Spec Kit in a Complex Brownfield Microservices Architecture with Multiple Repositories and Teams?

[KamalAlsabah]

Hi everyone,

I'm looking for advice from people who have adopted Spec Kit, or a similar Spec-Driven Development (SDD) approach, in a large, existing brownfield system with multiple repositories, independently deployed microservices, shared libraries, and multiple engineering teams.

I'm particularly interested in real-world experiences, architectural approaches, and lessons learned rather than just the basic Spec Kit workflow.

1. Our Current Architecture

We have an existing application that originally started as a monolith. Over time, we have been migrating parts of it toward a microservices architecture, but the migration is still ongoing.

Our codebase is distributed across several types of repositories:

1. Main Application Repository

• Contains the main application and some modules that are still part of the existing application architecture.
• Includes modules such as CRM, Fleet, Rental, Tracking, and others.
• Contains the API Gateway and other application-level components.

2. Independent Microservice Repositories

Some capabilities have already been extracted into separate repositories and are developed and deployed independently.

Examples include:

• Feedback
• Loyalty
• Customer
• Other independently developed microservices

3. Building Blocks Repository

We also have a shared repository containing reusable libraries and infrastructure components used across multiple services, such as:

• HTTP client building blocks for synchronous communication between microservices.
• Event dispatcher and messaging-related components.
• Redis management.
• Rebus integration.
• Shared permission modules.
• Other common infrastructure and application building blocks.

These repositories are interconnected. A change in one repository can affect other services, shared contracts, infrastructure components, or the overall application behavior.

2. Our Organizational Context

This is not a small project maintained by one developer.

We have a relatively large organization with different teams and responsibilities, including:

• Business teams responsible for business requirements.
• Development teams responsible for implementing features across different repositories.
• Architecture teams responsible for system-wide architectural decisions and standards.
• Other teams involved in testing, integration, and delivery.

Multiple teams work on the same overall product, but they may own different repositories and services.

Our goal is to introduce Spec-Driven Development in a way that works at this organizational scale, rather than simply adding Spec Kit to every repository and letting each team operate independently.

3. What We Want to Achieve

Ideally, we want a workflow in which:

1. Business requirements can be expressed at the system or feature level.
2. The overall system architecture and service responsibilities are documented and discoverable.
3. Feature specifications identify which services, modules, repositories, and contracts are affected.
4. Each repository can have its own detailed specifications, implementation plans, and tasks.
5. Cross-service dependencies and API/event contracts remain consistent.
6. Changes in one repository trigger the necessary impact analysis for dependent repositories.
7. Teams can work independently while still coordinating changes that span multiple services.
8. Architectural decisions and relevant specifications stay up to date as the system evolves.

We also want to avoid an approach that requires manually documenting every detail of the existing system before we can start using Spec Kit.

The system is already large and evolving, so we need a practical way to introduce SDD incrementally.

4. Questions About the Architecture and Workflow

A. Should We Have a Central Repository for System-Level Specifications?

Would it make sense to create a dedicated repository that acts as the central source of truth for system-level specifications and architectural knowledge?

For example, this repository could contain:

• System architecture and service boundaries.
• Responsibilities and ownership of each service and module.
• High-level business capabilities and workflows.
• Dependencies between services and repositories.
• Cross-service feature specifications.
• Shared API and event contract definitions, or references to their authoritative sources.
• Architecture Decision Records (ADRs).
• Integration plans for features that span multiple repositories.

Individual repositories would then contain their own service-level specifications, plans, tasks, and implementation details.

Is this a good pattern for a large brownfield system, or would you recommend a different structure?

How do you distinguish between system-level specifications and repository-level specifications without duplicating information or creating conflicting sources of truth?

B. How Should We Handle Contract-Driven Development Across Repositories?

Suppose we want to implement a feature that affects the Customer microservice, the main application, and a shared Building Blocks library.

The change might involve:

• A business requirement defined at the system level.
• An API contract change in one service.
• A corresponding client or integration change in another repository.
• Changes to shared messaging or infrastructure components.
• Integration tests across the affected services.

How would you organize this workflow with Spec Kit?

Specifically:

• Should API and event contracts live in a dedicated contracts repository, in the owning service repository, or somewhere else?
• How should we distinguish between a contract's authoritative definition and the specifications that describe how different services use it?
• How should dependent repositories discover that a contract has changed?
• How do we coordinate implementation order, compatibility requirements, versioning, and integration testing?
• How should breaking changes be handled when multiple teams cannot deploy their changes simultaneously?

Most importantly, how do we ensure that the overall feature specification remains consistent with the individual service specifications and the actual contracts?

C. How Can We Keep System-Level Specifications Aware of Changes in Individual Repositories?

One of our biggest concerns is keeping the overall architecture and its specifications synchronized as individual repositories evolve.

For example, if a team changes an API, moves a responsibility to another service, or modifies a shared Building Blocks component, how should that change be reflected in the system-level architecture and dependency information?

Would you recommend:

• Explicit links between system-level specifications and repository-level specifications?
• A machine-readable service catalog and dependency map?
• Automated checks in CI/CD to detect contract or architecture inconsistencies?
• A central integration workflow that coordinates changes across repositories?
• Some combination of these approaches?

What should be automated, and what should remain an explicit architectural or team decision?

I'm particularly interested in approaches that avoid duplicating documentation and do not depend entirely on developers remembering to update multiple documents manually.

D. How Should Spec Kit Be Used in a Brownfield System?

This is probably our most important practical question.

We already have a large codebase with existing business rules, architectural decisions, integrations, and historical constraints that are not necessarily documented in one place.

Should we first spend time building comprehensive specifications for the entire existing system before introducing Spec Kit?

Or should we start with new features and document the relevant existing behavior as we go?

For example, would the following incremental approach make sense?

1. Create a lightweight system architecture overview.
2. Identify service boundaries, repository ownership, major dependencies, and important integration points.
3. Introduce Spec Kit for one representative feature.
4. Investigate the existing code and document only the relevant behavior and constraints needed for that feature.
5. Use the specification, plan, and tasks to implement the change.
6. Update the relevant architectural knowledge and contracts when the change introduces durable changes to the system.
7. Gradually expand the approach to other services and teams.

If you have adopted SDD in an existing system, what did your initial onboarding process look like?

How much architectural documentation did you create upfront, and how did you decide what was worth documenting?

E. How Should We Structure the Specifications Themselves?

For a system like ours, what information belongs in each layer?

For example:

• System-level specifications: Business capabilities, cross-service workflows, system-wide requirements, and architectural constraints.
• Service-level specifications: Service responsibilities, business rules, interfaces, dependencies, and local constraints.
• Feature-level specifications: The specific behavior and changes required to deliver a feature.
• Contract specifications: API schemas, event schemas, compatibility rules, and consumer/provider expectations.
• Implementation plans and tasks: The concrete changes required in each affected repository.

Is this separation practical when using Spec Kit, or does it introduce too much process overhead?

How would you map this structure to Spec Kit's existing specify, plan, and tasks workflow?

Also, how do you handle a feature that spans multiple repositories without ending up with several disconnected specifications that each describe only part of the same change?

F. How Should We Introduce This Across Multiple Teams?

Assuming we have a central system-level specification and individual repositories with their own specifications, how should the workflow operate in practice?

For example, should a typical cross-service feature follow a process like this?

1. Business and architecture teams define and clarify the overall requirements.
2. A system-level specification describes the feature and identifies affected services.
3. Each affected repository gets its own implementation specification, plan, and tasks.
4. Teams review the contracts, dependencies, and implementation order.
5. Teams implement their respective changes independently where possible.
6. CI validates repository-level requirements and contracts.
7. Integration testing verifies that the complete feature works across services.
8. The relevant system-level documentation is updated as part of completing the feature.

Would you organize the process differently?

How do you maintain traceability from a business requirement to the system-level specification, individual repository specifications, implementation tasks, pull requests, and integration tests?

And how do you avoid making this workflow too heavyweight for normal development?

5. A Particularly Important Concern: Architecture Awareness for AI Agents

One of our long-term goals is to make AI-assisted development reliable enough that an agent can work on a feature without treating each repository as an isolated project.

For example, if we ask an agent to change authentication from username/email-based login to phone-number-based login, we want it to understand the relevant architecture before proposing changes.

It should be able to identify:

• Which repositories and services are involved.
• Where authentication behavior is implemented.
• Which shared libraries and contracts are relevant.
• Which consumers may be affected.
• Which specifications and tests need to change.
• What implementation order and compatibility constraints apply.
• What additional work is required to keep the overall system consistent.

We do not want to put the entire architecture and every repository's documentation into the agent's context for every task. That would be expensive, difficult to maintain, and potentially counterproductive.

Instead, we want a reliable way to discover the relevant architectural knowledge and dependencies for each feature.

Has anyone combined Spec Kit with a service catalog, architecture documentation, dependency mapping, contract testing, or other mechanisms to achieve this?

What worked well in practice, and what did not?

6. Keeping the Process Practical and Efficient

We are also concerned about the ongoing maintenance cost.

A solution that requires every team to manually maintain multiple layers of documentation for every small change is unlikely to scale.

How do you decide:

• Which architectural information should be maintained centrally?
• Which information should live with the service that owns it?
• Which documents should be generated or validated automatically?
• When should an existing specification be updated?
• How should agents discover relevant context without loading everything?
• How do you prevent specifications from becoming stale or diverging from the implementation?

We want specifications to provide useful, reliable context for both developers and AI agents, not become another documentation system that gradually loses credibility.

7. What I Would Especially Like to Learn From the Community

If you have worked on a similar system, I would really appreciate hearing about your actual experience.

In particular:

1. Your starting point: What did your architecture and repository structure look like before adopting SDD?
2. Your initial approach: What did you implement first, and what did you deliberately postpone?
3. Your specification strategy: Did you use a central repository, repository-local specifications, a dedicated contracts repository, or another approach?
4. Your multi-repository workflow: How did you coordinate a single feature across several services and teams?
5. Your brownfield strategy: Did you document the existing system upfront or build the documentation incrementally?
6. Your automation: What did you automate in CI/CD, contract validation, dependency analysis, and documentation maintenance?
7. Your results: What worked, what failed, and what would you do differently if you were starting again?

Links to real-world examples, public repositories, architectural diagrams, workflow definitions, or write-ups would be especially valuable.

I am not looking for a theoretically perfect architecture. I am trying to find an approach that can evolve with an existing system, support multiple teams, preserve architectural consistency, and make AI-assisted development more reliable without introducing excessive overhead.

If you were starting today with Spec Kit in this kind of environment, what would your recommended architecture and adoption roadmap look like, from the first experiment to a mature, organization-wide workflow?

Thanks!