Skip to content

SDD-METHODOLOGY — Spec Driven Development as Canonical Law

Status: live · Version: 1.0.0 · Camada: 19 · Rule 35 (canonical) — Spec antes do código

Purpose

SDD makes the spec the source of truth. Code, tests, and documentation derive from spec. Story acceptance requires spec approval before any code is written.

The cycle

SPEC ─▶ HARNESS ─▶ CODE ─▶ VERIFY ─▶ (loop)
  ▲                                  │
  └──────── revisions ───────────────┘

1. SPEC

  • Story has a spec: PRD section + acceptance criteria + constraints + structure (if new project)
  • Spec passes DoR (Definition of Ready)
  • Spec is approved by Product Agent + Architect Agent
  • check_spec_approved() validates before allowing Phase 2 (Planning)

2. HARNESS

  • Behavioral harness generated from spec
  • N scenarios cover: happy path + edge cases + failure modes
  • Harness MUST pass minimum threshold per scale (harness_min_pass_rate)
  • See HARNESS-ENGINE for details

3. CODE

  • Agent writes minimal code to satisfy spec + pass harness
  • TDD enforced when profile allows (Rule 14 contextual)
  • No code without corresponding spec line

4. VERIFY

  • All harness scenarios pass at min threshold
  • Phase 5 reviewer approves (Rule 15)
  • Audit (Phase 3) clean
  • DoD binary (Rule 4) — only "fully done" accepted

Spec approval check

def check_spec_approved(story: Story) -> SpecCheckResult:
    required = {
        "prd":      story.has_prd_section(),
        "ac_min":   len(story.acceptance_criteria) >= profile.ac_min_per_story,
        "scope":    story.has_explicit_scope(),
        "structure": story.creates_new_project == False or story.has_project_structure(),
    }
    if not all(required.values()):
        return SpecCheckResult(approved=False, missing=[k for k,v in required.items() if not v])
    return SpecCheckResult(approved=True)

Required per scale: - MICRO: ac_min=3 - MINI: ac_min=4 - MEDIUM: ac_min=4 - NORMAL: ac_min=5 - LARGE: ac_min=6

Integration with framework

  • PIPELINE-VALIDATION (C7) — Phase 2 (Planning) blocked until check_spec_approved passes
  • STORIES.md (C3 template) — DoR includes spec criteria
  • HARNESS-ENGINE (sibling) — generates harness from approved spec
  • PROJECT-STRUCTURE (C3 template) — part of spec for new-project stories
  • ARCHITECTURE-PATTERNS (sibling) — informs spec when architectural choices needed

Rule 35 enforcement (absolute)

Violation = HALT. Cannot proceed past Phase 1 without approved spec.

Audit detects: - Story with no spec → reject at Phase 0 - Story with spec but not approved → reject at Phase 2 - Code commit without corresponding spec ref → CI fail

Cross-references

  • CONSTITUTION — Rule 35
  • HARNESS-ENGINE (sibling)
  • PROJECT-STRUCTURE.md (C3 template)
  • ARCHITECTURE-PATTERNS (sibling)
  • STORIES.md (C3 template) — DoR
  • PIPELINE-VALIDATION (C7)