「仕様書がテストになり、テストが実装になる」 — Claude Code で実現する Spec-Driven Development

# specs/user_auth.yaml
feature: ユーザー認証
version: "1.0"
module: src/auth
 
functions:
  - name: validatePassword
    description: パスワードのバリデーションを行い、強度スコアを返す
    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: 有効なパスワード（英数字記号混在）
        input: "Secure@Pass1"
        expected:
          valid: true
          score_min: 80
          errors: []
      - description: 短すぎるパスワード
        input: "abc"
        expected:
          valid: false
          errors: ["パスワードは8文字以上必要です"]
      - description: 空文字
        input: ""
        expected:
          valid: false
          errors: ["パスワードを入力してください"]
      - description: 最大文字数超過
        input: "a" * 129
        expected:
          valid: false
          errors: ["パスワードは128文字以内にしてください"]
 
  - name: hashPassword
    description: パスワードを bcrypt でハッシュ化する
    inputs:
      - name: plaintext
        type: string
    outputs:
      - name: hash
        type: string
        format: bcrypt
    security:
      - salt_rounds: 12
      - timing_safe: true
    test_cases:
      - description: 同じパスワードでも毎回異なるハッシュが生成される
        assertion: hash1 != hash2 for same input
      - description: ハッシュはbcrypt形式
        assertion: hash.startswith("$2b$")

# tests/test_user_auth.py
import pytest
from src.auth import validatePassword, hashPassword
import bcrypt
 
