Spec driven development in an enterprise is a different game

What is spec driven development

Spec driven development (SDD) is simple. Before you let an AI coding agent build anything, you write down exactly what you want it to build. You don't just open Claude Code and type "add notification preferences." You first write a spec that covers what the feature does, how it should behave, and what counts as done. Then you figure out the technical approach: which service, which database, which APIs. Then you break that into small tasks the agent can pick up one at a time.

Why bother? Because agents are good at writing code but bad at making decisions. If you tell an agent "add user preferences," it'll build something. But it might create a new database table when one already exists, or call a service directly when it should go through a queue, or follow a pattern from the wrong part of the codebase. SDD means the human makes the decisions and the agent does the building.

Why it works great for a solo developer

When one developer owns the whole codebase, writing a spec is natural. The preferences table, the SMS provider, the switch to gRPC last quarter: all of that goes in from memory. The spec is accurate because the person writing it already knows the system.

Now try it with a team

Take the same feature in an enterprise with 40 services. The PM writes the PRD, but doesn't know notification preferences already live in a separate microservice, or that SMS was migrated to a new provider. Their job is customers and roadmap, not reading service code. The developer writes a plan based on the PRD, but they've been on the team four months and have never touched the notification service. So the plan says: add a preferences field to the User model, create a PreferencesController. The agent builds exactly that. Clean code, passes the tests, architecturally wrong.

The spec was the problem, not the agent. This happens every time a spec is written by someone who doesn't have the full picture. In an enterprise, nobody has the full picture.

The five problems with SDD in a team

1. Specs are written blind. The PM has no way to query how the system actually works. So the PRD describes a feature as if it's being built from scratch, without knowing what already exists, which service owns what, or what the right integration pattern is. The agent builds exactly what the spec says. The spec is wrong.

2. You can't change one section safely. The spec is one document where every section makes assumptions about the others. Change how SMS works and you might break an assumption in the email section. Nobody re-reads 40 pages to check. In practice, specs stop getting updated, and agents build from something stale.

3. One spec, three agents. Different parts of the feature go to different developers. Each agent gets the full document. The parts it doesn't need are noise that degrades its output.

4. Nobody outside engineering has visibility. The PM hands off the PRD and finds out what's done, what's blocked, and what changed at the next standup. There's no way to check without asking a developer.

5. Specs drift across repos. Your feature touches frontend and backend: two repos, two SPEC.md files. An update in one doesn't propagate to the other. By the time you notice, the specs and the code contradict each other.

A frontend developer updates their spec to change the UI flow. Pushes it. The backend developer doesn't see it. The backend developer updates their spec to change the API contract. Pushes it. The frontend spec doesn't know. Agents are shipping changes every hour. By lunchtime:

Be honest: you've seen this happen. Maybe not with SPEC.md files specifically, but with any shared understanding that lives in two places. Now imagine it with 50 repos. Or 200. Every SPEC.md is an island. There's no mechanism to keep them in sync because they don't know about each other. The whole point of SDD is that the spec is the source of truth. When that "source of truth" is scattered across hundreds of repos and contradicting itself, it's not one anymore.

How to fix it

The SDD approach is right. Plan before you build, be specific, don't let the agent guess. That doesn't change. What changes is how you handle the five problems above.

Connect the spec to the codebase. The PM should be able to ask "how does our notification system work today?" and get an answer from the actual code, in plain language. Not a Confluence page, not a Slack thread. The real current state: which service owns preferences, what the data model looks like, which providers are integrated. When the PRD is based on how the system actually works, the developer's plan is based on reality instead of assumptions.

Break the spec into small, trackable requirements. Instead of one big SPEC.md, split the feature into workstreams ("email preferences," "SMS preferences," "push preferences"). Each workstream has its own requirements with acceptance criteria. You can update the SMS requirements without touching email. You can see which requirements are done, which are in progress, and which haven't started. When the spec needs to change, you change the specific requirement, not the whole document.

Give each agent just the requirements it needs. When three developers are building three workstreams in parallel, each agent should only see the requirements for its workstream, not the entire feature spec. The agent grabs its specific requirements via MCP (Model Context Protocol), builds them, and marks them done. Focused context means better output. An agent working on email preferences doesn't need to know anything about SMS.

Make progress visible to everyone. When an agent marks a requirement as done, the PM sees it. When a workstream is blocked, the EM sees it. Nobody has to ask for a status update or wait for the next standup. The spec, the implementation, and the progress are all in the same system.

Keep one spec, not one per repo. The spec should live outside the repos it describes. One set of requirements for the feature, regardless of how many services it touches. When a requirement changes, it changes once, and every agent working on any part of the feature sees the same thing. No more frontend spec saying one thing and backend spec saying another. The spec is the single source of truth, and it actually behaves like one.

SDD works. Plan before you build, be specific, don't let the agent guess. That's even more important when agents are doing the building. But most SDD guides assume one developer with one repo. In an enterprise, planning starts with a PRD not a spec, specs span multiple repos, and the people defining the feature don't have time to dig through every service. You need the spec connected to the code, living in one place regardless of how many services it touches, broken into pieces small enough to manage, and feeding requirements directly to your agents.