AIで実装前のコード要件を整理する方法｜入力と出力を先に決める

AIにコードを書かせる前に、要件を「誰が何を完了するか」「入力と出力は何か」「失敗時に何を返すか」まで決めます。「検索機能を作る」だけでは完成か判断できません。対象ユーザー、受け入れる入力、観測できる結果、既存システムとの接点、変えてはいけない条件、完了確認を一枚のBriefへまとめます。コード生成より先に、Planと未確定事項を人が確認してください。

要件を実装可能な単位に分ける

依頼を読んだ開発者が質問しなくても同じ振る舞いを想像できるかを確認します。利用者の目的、対象画面やAPI、既存状態、必要な変更、対象外を分けます。「登録できる」なら、何を登録し、保存先はどこか、重複時にどう扱うか、失敗時に利用者へ何を示すかを定義します。

表は横にスクロールできます

項目	記入する内容	確認できる証拠
User outcome	誰が何を完了するか	UIの状態や処理結果
Input	型、必須、許容値、文字数等	schema / validation
Output	画面、return、保存、HTTP応答	観測できる結果
Error / empty	不正値、未登録、権限、timeout	error path
Existing touchpoint	route、component、API、data	関連箇所
Constraint	変えない契約、依存、互換性	regression check
Done	pass条件、対象環境	test / acceptance

この表は要件の骨格です。すべての欄に技術詳細を埋める必要はありませんが、利用者の判断やデータ安全性を左右する欄を空欄のまま実装へ進めないようにします。まだ決まっていない点は「未決」と明示し、AIに勝手に仕様を補完させないことが大切です。

曖昧な要件を例へ直す

「検索する」なら、検索対象、部分一致か完全一致か、大文字小文字の扱い、空文字、0件、複数件、検索結果の並び、URL共有の要否を決めます。「通知する」なら、誰へ、何を契機に、重複通知をどう抑え、失敗後に再送するかを決めます。

表は横にスクロールできます

入力	期待結果	境界・例外
有効なkeyword	条件に合う結果を表示	何件まで、順序
空欄	初期状態または案内	全件表示の可否
該当なし	0件表示と次Action	検索条件を戻せる
不正な値	validation message	保存や送信をしない

これらは例です。既存製品や実装を見ずに具体動作を決めたことにはしません。利用者へ影響する基準はProduct ownerが確定し、AIは整理した候補を提示します。

例外経路とデータ契約

正常系だけの要件は、実装後にpermission不足やnetwork障害の扱いが抜けがちです。入力不足、重複、認証切れ、権限、timeout、rate limit、外部API障害、空データ、再試行など、起こり得る経路を選びます。それぞれで画面表示、ログ、再試行可否、保存状態、サポートに必要な情報を定義します。

Dataの読み書きに触れる変更では、schema、既存レコード、互換性、migration、削除・上書きの挙動を明示します。機密情報をpromptへ貼らず、必要最小限の匿名化した例を用います。認証情報、個人情報、production dataを含むテスト値は、許可された安全な環境で扱い、logに出さない条件もBriefへ入れてください。

Acceptance Criteriaを書く

「動作する」ではなく、Given / When / Thenまたは箇条書きで、確認できる条件を作ります。

• どの前提で処理を始めるか。

• どの操作をすると、どの結果が見えるか。

• どのerror条件で、何が表示・保存されないか。

• 既存の主要経路が維持されることをどう確認するか。

• desktop/mobileや権限別の対象をどこまで見るか。

Acceptance Criteriaには実装方法ではなく、利用者が確認できる成果を書きます。たとえば内部関数名ではなく、画面上のlabelや表示状態で記述します。テスト不能な言葉（速い、便利、直感的など）だけで終わらせず、測定またはreview方法を添えます。

Planをreviewしてから生成する

CursorのPlan Modeは、コードを書く前にcodebaseを調べ、計画を作成・reviewする機能として公式に案内されています。使える環境では、AIに関連file、既存契約、影響範囲、test案を列挙させます。これは現在のCursor機能説明であり、すべてのAI coding toolや契約に同じ機能があるわけではありません。Planを人が修正し、変更範囲・依存・data migration・security・rollbackを確定してから実装へ進みます。

