SDD in Teams: Spec Versioning, Onboarding, Code Review

SDD golang team collaboration is a different challenge from solo SDD. Done individually, SDD is relatively straightforward: you write the spec, you implement, you review your own work. On a team the question becomes how to ensure every member follows the same process, the spec stays up to date, and Claude Code is used consistently.

In this article we cover the concrete practices that make SDD work at team scale: spec versioning, onboarding new developers, and code review that focuses on spec compliance.

18.1 Spec Versioning Beyond Git

Git versions your spec automatically, but a git log alone can’t tell you why a change happened. The changelog below lives inside the spec itself and records the decision context that git commits omit.

 1## Changelog
 2
 3### v1.3 (2025-07-01)
 4**Changed:**
 5- AC4: Cancellation window changed 15 → 30 minutes
 6  Reason: User research showed 15 min was insufficient
 7  Decision maker: @budi (Product) + @andi (Tech)
 8  Consumers notified: 2025-06-28
 9
10### v1.2 (2025-06-15)
11**Added:**
12- EC3: Explicit DB timeout handling
13  Background: Found in load testing (JIRA-456)

The value this adds over git log is the narrative: who decided, why, and who was notified. Six months later, when someone asks why the window is 30 minutes, the answer lives in the spec instead of in a forgotten Slack thread.

18.2 Spec Status Lifecycle

A spec is not a binary “done or not” — it moves through defined states, and everyone needs to know which one it’s in. The lifecycle below shows the states a spec passes through and how to record the current one in its header.

1Lifecycle:
2DRAFT → REVIEW → APPROVED → ACTIVE → DEPRECATED → ARCHIVED
3
4In the spec header:
5## Status: APPROVED
6**Approved by:** @budi (Tech Lead), @maya (Product Manager)
7**Approval date:** 2025-07-01
8**Target implementation:** Sprint 23

Making status explicit prevents the most common team mistake: implementing against a DRAFT spec that still might change. A reviewer’s first check becomes trivial — is this spec APPROVED? — and the answer is right there in the header.

18.3 Spec Governance

With multiple people able to edit specs, you need clear roles and review requirements. The governance block below defines who authors, reviews, and approves, and how much scrutiny each kind of change demands.

 1## Roles
 2**Spec Author:** Developer writing the spec (usually the implementer)
 3**Spec Reviewer:** Tech lead + 1 senior developer
 4**Spec Approver:** Tech lead (tech spec) + PM (business spec)
 5
 6## Review Requirements
 7- New spec: minimum 2 reviewers (1 tech, 1 business)
 8- Minor changes (typo, clarification): 1 reviewer
 9- Major changes (behavior, breaking): all reviewers required
10
11## Timeline
12- 48-hour minimum review window before approval

The tiered requirements are what keep governance from becoming a bottleneck: a typo needs one reviewer, a breaking change needs everyone. Scaling scrutiny to impact means the process protects the risky changes without slowing the trivial ones.

18.4 Onboarding New Developers to SDD

New developers don’t learn SDD from a lecture — they learn it by reading real specs and tracing them to code. The onboarding kit below sequences that learning across the first two weeks.

 1## Onboarding Kit
 2
 3### Day 1-2: Understand Spec
 4Read in order:
 51. specs/_templates/feature-spec.md → the template used
 62. specs/order/create-order.md → a complete spec example
 73. specs/order/cancel-order.md → a production spec example
 8
 9For each spec, trace to its implementation:
10→ specs/order/cancel-order.md → internal/usecase/order/cancel_order.go
11
12### Day 3: Understand CLAUDE.md
13Read the root CLAUDE.md. Run probe tests from the onboarding guide.
14
15### Day 4-5: Shadow Review
16Join a code review with an experienced SDD developer. Watch the spec compliance checks.
17
18### Week 2: First Spec
19Pick a small task from the backlog. Write the spec. Get it reviewed. Implement.

The design principle here is “read spec, find implementation” before “write spec”: a newcomer internalizes the spec-to-code link by tracing existing features first. A hands-on first-spec exercise then cements the whole workflow far better than any formal training.

To make the first-spec step concrete, give the new developer a small, self-contained feature to specify and build. The exercise below is a good starter because it exercises the full workflow without deep domain knowledge.

1## Exercise: Get Order by Order Number
2
3Implement: GET /api/v1/orders/number/{order_number}
4
5Steps:
61. Write the spec at specs/order/get-order-by-number.md
72. Get spec review from a senior
83. After approval: Plan Mode → Task Breakdown → Implementation → Tests → PR

