はじめに

「コードを書く前に仕様を明確にする」 ーこの原則を徹底するのが 仕様駆動開発（Spec Driven Development） です。
AI駆動開発ツールが急速に普及し始めた今、改めて「仕様を言語化する」ことの重要性が再評価されています。

なぜ今、SDDなのか？

AIと人間が協調して開発する時代に、「曖昧な指示」や「暗黙知」 が大きな障壁となるからです。AIに「ちゃんと伝わる」仕様を作ることで、人間の思い込みや抜け漏れによるトラブルを未然に防ぎ、AIの力を最大限に引き出すことができます。

今回は、SDD（仕様駆動開発）を2つのAI開発ツールで実践し、その違い・気づきを徹底比較します。

SDDとは？

仕様駆動開発（Spec Driven Development） とは、ソフトウェア開発の最初の段階で「仕様」を明確かつ構造的に記述し、その仕様をもとに設計・実装・テスト・ドキュメント化まで一貫して進める開発手法です。
従来の「ウォーターフォール」や「アジャイル」とも異なり、AI時代の新しい開発パラダイムとして注目されています。
最近では、AWSがリリースしたIDE「Kiro」にもSDDが標準搭載され、AIを活用した開発効率の劇的な向上が期待されています。

AWSがリリースしたIDE：Kiro
Kiro.dev：kiro.dev

開発フロー

従来は、人間がすべての要件定義から実装・テストまで を担っていました。しかし今後は、AIが要件を理解し、設計や実装を自動化する流れが加速します。
その際、AIが誤解しないための仕様の明文化、曖昧な指示や「なんとなく」で済ませない設計が極めて重要です。

※「暗黙知」＝経験的に使っている知識だが、簡単に言葉で説明できない知識のこと
（例：「このくらい分かるよね？」←人によって解釈が異なる）

今までの開発

要件定義 → 設計 → 開発 → テスト → リリース

AI開発フロー

AI対話型要件定義 → 構造化設計 → AIタスク定義 → AI実装 → 自動品質チェック → AIレビュー → 人間レビュー

SDDのメリット

AIの暴走を防ぎ、期待通りのアウトプットが得られる
- → 仕様を明確にすることで、AIが意図しない実装や誤動作を減らせる
人による「解釈のズレ」を最小化できる
- → チーム開発や複数AIエージェントとの協働においても有効
テストやレビューの自動化がしやすくなる
- → 仕様＝テストケースになるため、「仕様の抜け漏れ」も見つけやすい
プロダクトの品質・再利用性が上がる
- → 仕様書がそのままドキュメントや設計資産になる

SDDのデメリット

仕様を明確に書くのは意外と難しい
- → 初期段階で「何を作るか」を言語化しきれないと、後工程で手戻りが増える
完全な自動化は難しく、人のチェックが必須
- → 仕様通りに本当に開発できているか、最終的な判断は人間の目が必要
「柔軟な仕様変更」には工夫が必要
- → 仕様変更時にAIやツールへの反映が煩雑になりがち

検証環境

使用したツール

今回、以下のAI開発ツールでSDDを実践しました。

Windsurf（Claude Sonnet 4）
Claude Code（Claude Sonnet 4）

PC環境

WindsurfはWSL環境との相性が悪かったため、Windows環境で検証を行いました。

Thinkpad
Windouws11
Powershell

作成したプロダクト

実際のユースケースとして、自分の結婚式用ホームページをAIに開発させてみました。
AIのアウトプット品質や、仕様の伝わり方、タスク分解の精度などを検証するには、「現実に使うもの」を題材にするのが一番です。

結婚式のホームページ

前提条件

SDDを実践するため、「要件定義」「設計」「タスク分割」を明文化・フォーマット化しました。この準備が、AIの「暴走」を防ぐ最大のポイントです。

ディレクトリ構成

/sdd-verification
└── doc-sample/
    ├── requirements-sample.md
    ├── design-sample.md
    └── tasks-sample.md

要件定義

要件定義を効率よく、かつ抜け漏れなく行うためのスクリプトとドキュメントフォーマットです。

このフォーマットだけで全ての要件が網羅できるわけではありません。
特に技術要件やローカル開発のルールなどは、別途補足が必要です。
最初に人間がある程度完成度の高い要件をAIに渡すのが理想です。

スクリプト

私が作りたい結婚式のホームページについて、ビジネス仮説と要件を整理するために質問を10～15個投げかけてください。それに答えることで、本当に必要な機能と成功指標を明確にしたいです。質問した結果はdoc-sample/requirements-sample.md を参考にして、要件定義書のdoc/requirements.mdを作成してください。

ドキュメントフォーマット（requirements-sample.md）

# 要件定義（requirements.md）
## ビジネス仮説
[AI対話で導出された核心仮説]
## 概要
[アプリケーションの目的と機能概要]
## ユーザーストーリー
[実際の利用シーンを具体化]
## 要件
### 要件1
**ユーザストーリー**：[具体的な機能要件]
#### 受け入れ基準
1. WHEN [特定の条件] THEN [期待される結果] SHALL
2. GIVEN [前提条件] WHEN [アクション] THEN [期待される結果] SHALL
3. GIVEN [前提条件] AND [追加条件] WHEN [アクション] THEN [期待される結果] SHALL
4. GIVEN [前提条件] AND [追加条件] AND [さらに追加条件] WHEN [アクション] THEN [期待される結果] SHALL
### 要件2
**ユーザストーリー**：[別の機能要件]
#### 受け入れ基準
1. WHEN [特定の条件] THEN [期待される結果] SHALL
2. GIVEN [前提条件] WHEN [アクション] THEN [期待される結果] SHALL
3. GIVEN [前提条件] AND [追加条件] WHEN [アクション] THEN [期待される結果] SHALL
4. GIVEN [前提条件] AND [追加条件] AND [さらに追加条件] WHEN [アクション] THEN [期待される結果] SHALL
## KPI設計
### 主要指標
- [測定可能な成功指標]
### 副次指標  
- [補完的な測定指標]
## 技術要件
### 優先順位付き機能一覧
Week 1: [必須機能]
Week 2: [重要機能]
Week 3: [追加機能]
Week 4: [拡張機能]
## 受け入れ条件
[各機能の完了判定基準]