AIのPlanには存在しないfileやAPI、誤った前提が混ざることがあります。repo内の実体とREADME、schema、testsを確認し、存在しない項目を追加前提にしないでください。要求が矛盾する場合は、重要な変更制約と利用者の目的を明らかにし、仕様を黙って決めないようにします。

依頼Promptの雛形

Outcome：[利用者が達成すること]

対象：[画面 / route / API]

Current behavior：[確認済みの現状]

Input：[型、必須、例]

Output：[成功時に利用者が見る状態]

Errors：[失敗条件と期待動作]

Constraints：[変更禁止の既存契約]

Done criteria：[検証できる条件]

未決事項：[AIに推測させない項目]

関連資料：[schema、既存API、test、画面]

まずPlanと不足情報を提示し、確認後に実装案を作成。

Draftを見るときは、要求漏れ、不要なscope拡大、既存契約、data破壊可能性、検証不足を確認します。単に手順がもっともらしいかではなく、利用者の成功条件を満たし、失敗時の責任が定義されているかを見ます。

実装後の確認を先に設計する

Acceptance Criteriaをtest caseへ変換します。正常系、空、境界、error、権限、連携失敗、既存動作に分け、UI testだけで足りるか、API contractやunit検証が必要かを考えます。Test dataは匿名化し、実Productionへ操作しない条件を明記します。

表は横にスクロールできます

Criterion	Test	環境	合否
有効な検索が結果を返す	入力例を送信し結果を確認	test data
0件で次Actionが分かる	no-match例を入力	test data
権限なしで保存されない	未許可userで試す	isolated test
既存routeが維持される	regression test	local / preview

コード生成の後、差分をreviewし、必要なtest、type、lint、buildを実行します。通ったcheckと未実施checkを分け、していない操作を「確認済み」と書きません。

AIものさしの判断

要件表とAcceptance Criteriaから実装の成功・失敗を判断できるなら、Planのreviewへ進みます。Product仕様、権限、data migrationなど重要条件が未確定なら、code generationの前に決定者へ戻します。AIは曖昧さを埋める主体ではなく、既知情報を整理し、質問と選択肢を可視化する補助として使います。

実装Briefをreviewする順番

1. 利用者の目的と対象画面が一致しているか読む。

2. 必須Inputと未決のInputを分け、空値・不正値の結果を見る。

3. 成功時と失敗時に観測できるOutputが定義されているか確認する。

4. 既存route、API、schema、権限、analytics等の不変条件を列挙する。

5. data更新、外部送信、通知など副作用と再試行条件を確認する。

6. Acceptance Criteriaをtest caseへ変換し、実施環境を指定する。

7. Scope外の希望を切り分け、今回の完了条件へ混ぜない。

この順番にすれば、見た目の変更から始めて利用者の仕事や保存条件を決め忘れる事態を減らせます。条件が決まらないなら、実装の仮定として埋めず、質問または選択肢として記録します。

Requirementの変更管理

実装中に要件が増えた場合、元のAcceptance Criteria、追加理由、影響するdata・route・testを比較します。追加の要件を同じPRへ含めるか、別の変更に分けるかは既存のrelease手順に従い、単にAIが関連しそうと提案した変更をscopeへ加えません。

レビュー時は、要件の一文と実装差分、テスト証拠を対応づけます。実装者が「想定していた」と説明しても、文書にない動作は利用者が保証されていない可能性があります。決定された契約はownerと確認日を記録し、後から基準が変わったときに再検討できる形にします。

変更対象を小さくする

AIへ渡す資料が多ければ精度が上がるとは限りません。依頼に必要なroute、API、schema、testだけを選び、関連しない過去案や秘密情報は外します。変更禁止の契約をBriefへ明記し、コード差分で実際に変更されたfileと照らします。AIの提案に新規dependency、DB migration、外部連携が含まれるなら、必要性と影響を人が別途判断してください。