Spec-Driven WaterFlow 開発

仕様を源流に、プロトタイプと実装を同期させる現実解

プロジェクトノート / v1.0 ・ プロトタイプ基盤: stitch_welcome_screen/*/code.html

目次

背景
全体像（WaterFlow）
中核アーティファクト
プロセス詳細
同期とガバナンス
リポジトリ運用
品質・リスク
まとめ
背景: なぜ Spec-Driven か
複数のステークホルダー（事業、デザイン、開発、運用）が関与するプロジェクトでは、暗黙知や口頭合意が積み重なるほど齟齬が増えます。 本プロジェクトでは Spec（仕様）を唯一の真実の源泉（SSOT） とし、そこから プロトタイプ と 実装 を連動させることで、常に同じ地図を見ながら進めることを狙います。

図1: Spec を中心にした同期

仕様（Spec / SSOT）
プロトタイプ（UI）
実装（API/フロント）
Spec を源流に、UI と実装へ流し込み、レビューで循環させる。

全体像: WaterFlow という現実解
WaterFlow は、厳密なウォーターフォールとアジャイルの中庸に位置づく 段階的合意 × 連続的検証 モデルです。 ゲートで合意を固定しつつ、次段のプロトタイプや軽量実装でフィードバックを即時に反映します。

図2: WaterFlow の基本フロー

要件定義
仕様（Spec）
プロトタイプ
実装
検証・受入
リリース
Spec Gate
UX Gate
Dev Gate
QA Gate
各ゲートで合意を固定しつつ、後段で軽量に検証して戻す。

段階的合意

Spec / UX / Dev / QA 各ゲートで合意を明確化。

連続的検証

プロトタイプや PoC を並走させ、早期に齟齬を発見。

SSOT

仕様を唯一の真実として管理し、派生物は同期で保つ。

中核アーティファクト（このリポジトリ）
外国人向け求人システム_要件定義書.md: 上位要件・前提の記録
stitch_welcome_screen/<feature>/code.html: UI プロトタイプ（静的 HTML、2 スペースインデント）
assets/: ローカル素材（フォント/アイコン）。外部 CDN 依存は最小化
process/: チェックリストによるゲート合意の可視化
図3: 仕様・UI・実装の対応マップ

要件ドキュメント
仕様（Spec）
UI プロトタイプ（code.html）
API/実装
視覚的合意 / a11y 確認
前提・目的
業務ルール / 仕様項目
契約・保存・API 統合
Gate: チェックリスト（process/templates/*.md）
チェックリストで段階的に合意を固定し、差分は UI/Spec に反映。

プロセス詳細（Spec-Driven × WaterFlow）
要件→仕様整備: 目的・スコープ・非機能・制約を明文化。曖昧語は排除。
仕様→UI プロトタイプ: stitch_welcome_screen/<feature>/code.html を追加し、主要ケースを可視化。
UI レビュー: 375 / 768 / 1280px で視覚確認と a11y チェック。
Dev 設計: API 契約・データ構造・エラーモデルを洗い出し、Spec に往復反映。
実装・検証: 小さく実装 → ハッピーパス/フェイルパスで確認 → 受入。
Tip: プロトタイプは python3 -m http.server 8000 で手早く確認できます。

同期とガバナンス（逸脱の早期検出）
逸脱は早期に小さく見つけて潰すのがコスト最小です。WaterFlow では レビューの頻度 と 同期の即時性 に投資します。

Spec を更新したら UI/実装への影響を即チェック
UI 側の気づきは Spec に必ず逆流（SSOT 維持）
チェックリストを通過できない変更はゲートで止める
図4: 逸脱検出の最短ループ

Spec
UI
実装
UI レビュー
実装レビュー
差分を Spec に還元
短いループで差分を捕捉し、Spec を常に最新に保つ。

リポジトリ運用（実務の型）
画面は stitch_welcome_screen/<feature>/code.html に追加（snake_case）
HTML は 2 スペース、セマンティックなタグ、最小限の inline style
アクセシビリティ: キーボード到達、代替テキスト、コントラスト
検証: 375/768/1280px の視覚確認、W3C Validator で基本整合
PR: 目的・差分・スクショ・フォローアップを明記（小さく、速く）
プレビュー: python3 -m http.server 8000 → http://localhost:8000/stitch_welcome_screen/spec_waterflow_blog/code.html
品質・リスクの扱い
要件漏れ: 仕様テンプレートとチェックリストで網羅性を担保
UI/仕様の乖離: プロトタイプの並走と週次レビューで同期
実装遅延: ゲートでの早期着火、依存の見える化、スライス分割
リリース品質: 受入観点を Spec 化、失敗ケースの先回り検証
まとめ
Spec を唯一の真実として据えることで、議論の土台と変更の理由が明快になり、UI と実装の同期コストが劇的に下がります。WaterFlow はその思想を現実のプロジェクトに適用するための、ちょうど良い強度 のプロセスです。

合意は段階的に、検証は連続的に
小さく作って早く見せる（プロトタイプ）
差分は必ず Spec に戻す（SSOT）