設計

設計をするためのスクリプトとドキュメントフォーマットは以下の通りです。

スクリプト

作成した要件定義（doc/requirements.md）の内容を基に、doc-sample/design-sample.mdを参考にして、設計書のdoc/design.mdの中を作成してください。

ドキュメントフォーマット（design-sample.md）

# 設計（design.md）

## 概要
[アプリケーションの目的と機能概要]

## アーキテクチャ
### システム構成
### レイヤー構造

## コンポーネントとインタフェース
### 主要コンポーネント

## データモデル

## エラーハンドリング

## テスト戦略
1. **ユニットテスト**
   - [各コンポーネントの単体テスト]

2. **統合テスト**
   - [コンポーネント間の連携テスト]

3. **E2Eテスト**
   - [ユーザーストーリーに基づくエンドツーエンドのテスト]
   - [主要なユーザフローのテストケース]
   - [受け入れ基準に基づくテスト]

## 技術スタック

## パフォーマンス考慮事項

タスク分割

タスクを明確にするためのスクリプトとドキュメントフォーマットは以下の通りです。

スクリプト

要件定義書（doc/requirements.md）と設計書（doc/design.md）を基に、doc-sample/tasks-sample.mdを参考にして、タスク（doc/tasks.md）を作成してください。

ドキュメントフォーマット（tasks-sample.md）

# 実装計画

- [ ] 1. [タスク1]

- [ ] 2. [タスク2]
- [ ] 2.1 [サブタスク1]
  - [ ] [サブタスク1の詳細]
  - _要件: 1.1, 1.2_

- [ ] 2.2 [サブタスク2]
  - [ ] [サブタスク2の詳細]
  - _要件: 1.3, 1.4_

- [ ] 3. [タスク3]
- [ ] 3.1 [サブタスク1]
  - [ ] [サブタスク1の詳細]
  - _要件: 2.1_

各ツールの結果

各フェーズごとに、AIツールの出力内容を比較しました。
質問の質・要件定義の網羅性・設計の深さ・タスク分解の粒度など、AIによるSDDの実力差を体感できます。

（以下、各ツールの詳細な出力内容は原文通り）

要件定義の出力結果

Windsurf

生成された質問

結婚式ホームページに関する質問（10-15個）

ビジネス仮説・目的について

このホームページの主な目的は何ですか？（例：ゲストへの情報提供、出席確認、思い出の共有など）

想定しているユーザー（ゲスト）はどのような方々ですか？（年齢層、ITリテラシー、関係性など）

従来の招待状や連絡方法と比べて、どのような課題を解決したいですか？

機能・コンテンツについて

必須で掲載したい情報は何ですか？（日時、場所、スケジュール、アクセス方法など）

**ゲストからの出席確認機能は必要ですか？**もし必要なら、どのような形式を想定していますか？

写真や動画の共有機能は必要ですか？（事前の思い出、当日の様子など）

ゲストからのメッセージ収集機能は必要ですか？（お祝いメッセージ、質問など）

多言語対応は必要ですか？（海外からのゲストがいる場合）

技術・運用について

ホームページの公開期間はどの程度を想定していますか？（結婚式前後の何ヶ月間など）

更新作業は誰が行いますか？（新郎新婦、家族、業者など）

スマートフォンでの閲覧が主になると思いますが、特に重視したいデバイスはありますか？

成功指標について

このホームページが成功したと判断する基準は何ですか？（出席確認の回収率、ゲストの満足度など）

ゲストにどのような体験を提供したいですか？（便利さ、楽しさ、感動など）

制約・その他

予算や開発期間に制約はありますか？

セキュリティやプライバシーで特に気をつけたい点はありますか？（パスワード保護、個人情報の取り扱いなど）

作成された要件定義書

要件定義（requirements.md）

ビジネス仮説

結婚式のゲストに対してデジタル招待状とインタラクティブな体験を提供することで、従来の紙の招待状よりも効率的で楽しい結婚式準備プロセスを実現できる。特に20～30代のゲストにとって、スマートフォンでアクセスできる便利で感動的な体験を提供することで、出席確認の回答率向上と結婚式への期待感醸成を図る。

概要

結婚式のゲスト向けホームページ。招待状機能、出席確認、お祝いメッセージ収集を中心とした、モバイルファーストのウェブアプリケーション。英語・日本語の多言語対応により、幅広いゲストに対応する。

ユーザーストーリー

ゲスト（友人・知人）: スマートフォンで招待状を確認し、出席可否を簡単に回答したい。結婚式の詳細情報やアクセス方法を手軽に確認したい。

ゲスト（両親世代）: 結婚式の基本情報を分かりやすく確認し、お祝いメッセージを送りたい。

新郎新婦: ゲストからの出席確認を効率的に収集し、結婚式準備を円滑に進めたい。

要件

要件1: 基本情報表示機能

ユーザストーリー: ゲストとして、結婚式の基本情報（日時、場所、スケジュール）を確認したい

受け入れ基準

WHEN ホームページにアクセス THEN 結婚式の日時が明確に表示される SHALL

GIVEN ホームページを開いた状態 WHEN 会場情報を確認 THEN 会場名、住所、地図が表示される SHALL

GIVEN 基本情報画面 WHEN アクセス方法を確認 THEN 最寄り駅からのルートが分かりやすく表示される SHALL

GIVEN 任意の時点 WHEN ページを開く THEN 結婚式までのカウントダウンが表示される SHALL

要件2: 出席確認機能

ユーザストーリー: ゲストとして、出席可否と参加人数を簡単に回答したい

受け入れ基準