class TestValidatePassword:
    """パスワードバリデーション機能のテスト"""
 
    def test_valid_password_returns_high_score(self):
        """有効なパスワード（英数字記号混在）は valid=True かつ score>=80"""
        result = validatePassword("Secure@Pass1")
        assert result["valid"] is True, f"valid should be True, got {result['valid']}"
        assert result["score"] >= 80, f"score should be >= 80, got {result['score']}"
        assert result["errors"] == [], f"errors should be empty, got {result['errors']}"
 
    def test_too_short_password(self):
        """8文字未満は valid=False でエラーメッセージを返す"""
        result = validatePassword("abc")
        assert result["valid"] is False
        assert "パスワードは8文字以上必要です" in result["errors"], \
            f"Expected length error, got {result['errors']}"
 
    def test_empty_password(self):
        """空文字は valid=False で入力要求エラーを返す"""
        result = validatePassword("")
        assert result["valid"] is False
        assert "パスワードを入力してください" in result["errors"]
 
    def test_password_at_max_length(self):
        """128文字は valid=True（境界値）"""
        result = validatePassword("A" * 120 + "@1aBcDe!!")
        assert result["valid"] is True, f"128-char password should be valid, got {result}"
 
    def test_password_exceeds_max_length(self):
        """129文字は valid=False で文字数超過エラーを返す"""
        result = validatePassword("a" * 129)
        assert result["valid"] is False
        assert "パスワードは128文字以内にしてください" in result["errors"]
 
    def test_password_exactly_8_chars(self):
        """8文字ちょうどは有効（境界値）"""
        result = validatePassword("Abcde!1x")
        assert result["valid"] is True, f"8-char valid password should pass, got {result}"
 
    def test_score_is_in_valid_range(self):
        """スコアは常に 0-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:
    """パスワードハッシュ化機能のテスト"""
 
    def test_same_password_produces_different_hashes(self):
        """同じパスワードでも毎回異なるハッシュが生成される（ソルト確認）"""
        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):
        """生成されたハッシュは bcrypt 形式"""
        hash_value = hashPassword("TestPassword1!")
        assert hash_value.startswith("$2b$"), \
            f"Hash should be bcrypt format, got: {hash_value[:10]}..."
 
    def test_hash_can_be_verified(self):
        """元のパスワードでハッシュを検証できる"""
        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):
        """異なるパスワードはハッシュ検証に失敗する"""
        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:
    """
    パスワードのバリデーションを行い、強度スコアを返す。
 
    Args:
        password: バリデーション対象のパスワード文字列
 
    Returns:
        dict: {valid: bool, score: int, errors: list[str]}
    """
    errors: list[str] = []
    score = 0
 
    # 空文字チェック（最優先）
    if not password:
        return {"valid": False, "score": 0, "errors": ["パスワードを入力してください"]}
 
    # 最大文字数チェック
    if len(password) > 128:
        errors.append("パスワードは128文字以内にしてください")
 
    # 最小文字数チェック
    if len(password) < 8:
        errors.append("パスワードは8文字以上必要です")
 
    # バリデーションエラーがある場合は早期リターン
    if errors:
        return {"valid": False, "score": 0, "errors": errors}
 
    # 強度スコア計算
    score += min(len(password) * 2, 30)  # 長さボーナス（最大30点）
 
    if re.search(r'[a-z]', password):
        score += 15  # 小文字
    if re.search(r'[A-Z]', password):
        score += 15  # 大文字
    if re.search(r'\d', password):
        score += 20  # 数字
    if re.search(r'[!@#$%^&*(),.?":{}|<>]', password):
        score += 20  # 記号
 
    score = min(score, 100)
 
    return {"valid": True, "score": score, "errors": []}
 
def hashPassword(plaintext: str) -> str:
    """
    パスワードを bcrypt でハッシュ化する。
 
    Args:
        plaintext: ハッシュ化するパスワード文字列
 
    Returns:
        str: bcrypt ハッシュ文字列（$2b$ 形式）
 
    Note:
        salt_rounds=12 を使用。毎回異なるソルトが生成されるため、
        同一パスワードでもハッシュ値は毎回異なる。
    """
    salt = bcrypt.gensalt(rounds=12)
    hashed = bcrypt.hashpw(plaintext.encode('utf-8'), salt)
    return hashed.decode('utf-8')

# 認証モジュール API リファレンス
 
## `validatePassword(password: str) -> dict`
 
パスワードの強度を検証し、スコアとエラー一覧を返します。
 
#### 引数
 
- **password** (str): バリデーション対象のパスワード
 
#### 戻り値
 
```json
{
  "valid": true,
  "score": 85,
  "errors": []
}
```
 
- **valid** (bool): バリデーション通過の可否
- **score** (int): 強度スコア（0〜100）
- **errors** (list[str]): エラーメッセージ一覧（valid=false の場合）
 
#### 使用例
 
```python
result = validatePassword("Secure@Pass1")
if not result["valid"]:
    for error in result["errors"]:
        print(f"エラー: {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 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 "🔧 仕様書から生成: $spec"
            
            # テストコードを生成
            claude --print "
              $spec を読んで、pytest 形式のテストコードを生成してください。
              - ファイルパス: tests/$(basename $spec .yaml)_test.py
              - 全 test_cases を網羅する
              - 境界値テストを追加する
              - エラーハンドリングのテストを含める
            "
          done
 
      - name: Run tests (Red phase check)
        run: |
          pytest tests/ -v --tb=short 2>&1 | tee /tmp/test_results.txt || true
          # テスト失敗は意図的（実装前の Red フェーズ）
 
      - name: Generate implementation from failing tests
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          TEST_OUTPUT=$(cat /tmp/test_results.txt)
          
          claude --print "
            以下のテストが失敗しています。仕様書に従い、全テストを通過する実装を生成してください。
            
            テスト結果:
            $TEST_OUTPUT
            
            制約:
            - 既存のコードを破壊しない
            - 型ヒントを使用する
            - エラーハンドリングを含める
          "
 
      - name: Run tests (Green phase verification)
        run: pytest tests/ -v --tb=long
 
      - name: Update documentation
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude --print "
            変更された実装を分析して、docs/ 以下の API ドキュメントを更新してください。
            変更した仕様書: $(git diff --name-only HEAD~1 HEAD -- 'specs/**/*.yaml')
          "
 
      - 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: spec変更に基づくテスト・実装・ドキュメントの自動更新"
          git push

# ❌ これは YAML パースエラーになる
errors: ["パスワードは: 8文字以上必要です"]
 
# ✅ シングルクォートで囲む
errors: ['パスワードは: 8文字以上必要です']

# ❌ Claude Code が生成したチート実装の例
def validatePassword(password: str) -> dict:
    # テストケースを見てハードコード...
    if password == "Secure@Pass1":
        return {"valid": True, "score": 85, "errors": []}
    if password == "abc":
        return {"valid": False, "score": 0, "errors": ["パスワードは8文字以上必要です"]}
    # ...

# AUTO-GENERATED from specs/user_auth.yaml v1.1
# Last updated: 2026-04-17
# このファイルは自動生成です。直接編集しないでください。
# 変更する場合は specs/ の仕様書を更新して再生成してください。

# specs/user_repository.yaml
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バイト数で規定する
        notes:
          - "bcrypt は先頭72バイトのみを鍵に使う。日本語なら24文字で到達する"
          - "超過時の挙動は bcrypt 4系以降で ValueError に変わっている"

import base64
import hashlib
import bcrypt
 
def hashPassword(plaintext: str) -> str:
    # SHA-256 で 32 バイトに畳んでから base64 で 44 バイトの ASCII にする。
    # 生のダイジェストをそのまま渡すと 0x00 が混ざり、C 文字列としてそこで切れる。
    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())

# 最初の仕様書（小さく始める）
feature: 数値フォーマット
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"