From Spec to Production: Spec-Driven Development with Claude Code

# specs/user_auth.yaml
feature: User Authentication
version: "1.0"
module: src/auth
 
functions:
  - name: validatePassword
    description: Validates a password and returns a strength score
    inputs:
      - name: password
        type: string
        constraints:
          - min_length: 8
          - max_length: 128
    outputs:
      - name: result
        type: object
        fields:
          - name: valid
            type: boolean
          - name: score
            type: integer
            range: [0, 100]
          - name: errors
            type: array
            items: string
    test_cases:
      - description: Valid password with mixed characters
        input: "Secure@Pass1"
        expected:
          valid: true
          score_min: 80
          errors: []
      - description: Password too short
        input: "abc"
        expected:
          valid: false
          errors: ["Password must be at least 8 characters"]
      - description: Empty string
        input: ""
        expected:
          valid: false
          errors: ["Password is required"]
      - description: Exceeds maximum length
        input: "a" * 129
        expected:
          valid: false
          errors: ["Password must not exceed 128 characters"]
 
  - name: hashPassword
    description: Hash a plaintext password using bcrypt
    inputs:
      - name: plaintext
        type: string
    outputs:
      - name: hash
        type: string
        format: bcrypt
    security:
      - salt_rounds: 12
      - timing_safe: true
    test_cases:
      - description: Same password produces different hashes each time
        assertion: hash1 != hash2 for same input
      - description: Hash is in bcrypt format
        assertion: hash.startswith("$2b$")

# tests/test_user_auth.py
import pytest
from src.auth import validatePassword, hashPassword
import bcrypt
 
class TestValidatePassword:
    """Tests for password validation"""
 
    def test_valid_password_returns_high_score(self):
        """Valid password with mixed chars: valid=True, score>=80"""
        result = validatePassword("Secure@Pass1")
        assert result["valid"] is True, f"Expected valid=True, got {result['valid']}"
        assert result["score"] >= 80, f"Expected score >= 80, got {result['score']}"
        assert result["errors"] == [], f"Expected no errors, got {result['errors']}"
 
    def test_too_short_password(self):
        """Password under 8 chars returns valid=False with length error"""
        result = validatePassword("abc")
        assert result["valid"] is False
        assert "Password must be at least 8 characters" in result["errors"], \
            f"Expected length error, got {result['errors']}"
 
    def test_empty_password(self):
        """Empty string returns valid=False with required field error"""
        result = validatePassword("")
        assert result["valid"] is False
        assert "Password is required" in result["errors"]
 
    def test_password_at_max_length(self):
        """128-character password is valid (boundary value)"""
        result = validatePassword("A" * 120 + "@1aBcDe!!")
        assert result["valid"] is True, f"128-char password should be valid: {result}"
 
    def test_password_exceeds_max_length(self):
        """129-character password returns valid=False"""
        result = validatePassword("a" * 129)
        assert result["valid"] is False
        assert "Password must not exceed 128 characters" in result["errors"]
 
    def test_password_exactly_8_chars(self):
        """8-character password is valid (boundary value)"""
        result = validatePassword("Abcde!1x")
        assert result["valid"] is True, f"8-char valid password should pass: {result}"
 
    def test_score_is_always_in_range(self):
        """Score is always between 0 and 100"""
        for pwd in ["weak", "Stronger1!", "V3ryStr0ng@Passw0rd!"]:
            result = validatePassword(pwd)
            assert 0 <= result.get("score", 0) <= 100, \
                f"Score out of range for '{pwd}': {result.get('score')}"
 
class TestHashPassword:
    """Tests for password hashing"""
 
    def test_same_password_produces_different_hashes(self):
        """Salt ensures different hashes for the same input"""
        hash1 = hashPassword("TestPassword1!")
        hash2 = hashPassword("TestPassword1!")
        assert hash1 != hash2, "Same password should produce different hashes due to salt"
 
    def test_hash_is_bcrypt_format(self):
        """Generated hash is in bcrypt format"""
        hash_value = hashPassword("TestPassword1!")
        assert hash_value.startswith("$2b$"), \
            f"Hash should start with $2b$, got: {hash_value[:10]}..."
 
    def test_hash_can_be_verified(self):
        """Original password verifies against generated hash"""
        password = "TestPassword1!"
        hash_value = hashPassword(password)
        assert bcrypt.checkpw(password.encode(), hash_value.encode()), \
            "Original password should match the generated hash"
 
    def test_wrong_password_fails_verification(self):
        """Wrong password fails hash verification"""
        hash_value = hashPassword("CorrectPassword1!")
        assert not bcrypt.checkpw("WrongPassword1!".encode(), hash_value.encode()), \
            "Wrong password should fail hash verification"

# src/auth.py
from __future__ import annotations
import re
import bcrypt
 
def validatePassword(password: str) -> dict:
    """
    Validate a password and return a strength score.
 
    Args:
        password: The password string to validate
 
    Returns:
        dict with keys: valid (bool), score (int 0-100), errors (list[str])
    """
    # Empty check — highest priority
    if not password:
        return {"valid": False, "score": 0, "errors": ["Password is required"]}
 
    errors: list[str] = []
 
    # Length constraints
    if len(password) > 128:
        errors.append("Password must not exceed 128 characters")
 
    if len(password) < 8:
        errors.append("Password must be at least 8 characters")
 
    # Early return if validation failed
    if errors:
        return {"valid": False, "score": 0, "errors": errors}
 
    # Strength scoring
    score = min(len(password) * 2, 30)          # Length bonus (max 30)
    if re.search(r'[a-z]', password): score += 15  # Lowercase
    if re.search(r'[A-Z]', password): score += 15  # Uppercase
    if re.search(r'\d', password):    score += 20  # Digits
    if re.search(r'[!@#$%^&*(),.?":{}|<>]', password): score += 20  # Symbols
    score = min(score, 100)
 
    return {"valid": True, "score": score, "errors": []}
 