WHEN 出席確認フォームにアクセス THEN 出席・欠席の選択肢が明確に表示される SHALL

GIVEN 出席を選択した状態 WHEN 人数を入力 THEN 参加人数を数値で入力できる SHALL

GIVEN フォーム入力完了 WHEN 送信ボタンを押下 THEN 回答が正常に送信され確認メッセージが表示される SHALL

GIVEN 回答済み WHEN 再度アクセス THEN 既に回答済みであることが分かる SHALL

要件3: お祝いメッセージ機能

ユーザストーリー: ゲストとして、新郎新婦にお祝いメッセージを送りたい

受け入れ基準

WHEN メッセージ投稿画面にアクセス THEN テキスト入力フィールドが表示される SHALL

GIVEN メッセージを入力した状態 WHEN 送信ボタンを押下 THEN メッセージが正常に送信される SHALL

GIVEN メッセージ一覧画面 WHEN 他のゲストのメッセージを確認 THEN 投稿されたメッセージが時系列で表示される SHALL

GIVEN 不適切なメッセージ WHEN 管理者が確認 THEN メッセージの削除・非表示が可能である SHALL

要件4: 多言語対応機能

ユーザストーリー: 英語圏のゲストとして、英語でホームページを利用したい

受け入れ基準

WHEN ページにアクセス THEN 言語切り替えボタンが表示される SHALL

GIVEN 言語切り替えボタンを押下 WHEN 英語を選択 THEN 全ての表示が英語に切り替わる SHALL

GIVEN 英語表示状態 WHEN フォームに入力 THEN 英語でのバリデーションメッセージが表示される SHALL

GIVEN 任意の言語設定 WHEN ページを再読み込み THEN 選択した言語設定が保持される SHALL

要件5: 写真・動画表示機能

ユーザストーリー: ゲストとして、新郎新婦の写真や動画を見て結婚式への期待を高めたい

受け入れ基準

WHEN 写真ギャラリーにアクセス THEN 新郎新婦の写真が美しく表示される SHALL

GIVEN 写真表示画面 WHEN 写真をタップ THEN 拡大表示される SHALL

GIVEN 動画コンテンツ WHEN 再生ボタンを押下 THEN 動画が正常に再生される SHALL

GIVEN モバイルデバイス WHEN メディアコンテンツを表示 THEN レスポンシブに最適化されて表示される SHALL

KPI設計

主要指標

出席確認の回答率: 90%以上

ページ訪問率: 招待ゲストの95%以上

お祝いメッセージ投稿率: 50%以上

副次指標

平均滞在時間: 3分以上

モバイルアクセス率: 80%以上

多言語機能利用率: 英語圏ゲストの90%以上

技術要件

優先順位付き機能一覧

Week 1: 基本情報表示、出席確認機能、レスポンシブデザイン
Week 2: お祝いメッセージ機能、写真ギャラリー
Week 3: 多言語対応、動画表示機能
Week 4: 管理画面、分析機能、パフォーマンス最適化

受け入れ条件

全機能がスマートフォンで正常に動作すること

日本語・英語の両言語で完全に利用可能であること

出席確認の回答データが管理者画面で確認できること

ページ読み込み時間が3秒以内であること

結婚式前後1ヶ月間の安定稼働が保証されること

Claude Code

生成された質問

ビジネス仮説・目的について

誰のための結婚式ホームページですか？（自分たちの結婚式 / 結婚式場の宣伝 / 結婚式企画サービス）

主なターゲットユーザーは誰ですか？（招待ゲスト / 新郎新婦の家族 / 一般の見込み客など）

このホームページで解決したい課題は何ですか？

機能・コンテンツについて

必須で含めたい情報・機能は何ですか？（招待状 / 会場案内 / スケジュール / 出席確認など）

ゲストからの出席確認やメッセージ収集は必要ですか？

写真ギャラリーや動画は掲載予定ですか？

リアルタイム更新が必要な情報はありますか？（天気予報 / 交通情報 / 当日の連絡事項など）

技術・運用について

想定される同時アクセス数はどれくらいですか？

スマートフォン対応は必須ですか？

多言語対応は必要ですか？（海外ゲストがいる場合）

運用期間はどれくらいを想定していますか？（結婚式前後の何ヶ月間？）

成功指標について

ホームページの成功をどのような指標で測りますか？（アクセス数 / 出席確認の回答率 / ゲストからの反応など）

予算の制約はありますか？

公開予定日はいつですか？

他に参考にしたい結婚式ホームページはありますか？

これらの質問への回答をお聞かせください。回答を基に、要件定義書を作成いたします。

作成された要件定義書

要件定義（requirements.md）

ビジネス仮説

結婚式の招待ゲストに対して、デジタルプラットフォームを通じて結婚式情報を共有し、出席確認やメッセージ収集を効率化することで、新郎新婦とゲストのコミュニケーションを向上させ、結婚式の準備プロセスを最適化できる。

概要

新郎新婦の結婚式専用ホームページ。招待ゲスト向けに結婚式の詳細情報を提供し、出席確認、メッセージ収集、リアルタイムコミュニケーション機能を提供する多言語対応（日本語・英語）のWebアプリケーション。

ユーザーストーリー

新郎新婦として、招待ゲストに結婚式の詳細情報を一元的に共有したい

招待ゲストとして、結婚式の詳細を確認し、出席可否を簡単に回答したい

招待ゲストとして、新郎新婦へのメッセージを投稿し、他のゲストの投稿も閲覧したい

海外ゲストとして、英語で結婚式情報を確認したい

要件

要件1: 結婚式基本情報表示

ユーザストーリー：招待ゲストとして、結婚式の基本情報（日時、場所、カウントダウン、地図）を確認したい

受け入れ基準

WHEN ホームページにアクセス THEN 結婚式の日時が表示される SHALL

GIVEN ホームページにアクセス WHEN 場所情報を確認 THEN 会場名と住所が表示される SHALL