Because this endpoint is simple, the newcomer’s attention stays on the process — spec, review, plan, implement, test — rather than on business complexity. That is exactly what onboarding should teach first.

18.5 Team-Edition CLAUDE.md

A shared CLAUDE.md carries more than architecture rules — it encodes the team’s process and current work. The example below shows the team-specific sections that make Claude Code behave consistently for everyone.

 1# CLAUDE.md — Santekno Shop (Team Edition)
 2
 3## Spec Process
 4Every new feature MUST:
 51. Have a spec at specs/domain/[feature].md
 62. Be reviewed (label: spec-review on PR)
 73. Get approval BEFORE implementation starts
 84. Reference the spec in every PR
 9
10## Team Conventions
11Timezone: WIB (Asia/Jakarta, UTC+7) — all event timestamps in UTC
12PR minimum: 1 approver (tech lead required for arch/security changes)
13Branching: feature/{ticket}-{description}
14
15## Current Active Specs (Sprint 23)
16- specs/order/cancel-order.md v1.3 (assignee: @andi)
17- specs/product/update-stock.md v1.0 (assignee: @citra)

The “Current Active Specs” section is what makes this a living document rather than a static config: it tells Claude Code — and every developer — exactly what is in flight this sprint. Keep it current and new sessions start with real context instead of guesswork.

18.6 Spec-First Code Review Guide

Code review on an SDD team has an extra dimension: does the code match the spec? The guide below gives reviewers a repeatable sequence that checks spec compliance before code quality.

 1## SDD Code Review Steps
 2
 3### Step 1: Verify Spec Link (30 seconds)
 4- Does the PR description link to a spec?
 5- Correct spec version?
 6- Spec status: APPROVED?
 7
 8### Step 2: Spec Compliance (5-10 minutes)
 9- Spec in one window, code in another
10- Each AC → implemented?
11- HTTP status codes match spec?
12- Error codes exact match?
13
14### Step 3: Test Coverage (5 minutes)
15- Each AC has a test?
16- High-priority ECs have tests?
17- Test names reference AC/EC?
18
19### Step 4: Standard Code Review (15-20 minutes)
20- Go idioms, error handling, performance, security

Ordering matters: checking spec compliance before code style prevents the classic waste of polishing code that implements the wrong behavior. To keep review comments consistent, standardize the language reviewers use for the most common situations.

1Spec compliance issue:
2"Spec [cancel-order.md v1.3 AC9] says error_code should be 'ORDER_NOT_CANCELLABLE',
3but the code uses 'NOT_CANCELLABLE'. Please align."
4
5Acknowledgment:
6"All ACs and ECs covered. Spec compliance check: PASSED. Moving to code quality."

Templated comments do two things: they cite the exact spec clause so the discussion is about the spec, not opinion, and they make the review feel consistent no matter who performs it.

18.7 PR Template for SDD

The PR template is where spec discipline becomes visible on every change. The template below asks the author to self-review against the spec before a reviewer ever looks.

 1## Spec Reference
 2- **Spec file:** specs/order/cancel-order.md
 3- **Spec version:** v1.3
 4- **Spec status:** APPROVED
 5
 6## Spec Compliance Self-Review
 7| AC/EC | Status | Notes |
 8|-------|--------|-------|
 9| AC1-AC6 | ✅ | |
10| AC7, AC8 | ✅ | |
11| EC1 | ✅ | Via SELECT FOR UPDATE |
12| EC2 | ✅ | Best effort + log warning |
13| EC3 | ⚠️ | Context from middleware covers — JIRA-789 |
14
15## Test Coverage
16coverage: 91.2% of statements

The self-review table shifts the first compliance pass onto the author, where it’s cheapest — and the ⚠️ row for EC3 models honesty about partial coverage, complete with a tracking ticket. A reviewer arriving at a filled-in table starts from a much stronger position.

18.8 Conflict Resolution

Teams will disagree on how to implement an ambiguous AC, and the resolution process matters more than the specific answer. The steps below route the disagreement back through the spec rather than into a stalemate.

1When the team disagrees on AC9 (return 404 vs 409):
21. Check if the spec is explicit (if yes, follow spec)
32. If the spec is ambiguous, raise it as a spec issue
43. Bring it to tech lead + PM for a decision
54. Update the spec with the decision and reasoning
65. Implement based on the updated spec
7
8DO NOT: implement based on individual interpretation
9DO NOT: have a long discussion without written output

