🎫

【Part 2】仕様駆動テンプレートを改善してやりとりを70%削減

に公開
Go
TypeScript
Claude
SDD
Antigravity
tech

仕様駆動でフロントエンド・バックエンドを同時開発すると、連携部分でバグが頻発する問題がありました。本記事では、テンプレートを3回ブラッシュアップしてこの問題を軽減し、AIとのやりとり回数を130回から37回まで削減した方法を紹介します。

成果物・主な機能

機能 スクリーンショット
ダッシュボード alt text
プロジェクト管理 alt text
チケット管理 alt text

開発環境

項目 内容
使用モデル Claude Opus 4.5
使用ツール Antigravity
技術スタック Go + DynamoDB + Vite + TypeScript

作業期間

回 目的 期間
1回目 テンプレート活用で完走＋ブラッシュアップ 2025/12/27 - 2026/01/02
2回目 さらなるテンプレートブラッシュアップ 2026/01/03 - 2026/01/07
3回目 ブラッシュアップしたテンプレートで完走 2026/01/07 - 2026/01/09

解決したかった課題（Before）

前回作成した仕様駆動用テンプレートを使っても、以下の問題が残っていました。

課題 状況 試したこと
フロントエンドとバックエンドの不一致 連携部分でエラーが頻発 フロントエンド先行開発フロー
バニラJSの構文エラー ビルド時に検知できず実行時に発覚 Vite + TypeScript
要件定義の品質にムラがある テンプレート活用前は不安定だった テンプレートへの学びの反映

解決策と結果（After）

1. フロントエンド先行開発フローの採用

従来は機能ごとにフロントエンド・バックエンドを同時に実装していましたが、フロントエンドを先に完成させるフローに変更しました。

Phase 1: 環境構築
    ↓
Phase 2: ハンドラー・スタブサービス作成
    ↓
Phase 3: フロントエンド作成
    ↓
【人間レビュー】全体の使用感を確認、見た目について指摘
    ↓
Phase 4〜: 機能別バックエンド実装（ユニットテスト含む）
    ↓
【人間レビュー】機能の使用感を確認、バグや操作性について指摘

効果: 先にフロントエンドのエラーを潰せるため、「フロントエンドにもバックエンドにもバグがある」という状況を回避できました。

残った課題: requirements.md → designs.md の段階で、バックエンドAPIはあるがフロントエンド側に対応する画面がない状態がどうしても発生しました。designs.md は膨大なドキュメントになるため、人間がこの段階で全ての矛盾に気づくのは困難です。結局、フロントエンドを実際に触った段階で問題に気づくことになります。

2. Vite + TypeScript の採用

バニラJSでは構文エラーが実行時まで発覚しませんでしたが、Vite + TypeScriptの構成にすることでビルド時にエラーを検知できるようになり、品質が安定しました。

3. テンプレートへの学びの反映

各Phase完了後にAIとふりかえりを行い、発生したバグの原因を分析してテンプレートに反映しました。

# ふりかえりプロンプト例
Phase 3: フロントエンド作成の作業のふりかえりをします。
以下にやりとりをまとめているのでバグが発生した原因を分析してください。
`@[docs_forAI/Phase3-log.md]` ※Antigravityのファイル参照記法

学んだこと・工夫したポイント

ユニットテストの指示方法

tasks.mdに詳細を記載しなくても、以下のような指示で想定通りのユニットテストを作成できました。

Phase Xの作業を進めてください。
docs/tasks-phases.md のとおりに実装やテストを作成できなかった場合は、
作業終了後に必ず報告してください。
このPhaseで作成するAPIについて、フロントエンドから呼び出しがない場合は、
作業終了後に必ず報告してください。
手動で動作確認するので作業完了後動作確認手順を教えてください。
mockioの利用方法は [ドキュメントのフルパス] のドキュメントを参照してください。

テスト要件
- サービス層は**カバレッジ100%**を目指してください
- 正常系・異常系の両方をテストしてください
- mockioを使用してリポジトリをモックしてください

UIライブラリの活用

フロントエンドの見た目用にUIライブラリを使うと、AIがライブラリに準拠した見た目を作ってくれるため、デザインのコントロールがしやすくなりました。

限界と注意点

DynamoDB設計の注意点

AIはDynamoDBの設計において以下の点が苦手でした。

  • Query vs Scan の判断: GSI（グローバルセカンダリインデックス）を考慮せず、フルスキャンが必要なPK/SKパターンで設計してしまう
  • ソート順: 明示的に指定しないと、直感と異なるソート順が採用されるケースがある

まとめ

項目 結果
やりとり回数 130回 → 37回（約70%削減）
品質 TypeScript導入でビルド時エラー検知が可能に
開発フロー フロントエンド先行開発でバグの早期発見

Discussion