GIVEN ホームページにアクセス WHEN カウントダウンを確認 THEN 結婚式までの残り日数が表示される SHALL

GIVEN ホームページにアクセス WHEN 地図を確認 THEN 会場位置が地図上に表示される SHALL

要件2: 出席確認機能

ユーザストーリー：招待ゲストとして、結婚式への出席可否を簡単に回答したい

受け入れ基準

WHEN 出席確認フォームにアクセス THEN 出席・欠席の選択肢が表示される SHALL

GIVEN 出席可否を選択 WHEN 送信ボタンをクリック THEN 回答が保存される SHALL

GIVEN 回答済み WHEN 再度アクセス THEN 前回の回答が表示される SHALL

GIVEN 管理者 WHEN 出席確認状況を確認 THEN 全ゲストの回答状況が表示される SHALL

要件3: メッセージ機能

ユーザストーリー：招待ゲストとして、新郎新婦へのメッセージを投稿し、他のゲストの投稿も閲覧したい

受け入れ基準

WHEN メッセージフォームにアクセス THEN メッセージ投稿欄が表示される SHALL

GIVEN メッセージを入力 WHEN 投稿ボタンをクリック THEN メッセージがリアルタイムで投稿される SHALL

GIVEN 投稿済みメッセージ WHEN メッセージ一覧を確認 THEN 全ての投稿がリアルタイムで表示される SHALL

GIVEN 新しいメッセージ投稿 WHEN 他のユーザーがページを表示 THEN リアルタイムで新しいメッセージが表示される SHALL

要件4: 多言語対応

ユーザストーリー：海外ゲストとして、英語で結婚式情報を確認したい

受け入れ基準

WHEN 言語切り替えボタンをクリック THEN 日本語・英語の切り替えができる SHALL

GIVEN 英語を選択 WHEN ページを表示 THEN 全ての情報が英語で表示される SHALL

GIVEN 日本語を選択 WHEN ページを表示 THEN 全ての情報が日本語で表示される SHALL

GIVEN 言語設定 WHEN 次回アクセス THEN 前回の言語設定が保持される SHALL

要件5: レスポンシブデザイン

ユーザストーリー：招待ゲストとして、スマートフォンから快適にアクセスしたい

受け入れ基準

WHEN スマートフォンでアクセス THEN レイアウトがモバイル最適化される SHALL

GIVEN タブレットでアクセス WHEN ページを表示 THEN 適切なレイアウトで表示される SHALL

GIVEN PCでアクセス WHEN ページを表示 THEN デスクトップ向けレイアウトで表示される SHALL

GIVEN 任意のデバイス WHEN フォーム操作 THEN 操作しやすいUIで表示される SHALL

KPI設計

主要指標

出席確認回答率（目標：90%以上）

メッセージ投稿数（招待ゲスト数の50%以上からの投稿）

副次指標

ページビュー数

平均滞在時間

言語別アクセス比率

デバイス別アクセス比率

技術要件

優先順位付き機能一覧

Week 1: 基本情報表示（日時、場所、カウントダウン、地図）、レスポンシブデザイン
Week 2: 出席確認機能、基本的なメッセージ機能
Week 3: メッセージのリアルタイム更新、多言語対応
Week 4: 管理者機能（出席状況確認、分析機能）

非機能要件

同時アクセス数：100人程度

運用期間：結婚式前後1ヶ月

対応ブラウザ：主要モダンブラウザ

セキュリティ：HTTPS対応、基本的なセキュリティ対策

受け入れ条件

全ての機能要件の受け入れ基準を満たすこと

レスポンシブデザインが適切に動作すること

多言語対応が正常に機能すること

リアルタイムメッセージ機能が安定して動作すること

100人の同時アクセスに対応できること

設計

Windsurf

作成された設計書

設計（design.md）

概要

結婚式ゲスト向けのモバイルファーストWebアプリケーション。招待状機能、出席確認、お祝いメッセージ収集を中心とし、日本語・英語の多言語対応を実現する。レスポンシブデザインによりスマートフォンでの最適な体験を提供し、新郎新婦の結婚式準備を効率化する。

アーキテクチャ

システム構成
[Frontend (React/Next.js)]
         ↓
[API Gateway]
         ↓
[Backend Services (Node.js/Express)]
         ↓
[Database (PostgreSQL)]
レイヤー構造

プレゼンテーション層: React/Next.js による SPA、多言語対応UI

API層: RESTful API、認証・バリデーション

ビジネスロジック層: 出席確認・メッセージ管理・通知機能

データアクセス層: ORM（Prisma）によるデータベース操作

データ層: PostgreSQL、画像・動画ストレージ（AWS S3）

コンポーネントとインタフェース

主要コンポーネント

フロントエンド

HomeComponent: 基本情報表示、カウントダウン

RSVPComponent: 出席確認フォーム

MessageComponent: お祝いメッセージ投稿・一覧

GalleryComponent: 写真・動画ギャラリー

LanguageSwitcher: 多言語切り替え

AdminDashboard: 管理者画面（出席状況・メッセージ管理）

バックエンド API

GET /api/wedding-info: 結婚式基本情報取得

POST /api/rsvp: 出席確認送信

GET /api/rsvp/:guestId: 出席状況確認

POST /api/messages: メッセージ投稿

GET /api/messages: メッセージ一覧取得

GET /api/gallery: 写真・動画一覧取得

GET /api/admin/dashboard: 管理者ダッシュボードデータ

データモデル

Wedding
CREATE TABLE weddings (
  id SERIAL PRIMARY KEY,
  bride_name VARCHAR(100) NOT NULL,
  groom_name VARCHAR(100) NOT NULL,
  wedding_date TIMESTAMP NOT NULL,
  venue_name VARCHAR(200) NOT NULL,
  venue_address TEXT NOT NULL,
  venue_map_url TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);