def hashPassword(plaintext: str) -> str:
    """
    Hash a plaintext password using bcrypt.
 
    Args:
        plaintext: The password to hash
 
    Returns:
        bcrypt hash string in $2b$ format
 
    Note:
        Uses salt_rounds=12. Each call generates a unique salt,
        so the same password produces a different hash each time.
    """
    salt = bcrypt.gensalt(rounds=12)
    hashed = bcrypt.hashpw(plaintext.encode('utf-8'), salt)
    return hashed.decode('utf-8')

# Authentication Module API Reference
 
## `validatePassword(password: str) -> dict`
 
Validates password strength and returns a result object.
 
#### Arguments
 
- **password** (str): The password string to validate
 
#### Return value
 
```json
{
  "valid": true,
  "score": 85,
  "errors": []
}
```
 
- **valid** (bool): Whether the password passed validation
- **score** (int): Strength score from 0 to 100
- **errors** (list[str]): Error messages when valid is False
 
#### Usage example
 
```python
result = validatePassword("Secure@Pass1")
if not result["valid"]:
    for error in result["errors"]:
        print(f"Error: {error}")
```

# .github/workflows/spec-driven.yml
name: Spec-Driven Development Pipeline
 
on:
  push:
    paths:
      - 'specs/**/*.yaml'
 
jobs:
  generate-and-test:
    runs-on: ubuntu-latest
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: 'pip'
 
      - name: Install dependencies
        run: pip install -r requirements.txt
 
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
 
      - name: Generate tests from changed specs
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          CHANGED_SPECS=$(git diff --name-only HEAD~1 HEAD -- 'specs/**/*.yaml')
 
          for spec in $CHANGED_SPECS; do
            echo "Generating from spec: $spec"
            claude --print "
              Read $spec and generate pytest test code.
              - Output path: tests/$(basename $spec .yaml)_test.py
              - Cover all test_cases in the spec
              - Add boundary value tests for numeric constraints
              - Include error handling tests
            "
          done
 
      - name: Run tests (Red phase — expected to fail)
        run: pytest tests/ -v --tb=short 2>&1 | tee /tmp/test_results.txt || true
 
      - name: Generate implementation from failing tests
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          TEST_OUTPUT=$(cat /tmp/test_results.txt)
          claude --print "
            The following tests are failing. Generate implementation
            following the spec to make all tests pass.
 
            Test output:
            $TEST_OUTPUT
 
            Constraints:
            - Do not break existing code
            - Use type hints
            - Include error handling
          "
 
      - name: Verify Green phase
        run: pytest tests/ -v --tb=long
 
      - name: Update documentation
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          CHANGED=$(git diff --name-only HEAD~1 HEAD -- 'specs/**/*.yaml')
          claude --print "
            Analyze the updated implementation and update docs/ API documentation.
            Changed specs: $CHANGED
          "
 
      - name: Commit generated files
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "GitHub Actions"
          git add tests/ src/ docs/
          git diff --staged --quiet || git commit -m "chore: auto-update tests, implementation, and docs from spec change"
          git push

# ❌ This causes a YAML parse error
errors: ["Password is required: enter a value"]
 
# ✅ Single-quote the string
errors: ['Password is required: enter a value']

# ❌ What Claude Code sometimes generates
def validatePassword(password: str) -> dict:
    if password == "Secure@Pass1":
        return {"valid": True, "score": 85, "errors": []}
    if password == "abc":
        return {"valid": False, "score": 0, "errors": ["..."]}
    # ...

# AUTO-GENERATED from specs/user_auth.yaml v1.1
# Last updated: 2026-04-17
# DO NOT EDIT MANUALLY — update the spec and regenerate

testing:
  environment_constraints:
    - database: "mock required (no real DB in CI)"
    - external_apis: "mock with pytest-mock"
  mock_library: "pytest-mock"

    inputs:
      - name: password
        type: string
        constraints:
          - min_length: 8
          - max_bytes: 72        # UTF-8 bytes, not characters
        notes:
          - "bcrypt keys on the first 72 bytes only; 24 Japanese characters reach that"
          - "Overflow behavior changed to ValueError in bcrypt 4.x and later"

import base64
import hashlib
import bcrypt
 
def hashPassword(plaintext: str) -> str:
    # SHA-256 folds any input to 32 bytes; base64 makes it 44 printable ASCII bytes.
    # Passing the raw digest instead risks an embedded 0x00 cutting the C string short.
    digest = hashlib.sha256(plaintext.encode("utf-8")).digest()
    return bcrypt.hashpw(base64.b64encode(digest), bcrypt.gensalt(rounds=12)).decode()
 
def verifyPassword(plaintext: str, hashed: str) -> bool:
    digest = hashlib.sha256(plaintext.encode("utf-8")).digest()
    return bcrypt.checkpw(base64.b64encode(digest), hashed.encode())

# Start small — a single function
feature: Currency Formatting
functions:
  - name: formatCurrency
    inputs:
      - name: amount
        type: number
    outputs:
      - name: result
        type: string
    test_cases:
      - input: 1000
        expected: "$1,000"
      - input: 0
        expected: "$0"
      - input: -500
        expected: "-$500"