Spec Firstとは：AI実装の手戻りを減らす仕様設計
この記事で学べること
- AI実装を仕様なしで始めたときに手戻りが起きる理由
- 作るもの、動作、作らないものを実装前に合意する仕様の書き方
- 仕様作成の手間と、変更リスクに応じてSpec Firstを適用する判断基準
Spec FirstでAI実装前に合意範囲を固定する
AI実装の手戻りは、指示の詳しさより先に、作るもの、期待する動作、作らないものを合意できているかで変わります。このサイトでは、実装前にその3点を確認すると、動いていても意図と違う変更を見つけやすくなりました。Spec Firstは、変更リスクに応じて実装前の合意範囲を固定する進め方です。
この記事では、「どの変更で仕様を先に書き、何を合意すれば手戻りを減らせるか」という問いに焦点を当て、結論を分ける判断軸、適用条件、最初に確認する事項を扱います。
最後まで読むと、「どの変更で仕様を先に書き、何を合意すれば手戻りを減らせるか」という問いを、自分の状況に照らして判断するための材料を持ち帰れます。
目的・範囲・非対象を実装前に固定する
「このページにお問い合わせフォームを追加してほしい」——こう伝えてAIに実装を依頼した場合、AIは「お問い合わせフォーム」として一般的なものを実装します。必要なフィールド、送信後の動作、エラー表示の方法など、すべてAIが自分の解釈で決めます。
できあがったものを見ると、「メールアドレス入力欄がない」「送信後に確認画面ではなくサンキューページへ飛ぶ仕様になっている」「想定と別のデザインになっている」といった状況が起きます。修正を依頼するたびに新たな調整が必要になり、最終的に意図に近いものができるまでに数回のやり取りが必要になります。
この繰り返しは、最初の指示に「何を作るか」の定義が含まれていなかったことが原因です。
Spec Firstは実装前に目的・範囲・非対象を合意する
本記事でいうSpec Firstは、特定企業が定義した単一の標準手法ではなく、AIに実装を依頼する前に要件・制約・受入条件を明文化する進め方を指します。仕様書といっても、正式な文書形式である必要はありません。「何を作るか」「どう動くか」「何をしないか」の3点を書き出すだけで、AIとの認識合わせが最初の段階で完了します。
私がこのサイトで新しい機能を追加するときは、実装の前に必ずこの3点を整理します。たとえばフォームの例であれば、次のように書きます。
## お問い合わせフォームの仕様
### 何を作るか
- 名前・メールアドレス・メッセージを入力できるフォーム
- 送信ボタンを1つ設置する
### どう動くか
- 送信後は同ページ内に「送信しました」というテキストを表示する
- バリデーション：名前・メールアドレスは必須、メールアドレスはフォーマットチェックあり
### 何をしないか
- 外部サービスへの連携はしない（この実装では送信後の処理は不要）
- デザインの変更は含まない（既存のスタイルをそのまま使う）仕様書があることで何が変わるか
AIとの認識合わせが最初に終わる
仕様書を渡すと、AIは実装を始める前に「理解した通りに進めます」または「この点を確認させてください」と返します。実装を始める前に認識のずれを検出できるため、「できあがってみたら違った」という状況が起きにくくなります。
レビューの基準が明確になる
実装が完了したあと、「仕様書に書いた通りに動いているか」を確認するだけでレビューができます。仕様書がない場合、「何が正しい動作か」の判断が毎回必要になります。
修正の範囲が限定される
仕様書があると、修正依頼も「仕様書のこの部分を変えたい」という形で出せます。仕様書なしで修正を重ねると、AIが前の修正との整合性を保てないまま変更を加えることがあります。
仕様書を書く手間との兼ね合い
「仕様書を書くのに時間がかかる」という点は、実際にそのとおりです。小さな修正（テキストを変える、色を変えるなど）に毎回仕様書は必要ありません。
仕様書が有効なのは、「複数の要素を含む実装」「AIが選択肢を持つ実装」「後で変更が生じる可能性がある実装」です。作業の規模と複雑さに応じて判断します。
まとめ：目的・動作・非対象を合意してから実装を始める
本記事でいうSpec Firstは「最初に仕様書を書くことで、実装後の修正回数を減らす」という進め方です。書く内容は「何を作るか」「どう動くか」「何をしないか」の3点から始められます。AIへの指示精度を上げる前に、まず「何を作るか」を自分自身で整理する習慣が、AIとの作業を安定させる出発点になります。
最初に次の変更について、作るもの、動作、非対象を各1文で書いてください。影響が小さく簡単に戻せる試作では詳細な仕様書が過剰になるため、変更リスクに合わせて記述量を調整します。