Guest
CREATE TABLE guests (
  id SERIAL PRIMARY KEY,
  wedding_id INTEGER REFERENCES weddings(id),
  name VARCHAR(100) NOT NULL,
  email VARCHAR(255),
  phone VARCHAR(50),
  guest_type VARCHAR(20) DEFAULT 'friend', -- friend, family
  created_at TIMESTAMP DEFAULT NOW()
);
RSVP
CREATE TABLE rsvps (
  id SERIAL PRIMARY KEY,
  guest_id INTEGER REFERENCES guests(id),
  wedding_id INTEGER REFERENCES weddings(id),
  attendance_status VARCHAR(20) NOT NULL, -- attending, not_attending
  guest_count INTEGER DEFAULT 1,
  dietary_restrictions TEXT,
  submitted_at TIMESTAMP DEFAULT NOW()
);
Message
CREATE TABLE messages (
  id SERIAL PRIMARY KEY,
  wedding_id INTEGER REFERENCES weddings(id),
  guest_name VARCHAR(100) NOT NULL,
  message_text TEXT NOT NULL,
  is_approved BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT NOW()
);
Media
CREATE TABLE media (
  id SERIAL PRIMARY KEY,
  wedding_id INTEGER REFERENCES weddings(id),
  file_url TEXT NOT NULL,
  file_type VARCHAR(20) NOT NULL, -- image, video
  caption TEXT,
  display_order INTEGER DEFAULT 0,
  created_at TIMESTAMP DEFAULT NOW()
);
エラーハンドリング

フロントエンド

ネットワークエラー: オフライン状態の検知と再試行機能

バリデーションエラー: リアルタイムフォームバリデーション

404エラー: カスタム404ページの表示

多言語エラーメッセージ: 選択言語に応じたエラー表示

バックエンド

400 Bad Request: 入力データバリデーションエラー

404 Not Found: リソースが見つからない場合

500 Internal Server Error: サーバー内部エラーのログ記録

レート制限: スパム防止のためのAPI呼び出し制限

テスト戦略

1. ユニットテスト

フロントエンド: Jest + React Testing Library

コンポーネントの描画テスト

ユーザーインタラクションテスト

多言語表示テスト

バックエンド: Jest + Supertest

API エンドポイントテスト

データベース操作テスト

バリデーションロジックテスト

2. 統合テスト

API統合テスト: フロントエンドとバックエンドの連携

データベース統合テスト: ORM とデータベースの整合性

外部サービス統合: 地図API、メール送信機能

3. E2Eテスト

出席確認フロー: ゲストが出席確認を完了するまでの全工程

メッセージ投稿フロー: メッセージ投稿から表示までの流れ

多言語切り替えフロー: 言語変更時の全画面表示確認

レスポンシブテスト: 各デバイスサイズでの表示・操作確認

管理者フロー: 出席状況確認とメッセージ管理

技術スタック

フロントエンド

Framework: Next.js 14 (React 18)

Styling: Tailwind CSS

多言語対応: next-i18next

状態管理: React Query + Zustand

フォーム: React Hook Form + Zod

地図: Google Maps API

バックエンド

Runtime: Node.js 18+

Framework: Express.js

ORM: Prisma

Database: PostgreSQL 15

認証: JWT

ファイルストレージ: AWS S3

メール送信: SendGrid

インフラ・デプロイ

Hosting: Vercel (Frontend), Railway (Backend)

Database: Railway PostgreSQL

CDN: Vercel Edge Network

監視: Vercel Analytics

パフォーマンス考慮事項

フロントエンド最適化

画像最適化: Next.js Image コンポーネント、WebP形式

コード分割: 動的インポートによるバンドルサイズ削減

キャッシュ戦略: SWR による効率的なデータフェッチ

プリロード: 重要リソースの事前読み込み

バックエンド最適化

データベースインデックス: 頻繁なクエリの最適化

API レスポンス圧縮: gzip圧縮の有効化

接続プール: データベース接続の効率化

レート制限: API呼び出し頻度の制御

目標パフォーマンス指標

First Contentful Paint: 1.5秒以下

Largest Contentful Paint: 2.5秒以下

Time to Interactive: 3.0秒以下

Cumulative Layout Shift: 0.1以下

API レスポンス時間: 200ms以下

Claude Code

作成された設計書

設計（design.md）

概要

結婚式専用ホームページは、新郎新婦と招待ゲスト間のコミュニケーションを円滑にするWebアプリケーションです。結婚式の基本情報提供、出席確認、リアルタイムメッセージ機能を提供し、日本語・英語の多言語対応とレスポンシブデザインを実現します。

アーキテクチャ

システム構成
[Frontend (React)] <-> [Backend API (Node.js/Express)] <-> [Database (MongoDB)]
                                |
                         [Real-time Server (Socket.io)]
レイヤー構造

プレゼンテーション層: React + TypeScript + Tailwind CSS

ビジネスロジック層: Node.js + Express + TypeScript

データアクセス層: MongoDB + Mongoose

リアルタイム通信層: Socket.io

コンポーネントとインタフェース

主要コンポーネント

フロントエンド

HomeComponent

結婚式基本情報表示

カウントダウン機能

地図表示

LanguageSwitcher

日本語・英語切り替え

言語設定の永続化

AttendanceForm

出席確認フォーム

回答状況表示

MessageBoard

メッセージ投稿フォーム

メッセージ一覧表示

リアルタイム更新

AdminPanel

出席状況管理

分析ダッシュボード

バックエンド

AuthController

ゲスト認証

セッション管理

AttendanceController

出席確認CRUD

出席状況集計

MessageController

メッセージCRUD

リアルタイム配信

WeddingInfoController

結婚式基本情報管理

データモデル

