Scaling Spec-Driven Development Across Teams
When one developer works alone, spec-driven development is straightforward: write a spec, generate code, verify it works. When a team of five, ten, or fifty engineers works together, things get complex. Multiple engineers might work on the same spec simultaneously. Specs might conflict with each other (Team A's API contradicts Team B's expected data format). Review and approval workflows need structure. This article covers governance, tooling, and processes that enable spec-driven development to scale across large teams.
Governance: The Spec Hierarchy
As projects grow, specs need a hierarchy. Not all specs are created equal. Some are foundational (core data models), others are dependent (feature-specific APIs).
Governance Hierarchy:
Level 1: Platform Specs (Shared across entire organization)
├── Common Data Models (User, Organization, Workspace)
├── Authentication & Authorization Model
├── API Versioning Strategy
├── Error Code Standard
└── Logging & Observability Standard
Level 2: System Specs (Owned by one team, used by others)
├── User Service Spec
├── Payment Service Spec
├── Notification Service Spec
└── Analytics Service Spec
Level 3: Feature Specs (Owned by feature team)
├── User Profile API
├── Account Recovery Flow
├── Password Reset
└── Email Preferences
For each spec, define:
- Owner: Which team/person is responsible?
- Reviewers: Who must approve changes? (usually 2–3 senior engineers)
- Status: Draft, Review, Approved, Deprecated
- Version: Semantic versioning (1.0.0, 1.1.0, 2.0.0)
- Breaking changes: What code/clients must change if this spec is adopted?
Spec Change Management Workflow
When a team proposes a spec change, follow a formal process:
1. Proposal (Author)
└─ Create detailed spec change request (SPEC-CHANGE-123)
├─ Current spec (if modifying)
├─ Proposed changes (diffs highlighted)
├─ Rationale (why this change)
├─ Impact analysis (which teams/code are affected?)
└─ Breaking changes (if any)
2. Initial Review (Reviewers)
└─ Read spec, ask clarifying questions
├─ Syntax/format issues
├─ Contradictions with other specs
├─ Unclear requirements
└─ Suggested improvements
3. Revision (Author)
└─ Address reviewer feedback
├─ Update spec based on questions
├─ Add examples if needed
├─ Document rationale for design decisions
4. Approval (Stakeholder Review)
└─ Team leads/architects sign off
├─ Verify no team is negatively impacted
├─ Confirm compatibility with platform specs
└─ Schedule implementation if breaking
5. Communication (Author)
└─ Notify affected teams
├─ Send change summary to Slack/email
├─ Provide migration guide for breaking changes
├─ Timeline: when does this become live?
6. Implementation & Rollout
└─ Teams implement per new spec
├─ Generate code from updated spec
├─ Run spec-derived tests
├─ Deploy when ready (stagger if breaking)
Formal process prevents chaos. Without it, teams might implement conflicting specs, or one team's change breaks another's code.
Shared Spec Repository Structure
Organize specs in a git repository with clear structure:
specs/
├── platform/
│ ├── authentication.yaml
│ ├── data-models.yaml
│ ├── error-codes.yaml
│ ├── api-versioning.yaml
│ └── logging.yaml
├── services/
│ ├── user-service/
│ │ ├── spec.yaml (core APIs)
│ │ ├── spec-v2.yaml (deprecated, for reference)
│ │ ├── test-vectors.json (edge cases)
│ │ └── OWNERS (who approves changes)
│ ├── payment-service/
│ │ ├── spec.yaml
│ │ ├── test-vectors.json
│ │ └── OWNERS
│ └── notification-service/
│ ├── spec.yaml
│ └── OWNERS
├── features/
│ ├── user-profiles/
│ │ ├── api-spec.yaml
│ │ └── data-model.yaml
│ └── account-recovery/
│ ├── workflow-spec.yaml
│ └── api-endpoints.yaml
├── GOVERNANCE.md (process, review rules, change management)
└── README.md (how to use this repo, conventions)
Use branches for spec proposals:
Main branch: Production-approved specs (stable)
├── feature/user-profiles-v2 (spec under review)
├── bugfix/payment-spec-rate-limits (minor fix)
└── experimental/graphql-support (exploration)
Pull requests require:
- 2 approvals from OWNERS
- All CI checks passing (spec syntax validation)
- At least 3 days of review time
Coordination Across Teams
When one team's spec depends on another's, coordinate explicitly:
Example: Order Service depends on Payment Service
Timeline:
- Week 1: Payment Service team finalizes payment spec (PAYMENT-SPEC-v2.0)
└─ Publishes with 2-week lead time
- Week 2: Order Service team reads payment spec
└─ Submits questions/clarifications (async design review)
- Week 3: Payment Service clarifies, Order Service finalizes order spec
└─ Includes dependency: "requires PAYMENT-SPEC-v2.0"
- Week 4: Both teams generate code from respective specs
└─ Integration tests verify order/payment interaction
- Week 5: Deploy Payment Service (backward compatible)
- Week 6: Deploy Order Service
Key: Dependencies must be explicit and versioned. Never assume an API won't change.
Review Processes for Large Teams
Scale code review to multiple teams:
Review Process 1: Core Platform Specs
These affect everyone. Multiple rounds of review:
Platform Spec Review (e.g., error-codes.yaml)
Stakeholders:
├── API Guild (senior architects) - 2 approvals required
├── Security Team - 1 approval (if security-related)
├── Ops Team - 1 approval (if infrastructure-related)
└── Compliance Officer - 1 approval (if regulated)
Timeline: 2 weeks minimum
Scope: Ecosystem-wide impact
Question to ask: "Will this spec change break any existing systems?"
Review Process 2: Service Specs
Service-level specs are owned by one team but reviewed by dependent teams:
Service Spec Review (e.g., payment-service/spec.yaml)
Stakeholders:
├── Payment Service team (owners) - author
├── Order Service team - 1 approval (we depend on this)
├── Billing Service team - 1 approval (we depend on this)
└── Tech Lead of Payment Service - 1 approval
Timeline: 1 week typical
Scope: This service + direct consumers
Question to ask: "Does this change break our integration?"
Review Process 3: Feature Specs
Feature specs are typically reviewed only by the feature team, but shared widely:
Feature Spec Review (e.g., user-profiles/spec.yaml)
Stakeholders:
├── Feature team (owners) - author + 1 approval
├── Product Manager - 1 approval (requirements)
└── Tech Lead - 1 approval (architecture)
Timeline: 3 days typical
Scope: This feature only
Question to ask: "Does this spec match requirements and architecture?"
Tooling to Support Scaled Specs
As teams grow, manual tracking breaks down. Use tools:
Tool 1: Spec Repository with CI
# .github/workflows/spec-validation.yml
name: Spec Validation
on: [pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Validate YAML syntax
run: python validate_specs.py
- name: Check for breaking changes
run: python check_breaking_changes.py
- name: Validate against platform standards
run: python check_platform_compliance.py
- name: Generate schema documentation
run: python generate_docs.py
- name: Run example code generation
run: python test_codegen.py
This ensures broken specs never merge to main.
Tool 2: Spec Dependency Graph
Track which services depend on which specs:
# build_dependency_graph.py
import json
import os
deps = {}
for service_dir in os.listdir("services"):
spec_file = f"services/{service_dir}/spec.yaml"
spec = load_yaml(spec_file)
dependencies = spec.get("dependencies", {})
deps[service_dir] = dependencies
# Output: service dependency graph
print(json.dumps(deps, indent=2))
When a spec changes, this tool shows which services are affected.
Tool 3: Spec Change Tracker
Track all spec changes in a spreadsheet or database:
Spec Change Tracker:
| Change ID | Service | Change | Status | Author | Approvers | Deploy Date |
|-----------|---------|--------|--------|--------|-----------|-------------|
| SC-001 | payment-service | Add rate limiting | Approved | Alice | Bob, Carol | 2026-06-15 |
| SC-002 | user-service | User.email max length 254 | Review | Dan | (waiting) | TBD |
| SC-003 | notification | SMS support | Draft | Eve | (none) | TBD |
This centralizes visibility into what's changing and when.
Communication Strategy
Keep teams informed about spec changes:
Spec Change Notification (Email Template)
Subject: SPEC CHANGE ALERT: payment-service v2.1.0
Dear Teams,
A breaking change to the Payment Service spec is being deployed on 2026-06-15.
WHAT IS CHANGING:
- Rate limit: 100 requests/min per account (was 1000)
- Error response: now includes retry_after_seconds field
AFFECTED TEAMS:
- Order Service (AFFECTED - you call payment APIs)
- Billing Service (AFFECTED - you call payment APIs)
- Analytics Service (NOT affected)
ACTION REQUIRED (by 2026-06-10):
1. Review: https://github.com/org/specs/pull/42
2. Test: Re-run integration tests with new spec
3. Deploy: Update your code and deploy by 2026-06-15
MIGRATION GUIDE:
https://specs.example.com/payment/v2.1.0/migration-guide
QUESTIONS:
Post in #spec-changes Slack channel
Comparison Table: Team Scales
| Scale | Governance | Review | Tools | Coordination |
|---|---|---|---|---|
| 1 dev | Informal | Self-review | Git | N/A |
| 1 team (5–10) | Light (OWNERS file) | 1 approval | Git, CI | Slack |
| 2–3 teams | Formal (hierarchy) | 2–3 approvals | Git, CI, tracker | Weekly sync |
| 10+ teams | Strict (platform levels) | Multiple gates | Git, CI, tracker, dependency graph | Spec committee |
Key Takeaways
- Spec governance requires a clear hierarchy: platform specs (org-wide), service specs (team-owned, widely-used), feature specs (feature-specific).
- Spec change management workflows prevent conflicting changes and ensure stakeholders review before adoption.
- A shared spec repository with CI/validation ensures specs are always syntactically correct and platform-compliant.
- Dependency tracking shows which teams are affected by spec changes.
- Communication is critical: notify teams early and provide migration guides for breaking changes.
Frequently Asked Questions
How do we handle spec disagreements between teams?
Schedule a design review with both teams and a neutral tech lead. Document the decision and rationale in the spec. Disagreements often indicate ambiguity; resolve it in the spec.
What if a team ignores a spec change?
Identify why: did they not see it? Disagree? Lack capacity? Address the root cause. If they refuse to comply, escalate to leadership. Spec-driven development only works if teams honor specs.
Can we version individual fields or just whole specs?
Best practice: version entire specs. Field-level versioning is complex and error-prone. If a field is being removed or changed significantly, bump the spec version and provide a migration path.
How do we handle experimental specs that aren't approved?
Use branches or a separate experimental directory. Mark them clearly (e.g., "DRAFT: Not for production use"). Never merge unreviewed specs to main.