Spec-Driven Development Is Simpler Than You Thought

Spec-driven development usually arrives as a framework: a sequence of phases, a command for each, templates, a governing document, and the assumption that one developer drives one agent through one repository. Seen that way, it looks like a heavy process to adopt – and for a team with its own tracker, its own roles, and dozens of services, adopting it that way is heavy and often unnecessary.

Under the packaging, SDD is a handful of ideas. My team runs it without a framework. I designed the process around those core ideas; the team adopted it, and five months later it is simply how we work – a team lead, two engineers, a PO/BA and two QA engineers, responsible for 80+ microservices. Agents write every document; people decide, direct each stage, and take responsibility for the result. Two things made it simple: an AI-native meta-repo, where the agent sees the whole system at once, and a triage step that keeps most work away from specifications altogether.

It isn't free. A home-grown process has no community or upgrade path behind it. It fits one team's context rather than every team's, and it leans on the workspace – without one, it becomes considerably heavier.

This piece is the argument, with my team's version as the example. The mechanism, decision by decision, is in RA-005.

SDD is six ideas

Strip away the tooling and what remains is short:

1. Intent is written and agreed before code.
2. What, how, and the steps are separate artefacts – requirements, design, and tasks – each reviewed on its own.
3. Tasks are small enough for a focused agent context, and each one links back to the implementation it supports.
4. The specification lives in the repository the agent reads, versioned alongside the code.
5. Acceptance is checked against the requirements, not against the implementation.
6. When behaviour changes, the specification changes first, on the record.

None of these needs a toolkit. They are practices, and you can build them into a team's process or add them to one that already exists.

A framework is those ideas, packaged for someone else's context

A framework bundles together the same ideas and decisions for its default situation: a fixed phase order, the full artefact set for every feature, its own folder layout, integrations for particular agents, and usually a single repository. Where those assumptions hold, adopting the framework is the cheaper option, and I'd take it.

Where they don't, the team starts adapting to the tool. One-line changes pick up ceremony. Features that span many repositories are split into per-repository specifications. A second planning system appears alongside the tracker the organisation already mandates. That is the weight people associate with SDD – and it belongs to the packaging, not to the ideas.

The workspace pays the context cost once

Most of what makes SDD expensive is context: gathering what the agent needs to know before it can write a sensible requirement, design or task. What matters is that the agent sees the whole system. A monorepo already provides that. For a team whose code is spread across many repositories, an AI-native meta-repo achieves the same result without migrating anything: every repository is cloned into a single tree alongside the team's documentation, rules and skills, so the agent sees the whole system in every session and the context cost is incurred only once.

That changes each stage:

• Requirements come from business documentation, but the agent can check them against the code as it is being written. Obstacles surface while the goal can still move – for example, offering an existing component instead of building a missing one is a common adjustment – and the effort for the whole flow can be estimated at the first stage.
• Design is validated against every service it touches in a single session.
• Tasks link to the exact requirement and design sections they implement, and the implementing agent can open each one.

Without that single view, the same ideas still work, but every step starts with assembling context by hand. That is where most of the heaviness comes from.

Triage keeps the rest light

The other half of the simplicity is not writing specifications. Every piece of work is triaged first:

• a full specification for multi-service features, complex business logic, UI flows, and event pipelines;
• a one-page task for a change within a single service or library;
• a direct fix with no artefacts for a small bug with an obvious cause.

The agent proposes the tier based on a short rubric; a person decides and can overrule it. One rule matters more than the rest:

The tier follows where the engineering happens, not how far the change extends.

A shared-library change that every consuming service then picks up via a version bump is a single design decision and a mechanical rollout – a one-page task, not a specification.

Most work never reaches a specification, and that is the design working rather than the process being skipped. A process that demands a specification for every ticket gets abandoned; triage is what keeps specifications for the work that needs them.

What our version looks like

Briefly – each point has its own section in RA-005:

• Agent-written, human-owned. Nothing in the flow is typed by hand. The agent drafts every artefact – requirements, design, tasks, code, test scenarios, release notes – and a person owns each stage, corrects the draft, and accounts for the result. This is AI-assisted engineering, not delegation.
• A specification is a folder of Markdown files in the workspace: requirements, design, tasks, a changelog, and a README linking to the Epic. Agents read and write to it, so nothing breaks when its layout drifts from the template.
• Each stage runs in its own session. A model that plans, implements and tests in a single session tends to confirm its early mistakes; a fresh session that starts from the files checks them instead. One engineer directing a team of agents can run the whole flow – the separation matters, not the headcount – and each stage can run on the model it needs.
• Requirements and design are edited in place; completed tasks are never edited. Every change is logged, rework appears as new tasks, and the specification remains accurate after release. Release preparation records which parts have reached which environment.
• The tracker preserves intent. Epics remain where management and other teams read them; the decomposition lives in the repository, and the agent reports status.

The change rules are the part that gets tested in production. On one feature, users reported problems on the first working day after release. The team decided to roll back, and within hours a backend hotfix was in production and the affected users' data had been rolled back. The same specification then recorded what had changed – an edit to the requirements, new tasks, a changelog entry – so it still describes what the feature does today and why.

The ideas fit into an existing process

A team doesn't have to replace its SDLC to realise most of this. The ideas can be added one at a time, in an order where each step pays for itself:

1. Triage first. Even without any specifications, a rubric for how much process a change deserves ends the arguments about it.
2. The one-page task. Context, a short plan, acceptance, and verification. Most planned work goes here.
3. Testable acceptance criteria, even without a specification folder. Much of the value of a specification lies in this one habit.
4. One real specification for a feature that genuinely spans services.
5. Rules and skills last. They make a working process repeatable; they can't invent it.

Whichever step a team is on, the files belong in the repository the agent reads – that is when the agent starts using them rather than guessing. The example repository includes a template for each step. It is a starting point to reshape, not a standard to copy.

Simpler than it looks

SDD can feel heavy when it arrives as someone else's framework. As a set of ideas, it is small enough to build a team's own process from scratch, or to fit into the one it already has. What made it simple for my team was not a tool: an agent that can see the whole system, a triage step that keeps specifications for the work that needs them, and people who own every stage while the agents write.

The full architecture, with the trade-offs next to each decision, is RA-005. The workspace it runs on is RA-003.