Guest（ゲスト）
interface Guest {
  id: string;
  name: string;
  email: string;
  language: 'ja' | 'en';
  createdAt: Date;
  updatedAt: Date;
}
Attendance（出席確認）
interface Attendance {
  id: string;
  guestId: string;
  status: 'attending' | 'not_attending' | 'pending';
  message?: string;
  createdAt: Date;
  updatedAt: Date;
}
Message（メッセージ）
interface Message {
  id: string;
  guestId: string;
  content: string;
  language: 'ja' | 'en';
  createdAt: Date;
  updatedAt: Date;
}
WeddingInfo（結婚式情報）
interface WeddingInfo {
  id: string;
  date: Date;
  venue: {
    name: string;
    address: string;
    coordinates: {
      lat: number;
      lng: number;
    };
  };
  couple: {
    bride: string;
    groom: string;
  };
  createdAt: Date;
  updatedAt: Date;
}
エラーハンドリング

フロントエンド

React Error Boundary による予期しないエラーのキャッチ

API通信エラーの適切な表示

フォームバリデーションエラーの表示

ネットワーク切断時の再接続処理

バックエンド

Global Error Handler による統一的なエラー処理

HTTP ステータスコードに基づく適切なレスポンス

データベースエラーのハンドリング

バリデーションエラーの詳細なメッセージ

テスト戦略

ユニットテスト

React コンポーネントのテスト（Jest + React Testing Library）

API エンドポイントのテスト（Jest + Supertest）

ビジネスロジック関数のテスト

データベースモデルのテスト

統合テスト

フロントエンド・バックエンド間のAPI通信テスト

データベース連携テスト

Socket.io リアルタイム通信テスト

多言語機能の統合テスト

E2Eテスト

ユーザーストーリーに基づくエンドツーエンドのテスト

主要なユーザフローのテストケース:

ホームページ閲覧 → 出席確認 → メッセージ投稿

言語切り替え → 各機能の動作確認

レスポンシブデザインの動作確認

受け入れ基準に基づくテスト:

出席確認回答率の計測

リアルタイムメッセージ更新の確認

100人同時アクセス時の動作確認

技術スタック

フロントエンド

Framework: React 18 + TypeScript

Styling: Tailwind CSS

State Management: React Context API + useReducer

Routing: React Router v6

HTTP Client: Axios

Real-time: Socket.io-client

Internationalization: react-i18next

Maps: Google Maps API / Leaflet

Build Tool: Vite

Testing: Jest + React Testing Library

バックエンド

Runtime: Node.js 18+

Framework: Express.js + TypeScript

Database: MongoDB

ODM: Mongoose

Real-time: Socket.io

Authentication: JWT + express-session

Validation: Joi

Logging: Winston

Testing: Jest + Supertest

インフラ・DevOps

Deployment: Docker + Docker Compose

Web Server: Nginx (reverse proxy)

Environment: dotenv

Process Manager: PM2

Monitoring: Basic health check endpoints

パフォーマンス考慮事項

フロントエンド最適化

React.memo によるコンポーネントの最適化

画像の遅延読み込み（Lazy Loading）

Bundle サイズの最適化（Code Splitting）

PWA 対応によるオフライン機能

バックエンド最適化

データベースクエリの最適化とインデックス設計

API レスポンスのキャッシュ戦略

Socket.io 接続数の効率的な管理

レート制限による DoS 攻撃対策

インフラ最適化

CDN によるアセット配信最適化

Gzip 圧縮によるデータ転送量削減

データベース接続プールの最適化

ヘルスチェックとログ監視

スケーラビリティ

水平スケーリング対応のステートレス設計

MongoDB レプリカセットによる可用性向上

Socket.io の Redis Adapter による多インスタンス対応

ロードバランサーによる負荷分散

タスク

Windsurf

作成されたタスク

実装計画

Week 1: 基盤構築・基本機能実装

1. プロジェクト初期設定

Next.js 14プロジェクト作成

Tailwind CSS設定

TypeScript設定

ESLint/Prettier設定

Git リポジトリ初期化

要件: 技術要件

2. バックエンド基盤構築

2.1 Express.js サーバー構築

プロジェクト初期化

基本ミドルウェア設定（CORS、JSON parser等）

環境変数設定

要件: アーキテクチャ

2.2 データベース設計・構築

PostgreSQL データベース作成

Prisma ORM設定

データベーススキーマ定義（Wedding, Guest, RSVP, Message, Media）

初期マイグレーション実行

要件: データモデル

3. 基本情報表示機能

3.1 フロントエンド実装

HomeComponent作成

結婚式基本情報表示UI

カウントダウン機能実装

レスポンシブデザイン対応

要件: 要件1

3.2 バックエンドAPI実装

GET /api/wedding-info エンドポイント作成

結婚式情報取得ロジック実装

エラーハンドリング実装

要件: 要件1

4. 出席確認機能

4.1 フロントエンド実装

RSVPComponent作成

出席確認フォームUI実装

フォームバリデーション（React Hook Form + Zod）

送信完了画面実装

要件: 要件2

4.2 バックエンドAPI実装

POST /api/rsvp エンドポイント作成

GET /api/rsvp/:guestId エンドポイント作成

出席確認データ保存・取得ロジック

重複送信防止機能

要件: 要件2

Week 2: メッセージ機能・写真ギャラリー

5. お祝いメッセージ機能

5.1 フロントエンド実装

MessageComponent作成

メッセージ投稿フォームUI

メッセージ一覧表示UI

リアルタイム更新機能（SWR）

要件: 要件3

5.2 バックエンドAPI実装

POST /api/messages エンドポイント作成

GET /api/messages エンドポイント作成

メッセージ承認機能（管理者用）

スパム防止機能（レート制限）

要件: 要件3

6. 写真・動画ギャラリー機能

6.1 フロントエンド実装

GalleryComponent作成

写真グリッド表示UI

画像拡大表示（モーダル）

動画再生機能

画像最適化（Next.js Image）

要件: 要件5

6.2 バックエンドAPI・ストレージ

GET /api/gallery エンドポイント作成

AWS S3 ストレージ設定

画像・動画アップロード機能（管理者用）

メディアファイル管理機能

要件: 要件5

7. 管理者機能基盤

7.1 認証システム

JWT認証実装

