Best Practices & Anti-Patterns
SDD is powerful and easy to overdo. Learn when it's worth the ceremony, when it isn't, and how to avoid the traps
The Honest Truth: SDD Has a Cost
Writing a constitution, a PRD, an architecture doc, and sharded stories before coding is real work. For the right project it pays back many times over. For the wrong one, it's ceremony that slows you down. A good engineer knows which is which.
When SDD Is Worth It
USE SDD WHEN... ✓ The project will live a long time (you'll forget why later) ✓ More than one person (or agent) works on it ✓ "Done" is fuzzy and needs pinning down ✓ Mistakes are expensive (money, safety, compliance) ✓ You need an audit trail (regulated work) ✓ The app is big enough that vibe coding loses the thread
When to Skip It (or Go Light)
SKIP / GO LIGHT WHEN...
✗ A one-off script or throwaway prototype
✗ A tiny, obvious change where "done" is self-evident
✗ You're exploring and don't know what you want yet
(explore by vibe first, THEN spec what you decide to keep)
✗ The whole task is smaller than the spec would beBest Practices That Travel Across Every SDD Method
A spec is heuristics and checkable claims, not a 50-page novel scripting every pixel (Level 8's "right altitude" again). Over-specified is as broken as under-specified.
Approve the brief, the PRD, the architecture, each story. SDD makes the gates obvious - use them. The agent proposes; you decide.
The spec is the product. If it's not in version control with history, you've lost the source of truth.
Sharded stories (BMAD) and atomic specs (LID) both exist because small, tightly-scoped units are where AI does its best work.
SDD reduces intent gaps; it doesn't eliminate your responsibility to read what shipped (Level 7's comprehension debt). Stay the engineer.
Anti-Patterns to Avoid
- Spec theater: writing impressive docs nobody enforces. If your spec doesn't drive the code (or a gate), it's decoration. (LID's CI gate exists precisely to prevent this.)
- Stale specs: the code changed, the spec didn't. Now the "source of truth" lies. Update the spec first, then the code.
- Over-sharding: 200 micro-stories for a tiny app. The overhead eats the benefit. Right-size the pieces.
- Cognitive surrender: trusting the planning docs so much you stop thinking. The docs are your thinking made explicit - not a replacement for it.
- Process for its own sake: using the heaviest method available because it feels professional. The best engineers use the lightest process that still keeps them safe.
How This Level Connects to the Rest
SDD isn't a separate island - it's where the last three levels meet:
Level 7 (Loops) → SDD's gates and CI checks ARE loop verifiers;
each story is a unit you can loop on.
Level 8 (Context) → a good spec / story IS a tight, high-signal
context package for the agent.
Level 9 (SDD) → the discipline that decides WHAT context and
WHICH loop, by pinning down intent first.
Specs, context, and loops are three views of the same craft:
getting an AI to build the right thing, reliably, at scale.Hands-On: Right-Size the Process
Planning before coding pays off on real projects and wastes time on throwaways - match ceremony to stakes
Long-lived, multi-person, fuzzy "done", expensive mistakes, audit needs, or too big for vibe coding
One-off scripts, obvious tiny changes, early exploration, or tasks smaller than their spec
Heuristics and checkable claims at the right altitude - not a pixel-by-pixel novel
Impressive docs nobody enforces; if the spec doesn't drive code or a gate, it's decoration
Code changed but the spec didn't - update intent first, then code, or the "source of truth" lies
The best engineers use the lightest process that still keeps them safe