ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/.claude/system/sdd-principles.md

5.7 KiB
Raw Blame History

Specification-Driven Development (SDD) Principles

Core Philosophy

Specifications don't serve code—code serves specifications.

The BMAD-Spec Orchestrator embodies Specification-Driven Development, where specifications become executable and generate implementation rather than just documenting it.

The Power Inversion

Traditional development treats specifications as scaffolding—useful for planning but discarded once coding begins. SDD inverts this relationship:

  • Traditional: Specification → (gap) → Implementation → (drift) → Reality
  • SDD: Specification → Implementation Plan → Code → Production

Key Transformations

  1. Specifications as Source of Truth: The PRD, architecture docs, and user stories ARE the primary artifacts
  2. Code as Expression: Implementation becomes the expression of specifications in specific languages/frameworks
  3. AI as Translator: Claude agents translate specifications into working systems systematically
  4. Continuous Regeneration: Changes to specs automatically propagate to implementation

SDD Workflow in Practice

1. Intent-Driven Development

  • Development team expresses intent in natural language
  • Specifications capture business logic, not implementation details
  • Lingua franca shifts from code to structured specifications

2. Iterative Specification Refinement

Vague Idea → AI Dialogue → Comprehensive PRD → Implementation Plans → Working Code

3. Systematic Alignment

  • Every technology choice has documented rationale
  • All architectural decisions trace back to specific requirements
  • Changes propagate systematically through the specification chain

4. Continuous Evolution

Production Feedback → Specification Updates → Implementation Regeneration

Why SDD Matters Now

1. AI Capability Threshold

  • Natural language specifications can reliably generate working code
  • AI amplifies developer effectiveness by automating specification-to-code translation

2. Complexity Management

  • Modern systems integrate dozens of services, frameworks, dependencies
  • SDD provides systematic alignment through specification-driven generation

3. Accelerated Change Pace

  • Requirements change rapidly in modern development
  • Pivots become systematic regenerations rather than manual rewrites
  • What-if experiments: "How would we implement X business need?"

SDD in BMAD-Spec Orchestrator

Agent Orchestration as SDD

Each agent in our system embodies SDD principles:

  1. Analyst Agent: Transforms vague ideas into precise specifications
  2. PM Agent: Creates executable product requirements (PRDs)
  3. UX Expert: Specifications become interface definitions
  4. Architect: Technical specs drive technology decisions
  5. Developer: Specifications generate implementation
  6. QA Agent: Test specs ensure specification compliance

Template-Driven Generation

  • Templates are executable specifications
  • Variables become specification parameters
  • Generated documents are implementation plans

Context Preservation

  • Session management maintains specification continuity
  • Agent handoffs preserve specification integrity
  • Version control tracks specification evolution

Practical Benefits

For Development Teams

  • Faster Iteration: Changes to specs regenerate implementation
  • Consistent Quality: Specifications enforce patterns and standards
  • Reduced Technical Debt: Systematic generation prevents accumulation
  • Enhanced Creativity: Focus on problem-solving, not mechanical translation

For Organizations

  • Accelerated Delivery: Specification-to-production pipeline
  • Predictable Outcomes: Specifications define exact deliverables
  • Risk Reduction: Generated code follows established patterns
  • Knowledge Preservation: Intent captured in specifications, not just code

Implementation Guidance

Writing SDD-Compatible Specifications

✅ DO: "Users must authenticate before accessing protected resources"
❌ AVOID: "Use JWT tokens with Express middleware"

✅ DO: "System must handle 1000 concurrent users with <100ms response time"  
❌ AVOID: "Use Redis caching and horizontal scaling"

✅ DO: "Invalid inputs should show clear error messages to users"
❌ AVOID: "Implement try-catch blocks with error logging"

Agent Interaction Patterns

  • Specifications First: Always start with business requirements
  • Implementation Second: Let agents choose technical solutions
  • Validation Throughout: Continuous specification-implementation alignment
  • Evolution Support: Design for specification changes

Success Metrics

Specification Quality

  • Precision: Requirements are unambiguous and testable
  • Completeness: All scenarios and edge cases covered
  • Traceability: Every implementation decision traces to requirements
  • Maintainability: Specifications evolve cleanly over time

Implementation Fidelity

  • Conformance: Generated code matches specifications exactly
  • Consistency: Similar requirements generate similar solutions
  • Quality: All implementations meet established standards
  • Performance: Specifications drive optimization decisions

The SDD Future

SDD transforms software development from craftsmanship to manufacturing—not by reducing creativity, but by amplifying it. Teams focus on what to build and why, while AI handles the how.

The BMAD-Spec Orchestrator is SDD in practice: a systematic approach to transforming human intent into working software through intelligent specification execution.

This document establishes SDD as the foundational philosophy for all BMAD-Spec Orchestrator operations. All agents, workflows, and templates must embody these principles.