ログイン画面作成

認証ミドルウェア実装

要件: 管理機能

7.2 管理者ダッシュボード

AdminDashboard コンポーネント作成

出席状況一覧表示

メッセージ管理機能

統計情報表示

要件: 管理機能

Week 3: 多言語対応・動画機能・UI改善

8. 多言語対応機能

8.1 多言語システム構築

next-i18next 設定

日本語・英語翻訳ファイル作成

LanguageSwitcher コンポーネント作成

言語設定永続化

要件: 要件4

8.2 全画面多言語対応

全コンポーネントの多言語化

エラーメッセージ多言語化

フォームバリデーション多言語化

動的コンテンツ多言語化

要件: 要件4

9. 地図・アクセス情報機能

9.1 地図表示機能

Google Maps API 統合

会場位置マーカー表示

ルート案内機能

モバイル対応最適化

要件: 要件1

10. UI/UX改善

10.1 デザインシステム構築

カラーパレット・タイポグラフィ統一

コンポーネントライブラリ整備

アニメーション・トランジション追加

アクセシビリティ対応

要件: ユーザビリティ

10.2 モバイル最適化

タッチ操作最適化

画面サイズ別レイアウト調整

パフォーマンス最適化

PWA対応検討

要件: モバイルファースト

Week 4: 拡張機能・最適化・デプロイ

11. パフォーマンス最適化

11.1 フロントエンド最適化

コード分割・遅延読み込み実装

画像最適化（WebP対応）

キャッシュ戦略実装

バンドルサイズ最適化

要件: パフォーマンス

11.2 バックエンド最適化

データベースインデックス最適化

API レスポンス圧縮

接続プール設定

クエリ最適化

要件: パフォーマンス

12. テスト実装

12.1 ユニットテスト

フロントエンドコンポーネントテスト（Jest + React Testing Library）

バックエンドAPIテスト（Jest + Supertest）

ユーティリティ関数テスト

要件: テスト戦略

12.2 統合・E2Eテスト

API統合テスト実装

E2Eテストシナリオ作成（Playwright）

多言語機能テスト

レスポンシブテスト

要件: テスト戦略

13. デプロイ・運用準備

13.1 本番環境構築

Vercel フロントエンドデプロイ設定

Railway バックエンドデプロイ設定

Railway PostgreSQL 設定

環境変数設定

要件: インフラ

13.2 監視・分析設定

Vercel Analytics 設定

エラー監視設定

パフォーマンス監視設定

ログ管理設定

要件: 運用

14. 最終調整・リリース準備

14.1 品質保証

全機能動作確認

各デバイスでの表示確認

パフォーマンス指標確認

セキュリティチェック

要件: 受け入れ条件

14.2 ドキュメント整備

ユーザーマニュアル作成

管理者マニュアル作成

技術ドキュメント更新

デプロイ手順書作成

要件: ドキュメント

継続的改善タスク

15. 運用・保守

定期的なセキュリティアップデート

パフォーマンス監視・改善

ユーザーフィードバック収集・対応

機能追加・改善

要件: 継続的改善

Claude Code

生成されたタスク

実装計画

Week 1: 基盤構築と基本情報表示

1. プロジェクト初期設定

1.1 フロントエンド環境構築

React + TypeScript + Vite のセットアップ

Tailwind CSS の設定

React Router の設定

要件: レスポンシブデザイン

1.2 バックエンド環境構築

Node.js + Express + TypeScript のセットアップ

MongoDB 接続設定

基本的なミドルウェア設定

要件: 技術要件

2. 結婚式基本情報表示機能

2.1 フロントエンド - ホームコンポーネント

HomeComponent の実装

結婚式日時表示機能

会場情報表示機能

要件: 要件1.1, 要件1.2

2.2 カウントダウン機能

リアルタイムカウントダウンの実装

日数・時間・分・秒の表示

要件: 要件1.3

2.3 地図表示機能

Leaflet の統合

会場位置のマーカー表示

レスポンシブな地図表示

Google Maps連携ボタン

要件: 要件1.4

3. レスポンシブデザイン実装

3.1 モバイル対応

スマートフォン向けレイアウト

タッチ操作最適化

モバイルナビゲーションメニュー

要件: 要件5.1

3.2 タブレット・デスクトップ対応

タブレット向けレイアウト

デスクトップ向けレイアウト

レスポンシブグリッドレイアウト

要件: 要件5.2, 要件5.3

Week 2: 出席確認とメッセージ基盤

4. データベース設計と実装

4.1 データモデル定義

Guest モデルの実装

Attendance モデルの実装

Message モデルの実装

WeddingInfo モデルの実装

要件: 設計書データモデル

4.2 データベース接続とシード

MongoDB 接続設定

初期データの投入

インデックス設定

要件: パフォーマンス考慮事項

5. 出席確認機能

5.1 バックエンド API

AttendanceController の実装

出席確認 CRUD API

出席状況集計 API

要件: 要件2.2, 要件2.4

5.2 フロントエンド UI

AttendanceForm コンポーネント

出席・欠席選択UI

回答状況表示機能

要件: 要件2.1, 要件2.3

6. 基本メッセージ機能

6.1 バックエンド API

MessageController の実装

メッセージ CRUD API

メッセージ一覧取得 API

要件: 要件3.1

6.2 フロントエンド UI

MessageBoard コンポーネント

メッセージ投稿フォーム

メッセージ一覧表示

要件: 要件3.2, 要件3.3

Week 3: リアルタイム機能と多言語対応

7. リアルタイムメッセージ機能

7.1 Socket.io サーバー実装

Socket.io サーバー設定

メッセージ配信機能

接続管理機能

要件: 要件3.4

7.2 フロントエンド Socket.io 統合

Socket.io クライアント設定

リアルタイムメッセージ受信

接続状態管理

要件: 要件3.4

8. 多言語対応機能

8.1 国際化ライブラリ設定

react-i18next の設定