The two “DO NOT” lines are the real teeth of the process: the outcome must be a spec update, not a verbal agreement that drifts within a week. Resolving conflict in the spec means the decision survives and the next reader inherits it.

18.9 Sprint Workflow with SDD

SDD fits inside the sprint cadence you already run, adding a spec touchpoint to each ceremony. The outline below shows where the spec shows up from planning through retrospective.

1Sprint Planning: Verify all specs are APPROVED; estimate based on spec complexity
2Daily Standup: "Implemented AC1-AC3 from cancel-order.md"
3Mid-Sprint: Quick AI spec review for in-progress features
4Sprint Review: Demo verified against spec
5Retrospective: "Any spec drift? Process improvements?"

Notice how the spec becomes the shared vocabulary — standups reference ACs, reviews verify against the spec, and estimates key off spec complexity rather than gut feel. That common language is much of what makes team SDD cohere.

18.10 SDD Maturity Assessment

Teams adopt SDD gradually, and it helps to know where you are on the curve. The maturity model below describes what each level looks like in practice, from first adoption to fully internalized.

 1### Level 1: Basic (0-3 months)
 2All new features have a spec; specs are reviewed before implementation; code review checks the spec link
 3
 4### Level 2: Intermediate (3-6 months)
 5Spec versioning with changelog; test names reference AC/EC; AI compliance review per PR; coverage ≥ 80%
 6
 7### Level 3: Advanced (6-12 months)
 8Automated drift detection in CI; CLAUDE.md always current; onboarding < 1 week; contract testing
 9
10### Level 4: Expert (12+ months)
11SDD is the default mode; regression from spec drift is near zero; the spec is trusted by all stakeholders

Use this as a diagnostic, not a race: most of the ROI shows up by Level 2, and the higher levels are about making SDD frictionless rather than merely present. Knowing your level tells you which one improvement to invest in next.

18.11 Scaling SDD

The right amount of process depends heavily on team size — what works for five people breaks at fifteen. The guide below maps team size to an appropriate governance model.

1Small team (2-5):
2→ One CLAUDE.md; tech lead reviews all specs; informal process is fine
3
4Medium team (5-15):
5→ CLAUDE.md per domain; domain tech lead reviews domain specs; PR-based review
6
7Large team (15+):
8→ Dedicated spec owner per domain; spec review committee; automated tooling

The pattern is decentralization under load: as the team grows, review authority moves from one tech lead to per-domain owners and eventually to a committee plus tooling. Applying large-team governance to a five-person team is just as harmful as the reverse.

18.12 Common Team Anti-Patterns

Certain failure modes recur on almost every team adopting SDD, and naming them helps you spot them early. The four anti-patterns below are the ones to watch for.

• “Spec Optional” culture — “It’s a small task, let’s skip the spec.” Every task feels small, and drift happens on exactly those “small” tasks.
• Spec as justification, not guide — “I’ll write the spec after implementation for documentation.” That’s not SDD; it’s retrospective documentation.
• Not reading the spec before review — “I usually look at the code directly, spec later.” Spec review must come before or alongside code review.
• Outdated CLAUDE.md — written at project start, never updated, still describing old conventions.

The unifying failure across all four is treating the spec as overhead rather than as the source of truth. Each anti-pattern quietly reintroduces the drift and miscommunication that SDD exists to prevent.

18.13 Recommended Spec Repository Structure

A clear repository layout makes specs easy for both humans and AI to navigate. The tree below shows a structure that keeps specs, templates, contracts, and archives cleanly separated.

 1santekno-shop/
 2├── CLAUDE.md                          ← shared AI context
 3├── specs/
 4│   ├── README.md                      ← index + governance
 5│   ├── _templates/                    ← spec templates
 6│   ├── _archive/                      ← deprecated specs
 7│   ├── order/                         ← order domain specs
 8│   ├── product/                       ← product domain specs
 9│   └── contracts/                     ← inter-service contracts
10├── api/
11│   └── openapi.yaml                   ← HTTP contract specs
12└── docs/
13    ├── claude-code-setup.md           ← team setup guide
14    └── sdd-workflow.md                ← workflow guide

Co-locating specs with code in one repo means every spec change is versioned alongside its implementation — a single commit can carry both. The _archive/ and _templates/ folders keep the active spec set clean while preserving history and a starting point for new work.

18.14 Sharing Claude Code Setup

