Enterprise Spec-Driven Development: Templates, Workflow & Governance

[vishalgb1]

Hi everyone,

Our team has recently started exploring Spec-Driven Development (SDD), and we are trying to understand the best way to structure our delivery workflow and architecture using SDD principles.

Our current system architecture includes:

• React web application (frontend)
• Backend APIs/services
• Database layer
• Shared/common libraries used across services

We want to move towards a spec-first approach where requirements, architecture, APIs, workflows, validations, and implementation tasks are driven from structured specifications rather than starting directly from coding.

I would appreciate guidance from teams already using SDD in real-world enterprise projects.

Some questions we currently have:

1. Specification Structure
   How do you usually structure specifications for a multi-layered system involving:

• frontend/UI
• APIs/services
• database/schema
• shared libraries
• integrations

Do you typically maintain:

• one master system specification,
• separate specifications per module/service,
• or layered specifications (business, technical, implementation)?

2. Templates & Standards
   Do you recommend:

• one common template across all components,
• or component-specific templates for frontend/backend/database layers?

Is it a good practice to have:

• a base/common specification template,
• extended with technology-specific sections where required?

3. Contracts & Versioning
   How do you handle:

• API contracts
• database migrations
• shared DTOs/models
• cross-service dependencies
• specification versioning and change management

4. Recommended SDD Workflow
   What does the end-to-end workflow typically look like in mature SDD implementations?

For example:
Requirements → Architecture/Design Specs → API/Data Contracts → Task Generation → Implementation → Validation/Test → Review

5. Governance & Traceability
   How do you maintain traceability between:

• business requirements,
• technical specifications,
• implementation tasks,
• test cases,
• and deployed functionality?

6. Keeping Implementation Aligned
   How do you ensure developers and AI coding agents remain aligned with specifications and avoid implementation drift over time?

7. Enterprise Best Practices
   Are there any recommended:

• repository structures,
• specification folder structures,
• governance practices,
• templates,
• or reference repositories
  that work well for enterprise-scale SDD adoption?

8. AI/Agentic Workflow Integration
   Has anyone successfully integrated SDD with:

• LangGraph
• MCP
• BPMN/process flows
• Azure/AWS pipelines
• multi-agent orchestration

We are trying to establish strong foundations before scaling this approach across the team, so any practical advice, lessons learned, or reference implementations would be extremely helpful.

Thanks in advance!

[thlandgraf]

Full disclosure up front: I'm the creator of a VS Code extension called SPECLAN that does pretty much exactly this, so apply the appropriate salt to the tool mention at the end. Most of what follows is tool-independent and is what I'd tell you regardless.

The single decision that makes or breaks enterprise SDD is anchoring entity identity in an ID in the frontmatter, not in the title or the file path. Once id: F-2419 is the canonical reference, renames are free, files can move between layers, and cross-layer traceability (business requirement -> API contract -> task -> test) becomes a mechanical lookup instead of a fragile web of paths that rot the first time someone reorganizes a folder. Most enterprise SDD efforts I've seen fail, fail here first.

On structure (your Q1 and Q7): master-spec vs per-module is a false choice. What scales is a hierarchy, not a layering. Business goals at the top, features decomposing into a tree of sub-features, requirements as the leaf - the small, testable, traceable unit an agent or developer actually implements. The architectural layer (frontend / API / db / shared lib) is a property of a requirement, not its own spec silo. One file per entity, in a directory tree that mirrors the hierarchy, each file Markdown with a YAML frontmatter header (id, type, parent, status, layer, depends_on). That gives you git as the audit trail for free, which covers most of Q5.

Drift (Q6) is the hard one, and it's a gate problem, not a process problem. Give every spec a status field with a lifecycle (draft -> review -> approved -> in-development -> under-test -> released -> deprecated). The AI agent is only allowed to implement entities in approved. A change to an approved spec doesn't edit it in place - it opens a Change Request entity that references the original by ID, carries its own review cycle, and on merge archives itself and updates the spec. That one primitive answers your versioning (Q3), change management (Q3), governance (Q5), and drift (Q6) questions together, instead of as four separate processes.

Templates (Q2): one base template per entity type, extended with type-specific sections, keyed off entity type and not the tech layer. A frontend requirement and an API requirement share most of their shape.

Agentic integration (Q8): the part that actually holds up is exposing the spec tree to the agents over MCP, so the agent asks "what requirement am I implementing and what are its acceptance criteria" as a tool call rather than being handed a prompt dump that goes stale. Prompted CLAUDE.md-style sync drifts; mechanical tool-call sync doesn't.

SPECLAN (the extension I mentioned) implements this whole stack - the hierarchical tree, frontmatter IDs, the status lifecycle, the Change Request entity, an MCP server over the spec tree - so if you'd rather look at a concrete reference implementation than build the conventions from scratch: https://speclan.net . Happy to go deeper on any of the eight. The drift/CR piece is the one I'd prioritize getting right before scaling anything else.