翻訳ファイルの作成（日本語・英語）

言語切り替えロジック

要件: 要件4.1, 要件4.4

8.2 多言語UI実装

LanguageSwitcher コンポーネント

全コンポーネントの多言語対応

日付・時刻の地域化

要件: 要件4.2, 要件4.3

9. エラーハンドリングとバリデーション

9.1 フロントエンドエラーハンドリング

Error Boundary の実装

API エラー表示機能

フォームバリデーション

要件: 設計書エラーハンドリング

9.2 バックエンドエラーハンドリング

Global Error Handler

バリデーションミドルウェア

ログ出力機能

要件: 設計書エラーハンドリング

Week 4: 管理機能とパフォーマンス最適化

10. 管理者機能

10.1 管理者認証

管理者ログイン機能

認証ミドルウェア

セッション管理

要件: KPI設計

10.2 管理ダッシュボード

AdminPanel コンポーネント

出席状況一覧表示

分析機能（回答率計算）

要件: KPI設計

11. パフォーマンス最適化

11.1 フロントエンド最適化

React.memo によるコンポーネント最適化

画像遅延読み込み

Code Splitting の実装

要件: パフォーマンス考慮事項

11.2 バックエンド最適化

データベースクエリ最適化

API レスポンスキャッシュ

レート制限の実装

要件: 100人同時アクセス対応

12. テスト実装

12.1 ユニットテスト

React コンポーネントテスト

API エンドポイントテスト

ビジネスロジックテスト

要件: テスト戦略

12.2 統合・E2Eテスト

API 統合テスト

Socket.io 通信テスト

E2E ユーザーフローテスト

要件: テスト戦略

最終週: デプロイと運用準備

13. デプロイメント

13.1 Docker 設定

フロントエンド Dockerfile

バックエンド Dockerfile

docker-compose.yml 設定

要件: 技術スタック

13.2 本番環境設定

環境変数設定

Nginx リバースプロキシ設定

HTTPS 設定

要件: 非機能要件

14. 最終検証

14.1 受け入れテスト

全要件の受け入れ基準確認

パフォーマンステスト（100人同時アクセス）

セキュリティチェック

要件: 受け入れ条件

14.2 ドキュメント整備

API ドキュメント作成

ユーザーマニュアル作成

運用マニュアル作成

要件: 運用準備

実装

各ツールの生成されたTasksに対して指示を出して実装を行います。

要件定義書（doc/requirements.md）と設計書（doc/design.md）を基にタスク（doc/tasks.md）を作成しているので、XXXX を実装してください。タスクが完了したら、タスク（doc/tasks.md）を更新してください。

各ツールの比較

検証内容に合わせて

リアルタイム・DevOps系機能の設計
- Claude Codeはリアルタイム通信やデプロイ、運用まで設計が細かい。
- Windsurfは設計の大枠をしっかり押さえるタイプ。
出力されるタスク分解の粒度
- Claude Codeはサブタスクや実装順序がより細かく、現場指示に近い。
- Windsurfは大項目単位でのタスク整理が得意。
UI/UXの使い勝手
- WindsurfはCascade内で自動スクロールされず、長い出力の確認がやや不便。
- Claude Codeは出力閲覧や編集のしやすさに優れる印象。
データモデルや設計思想の違い
- WindsurfはリレーショナルDB（PostgreSQL）＋Next.jsを推奨。
- Claude CodeはNoSQL（MongoDB）＋リアルタイム通信（Socket.io）を積極活用。
- → ツールごとに「推奨する技術スタック」や「設計思想」に違いが見られる。

気づき

AIの理解度は「仕様の明確さ」に大きく左右される
- どちらのツールも、指示が曖昧だとアウトプットも曖昧になりがち。
- 人間以上に「言葉の定義」が重要だと実感。
タスク分解やデータモデル設計の粒度に個性が出る
- Windsurfは設計がやや大枠、Claude Codeは細かいリアルタイム処理や管理機能までカバー。
- AIごとに得意な領域・苦手な領域が見えるのが面白い。
AI開発は「手戻り」が少なくなる一方で、最初の要件定義に時間をかける必要がある
- 仕様を徹底的に詰めることで、開発後の修正コストが大幅に減る。
自動生成された設計書やタスクは、そのまま現場で使えるレベルに近い
- ただし「人間の最終レビュー」はやはり不可欠。
- 微妙なニュアンスや運用ルールはAIだけでは補えない。
AIツールごとのUI/UXや操作性も、開発体験に影響する
- 例えばWindsurfのCascadeで自動スクロールされないのは、意外とストレスになる。
- Claude Codeはサクサク動くので実装していてストレスがかかりにくい。

まとめ

SDD（仕様駆動開発）は、AI時代の「開発の当たり前」になる可能性が高いと実感しました。

仕様を明文化し、構造化することが、AI開発の成功のカギ
AIツールごとに得意分野や出力のクセがあるので、人間のレビューと組み合わせるのがベスト
「仕様を書くのが面倒」と感じるかもしれませんが、最初に仕様を固めることで、後の開発・運用コストが激減します

今後もAI開発はますます進化しますが、
「仕様を言葉にする力」「要件を伝える力」 こそが、AI時代のエンジニアにとって最大の武器になると確信しています。

2025.8.9追記

今回はKiroをベースにした仕様駆動を実施しました。
しかしドキュメント数が少ないとAIの暴走は避けられない現実があります。
こちらのサイトで紹介されているドキュメントを書くことでより精度良くAIが使えるのではと思っています。

【Claude Code】マネできる！個人開発するときに最初に用意したドキュメント24種と機能要件書を全公開

付録・今後の展望

今回の検証内容やリポジトリは随時アップデート予定です
他のAIツールや、より複雑なプロダクトでも検証を続けていきます
SDDのノウハウやテンプレートも今後公開予定です
ご質問・ご感想など、お気軽にコメントください！
（もし本記事が参考になったら、シェア・ブックマークも大歓迎です）