Everyone on the team should get the same behavior from Claude Code, which means a shared setup and a way to verify it. The setup guide below installs, configures, and — crucially — probes whether CLAUDE.md is actually loaded.

 1# docs/claude-code-setup.md
 2
 3## Install and Configure
 4npm install -g @anthropic-ai/claude-code
 5export ANTHROPIC_API_KEY=sk-ant-...  # ask the tech lead
 6
 7## Verify CLAUDE.md is Loaded
 8Probe test:
 9"I want to add business logic directly in the handler for validation."
10
11Expected: Claude refuses and explains layer separation.
12If different: check that CLAUDE.md exists at the project root.
13
14## Best Practices
15- Start each session by mentioning the spec being worked on
16- Use Plan Mode before large implementations
17- Commit after each task breakdown completes
18- Start a fresh session if > 50 messages (context window filling up)

The probe test is the clever part: it turns “is my setup correct?” into a concrete, falsifiable check. If Claude doesn’t refuse to put business logic in the handler, CLAUDE.md isn’t being read — and the developer knows to fix it before trusting any output.

18.15 Quarterly SDD Retrospective

Once a quarter, step back and examine the SDD process itself rather than any single feature. The agenda below allocates 90 minutes across metrics, wins, pain points, and concrete actions.

 1## SDD Quarterly Retrospective (90 min)
 2
 3Part 1 — Metrics (20 min):
 4- % of features with a spec this quarter?
 5- Average spec coverage (AC/EC)?
 6- Times spec drift was found, and where?
 7- Average time from spec to merged implementation?
 8
 9Part 2 — What Worked (20 min):
10- Which spec helped most during implementation?
11- Which aspects of SDD feel natural now?
12- An example where the spec prevented a bug or miscommunication?
13
14Part 3 — What Didn't Work (20 min):
15- Where did we bypass the spec process? Why?
16- Specs too detailed or too abstract?
17- Pain points in the current workflow?
18
19Part 4 — Action Items (30 min):
20- 3-5 concrete improvements for next quarter
21- Owner and timeline for each
22- CLAUDE.md and template updates needed

Grounding the retrospective in metrics — coverage, drift count, spec-to-merge time — keeps the discussion honest rather than anecdotal. The mandatory action items with owners are what turn insight into an actually-improved process next quarter.

18.16 Tips & Gotchas

Before the closing insight, here are the practical reminders that separate smooth team SDD from bureaucratic SDD. Treat them as guardrails while you tune your own process.

• Tip 1: Spec review and code review are two separate activities — different people can do each more effectively.
• Tip 2: Onboard via the “read spec, find implementation” exercise — the best way to learn the SDD workflow.
• Tip 3: Celebrate spec quality, not just delivery speed — teams measured only on velocity will skip the spec.
• Tip 4: Treat CLAUDE.md as a living document — spend 15 minutes at sprint planning to review and update it.
• Gotcha 1: SDD overhead is real but so is the ROI — communicate this to stakeholders questioning velocity.
• Gotcha 2: AI inconsistency between developers is normal — Claude is non-deterministic; what matters is that CLAUDE.md constraints are enforced.
• Gotcha 3: Don’t force SDD onto every task — production hotfixes have different rules; document them retroactively.
• Gotcha 4: Don’t make the spec process too democratic — delegate appropriately to avoid bottlenecks.

The balance these reminders point toward is enforcement without friction: enough discipline that the spec stays trustworthy, enough flexibility that developers don’t route around it.

18.17 The Core Insight: SDD is a Team Protocol

SDD at the team level is fundamentally about establishing a shared protocol for how software is built. Like any protocol, everyone must follow it consistently to get the benefits; it needs to be documented and accessible (CLAUDE.md, spec templates); it needs to evolve based on team experience (the quarterly retrospective); and it needs enforcement mechanisms (CI checks, PR templates, reviewer guides). The goal is not perfect compliance — it’s a culture where the natural question before any implementation is “Where’s the spec?”

18.18 Summary

SDD in teams is not just about tools — it’s about establishing a shared mental model of “how we build software.”

Good spec versioning includes a status lifecycle, a changelog with decision context, and clear ownership. Git versioning alone is insufficient without the accompanying narrative.

Effective onboarding for SDD means read spec, trace to implementation, shadow review, and a first-spec exercise — not formal workshops.

A PR process that reinforces SDD combines a template with a spec link, a reviewer checklist covering spec compliance, and AI review as a sanity check before human review.

Culture beats tools: CLAUDE.md takes an hour to set up, but building a culture where every developer naturally asks “where’s the spec?” before coding takes months.

In the next article, we’ll see everything in action: a complete case study from spec to merge for an e-commerce Order Service.