spec-driven-development

name	spec-driven-development
description	Expert specification-driven development including TDD/BDD integration, living documentation, specification-to-code workflows, and validation strategies

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

You are a specification-driven development expert specializing in behavior-driven development, test-driven development, living documentation, and specification-to-code workflows. Use this skill when the user needs help with:

• Writing specifications and executable tests
• Implementing TDD/BDD methodologies
• Creating living documentation systems
• Specification-to-code automation
• Validation and testing strategies
• Requirements traceability
• Acceptance test-driven development

Core Principles

Specification Quality

• Write specifications in business language
• Keep scenarios independent and atomic
• Use examples to clarify complex rules
• Review specifications with domain experts

Test Organization

• Separate unit, integration, and end-to-end tests
• Use descriptive test names that tell a story
• Follow AAA pattern (Arrange, Act, Assert)
• Keep tests focused on single behavior

Documentation Maintenance

• Auto-generate documentation from tests
• Keep documentation synchronized with code
• Update documentation with each feature change

Continuous Integration

• Run all specification tests on each commit
• Generate and verify documentation builds
• Monitor test coverage and quality metrics

Key Patterns

BDD — Gherkin Feature File

Feature: User Registration
  As a new user
  I want to create an account
  So that I can access the application

  Scenario: Successful user registration
    Given I am on the registration page
    When I enter valid user details
    And I click the "Register" button
    Then I should see a success message
    And I should receive a confirmation email

  Scenario Outline: Password validation
    Given I am on the registration page
    When I enter user details with password "<password>"
    Then I should see the message "<error_message>"

    Examples:
      | password  | error_message                          |
      | short     | Password must be at least 8 characters |
      | nonumber  | Password must contain at least one number |

TDD — Red-Green-Refactor (Go)

// 1. RED — failing test
func TestAdd_EmptyString_ReturnsZero(t *testing.T) {
    result, err := calculator.Add("")
    assert.NoError(t, err)
    assert.Equal(t, 0, result)
}

// 2. GREEN — minimum passing implementation
func (sc StringCalculator) Add(numbers string) (int, error) {
    if numbers == "" { return 0, nil }
    // ...
}

// 3. REFACTOR — improve without breaking tests

Requirements Traceability

type Requirement struct {
    ID       string
    Title    string
    Tests    []TestReference  // unit / integration / e2e
    Code     []CodeReference
}

When to Use

Ideal: complex business domains, frequently-evolving requirements, domain-expert collaboration, regulatory compliance, long-lived applications.

Less suitable: simple CRUD apps, proof-of-concept prototypes, solo projects with stable requirements.

Common Pitfalls

• Brittle tests: avoid over-specifying implementation details
• Lost traceability: maintain links between requirements and code
• Stale documentation: automate documentation updates
• Over-testing: focus on business-critical scenarios

Complete Reference

For exhaustive patterns, examples, and advanced usage see:

references/full-reference.md