AIと一緒に仕様書を書いてから実装する進め方｜要件の整理・タスクの分解・受け入れ条件

AIコーディングツールに「CSVで出力する機能を作って」と頼むと、短い時間で動くコードが出てきます。ところが、出力する項目や文字コード、該当データがないときの動作は、AIが推測で決めています。レビューの段階で「そういう仕様のつもりではなかった」と気づき、作り直すこともあります。

AIに実装を任せる前に、AIと一緒に仕様書を書き、受け入れ条件を決めてからタスクに分けて実装すると、作り直しの原因になる認識のずれを早く見つけられます。この記事では、仕様書のひな形、AIに質問させて抜けを探す方法、受け入れ条件の書き方、タスクの分解と実装・レビューの進め方を説明します。

仕様書を先に書く理由

AIコーディングツールは、指示に書かれていない部分をリポジトリの既存のコードや一般的な作り方から補います。補った内容が正しいこともありますが、業務の決まりや画面の使われ方はコードからは分かりません。

仕様書を先に書くと、AIが補う前に人が決めるべき点を洗い出せます。仕様書はレビューの基準にもなり、出てきたコードが仕様書の受け入れ条件を満たしているかで判断できます。仕様書から計画やタスクへ進める手順を支援するツールとして、GitHubが公開しているSpec Kitのようなオープンソースのツールキットもあります。ツールを使うかどうかにかかわらず、考え方は同じです。

仕様書のひな形

仕様書は長い文書にする必要はありません。次の項目を埋めれば、AIに実装を頼むときの前提として使えます。

【機能名】
【目的】誰の、どの作業を、どう変えたいか。
【利用者】この機能を使う人と、使える権限。
【範囲】今回作るもの / 今回は作らないもの。
【画面と操作】どの画面から、どの操作で使うか。
【データ】入力、出力、保存するデータの項目。
【エラーや例外のときの動作】データがない、権限がない、処理に失敗したときにどうなるか。
【受け入れ条件】完成したと判断する条件。
【未決事項】まだ決まっていないことと、決める人。

「今回は作らないもの」と「未決事項」の欄を必ず置きます。この二つがないと、AIは書かれていない部分を作り込んだり、決まっていないことを決まったものとして実装したりします。

AIに質問させて抜けを探す

ひな形を埋めたら、すぐに実装を頼まず、AIに仕様書を読ませて質問を出してもらいます。

次の仕様書を読み、実装を始める前に確認が必要な点を質問してください。
質問は、利用者・データ・エラー時の動作・既存機能への影響に分けてください。
仕様書から答えが分かる質問は出さないでください。
まだ実装はしないでください。

AIの質問には、すぐに答えられるもの、業務の担当者に確かめる必要があるもの、今回の範囲外にするものが混ざります。答えを「決めた」「保留」「範囲外」に分け、決めた内容は仕様書の該当する欄に、保留は未決事項の欄に、範囲外は「今回は作らないもの」に書き足します。

質問を一往復で終わらせず、仕様書を更新したらもう一度質問を出してもらいます。新しい質問が細かい表記の確認だけになったら、実装に進む目安になります。

受け入れ条件の書き方

受け入れ条件は、完成したかどうかを第三者が確かめられる文にします。「使いやすい」「速い」のような書き方では、レビューのときに判断できません。

受け入れ条件は、そのままテストの観点になります。AIにテストを書かせるときも、受け入れ条件を渡すと、仕様に沿ったテストを作りやすくなります。テストの確かめ方は、テストコードの作成にAIを使うときの注意点を参照してください。

タスクに分解する

仕様書が固まったら、実装をタスクに分けます。一つのタスクは、一つのプルリクエストでレビューできる大きさにします。各タスクには、変更する場所、完了条件、先に終わっている必要のあるタスクを書きます。

タスクの分解もAIに下書きさせることができます。仕様書を渡して「受け入れ条件ごとに、どのタスクで満たすかが分かるように分けて」と依頼し、出てきた一覧から、受け入れ条件のどれにも対応しないタスクや、どのタスクにも含まれない受け入れ条件がないかを確かめます。

出荷予定のCSV出力を作る想定例

ここからは想定例です。受注管理アプリを開発しているチームで、開発者が「出荷予定をCSVで出力する」機能を担当します。開発者は倉庫担当者から聞いた要望をもとにひな形を埋め、AIに質問を出してもらいます。

AIからは、「出力する期間の指定方法は」「文字コードは何を使うか」「キャンセル済みの注文を含めるか」「出力件数が多いときに分割するか」といった質問が返ってきます。開発者は文字コードとキャンセル済みの扱いを倉庫担当者に確かめて仕様書に書き、件数が多いときの分割は今回は作らないものに入れます。

タスクは、出荷予定を期間で取得する処理、CSVを作る処理、画面のボタンと権限の制御、の三つに分けます。開発者はタスクを一つずつAIに実装させ、プルリクエストごとに受け入れ条件と照らし合わせてレビューします。

実装とレビューの進め方

実装を頼むときは、仕様書全体と、今回のタスクの範囲を一緒に渡します。仕様書の置き場所や、AIに毎回読ませたい前提は、リポジトリにAI向けの指示書を置くときの書き方で説明した指示書から参照できるようにしておきます。

レビューでは、タスクの完了条件と受け入れ条件を満たしているか、タスクの範囲外の変更がないかを確かめます。レビューの手順はAIが書いたコードのレビュー手順にまとめています。

実装の途中で仕様の変更が必要になったら、コードだけを直さず、先に仕様書を更新します。仕様書とコードの内容が食い違ったままになると、次のタスクでAIが古い仕様書に沿って実装してしまうためです。

まとめ

AIに実装を任せる前に、目的、範囲、操作、データ、エラー時の動作、受け入れ条件を仕様書に書きます。AIに質問させて抜けを探し、答えを決めた・保留・範囲外に分けて仕様書へ反映してください。タスクは一つずつ実装してレビューし、途中で決めたことは仕様書に戻して記録します。

e-GrantsのAI開発環境の導入・整備では、Codex・Claude Code・GitHub Copilotの導入を支援し、チームの開発の進め方に合わせて設定と運用ルールを整えます。仕様書のひな形やレビューの手順を含めて、AIと開発を進める方法をチームで決めたい場合はご相談ください。一宮市・名古屋市・愛知県を中心に、オンラインで全国からご相談いただけます。