要件定義にCodexを使う方法｜仕様整理と確認手順を実務で

要件定義にCodexを使う意味

要件定義は、利用者の要望をそのままコードへ変換する作業ではありません。何の問題を解くのか、誰がどの場面で使うのか、どこまでを今回の対象にするのかを決め、実装後に「できた」と判定できる言葉へ置き換える作業です。Codexはリポジトリ内のファイルを読み、似た機能や既存の制約を探し、仕様の抜けを質問にできます。しかし、会社やサービスとして何を優先するか、例外をどこまで許容するか、利用者にとって本当に価値があるかは、担当者が判断する領域です。

GPT-5.6の提供開始後は、短いコード補完だけでなく、複数のファイルや長い作業の流れを含む依頼を考えやすくなりました。Codex CLI 0.146.0でもセッション名、スレッドの固定、横の会話、スキル関連の扱いなどが更新されています。これは要件定義を丸ごと委ねればよいという意味ではなく、調査結果、仕様案、確認記録を段階的に扱いやすくなったという意味です。新しい機能に期待するほど、最初に「何を成果物とするか」を決めることが重要になります。

要件定義と実装依頼を分ける

「会員登録を改善して」と依頼すると、Codexは画面の変更、入力項目の追加、データ構造の修正、通知の導入など複数の解釈を持てます。要件定義では、まず会員登録のどの問題を解くのかを定めます。入力途中で離脱する人を減らしたいのか、登録後の確認を分かりやすくしたいのかで、調べるファイルも測る指標も変わるからです。

実装依頼は「決まった仕様をリポジトリへ反映する依頼」、要件定義は「何を決めるべきかを明らかにする依頼」と考えると整理しやすくなります。前者では変更対象と検査方法を指定し、後者では現状の根拠、不明点、選択肢を出してもらいます。二つを分ければ、まだ決まっていない判断をコードの差分で済ませる事故を避けられます。

Codexに任せる調査と人が決めること

Codexには、画面からデータ保存までの経路を追うこと、既存の入力検証を探すこと、関連するテストを列挙すること、仕様案の矛盾を指摘することを任せられます。特に、初めて触るリポジトリでファイルの位置を探す作業や、同じ名前の処理を比較する作業は、要件定義の初動を速くします。

一方で、対象範囲の最終決定、優先順位、利用者への説明、失敗時に許容する動作、公開時期は人が決めます。Codexが「既存の書き方に合わせる」と提案しても、既存の振る舞いが今回の目的に合うとは限りません。調査結果は事実、推測、提案の三つに分けて読ませると、判断の境界が見えます。

成果物を先に決める

要件定義を始める前に、最終的に残す文書の形を決めます。長い文章だけを作ると、読み手によって重要な部分が変わってしまいます。最低限、目的、対象となる利用者と場面、現状の問題、対象範囲、対象外、必要な入力と出力、受け入れ条件、未決事項を一つの場所に置きます。文章の量を増やすことより、後から同じ判定ができることが大切です。

たとえば「検索結果を改善する」というテーマなら、検索対象、検索語の扱い、結果がない場合の表示、並び順、既存利用者への影響まで書きます。画面の見た目だけを要件にしないで、どのデータを受け取り、どんな結果を返し、異常時に何を表示するかまで含めます。こうするとCodexは、見た目に関するファイルだけでなく、入力検証、取得処理、テストの位置も調べられます。

目的・対象・範囲を一文で固定する

目的は「機能を追加する」ではなく、「誰のどんな負担を減らし、どの状態を実現するか」で書きます。対象は利用者の属性を抽象的なラベルで決めるのではなく、操作する人と場面で表します。たとえば「初回利用者が、スマートフォンで、登録途中から再開できるようにする」のように、行動と条件が含まれる文にします。

範囲は、今回変更する部分と変更しない部分の境界です。登録画面だけを対象にするなら、請求情報や退会処理を対象外として明記します。対象外は余計な情報ではありません。Codexが関連ファイルを見つけたときに、どこまで変更提案を広げてよいかを決める重要な境界です。

必須条件と希望条件を分ける

すべての要望を同じ重さで書くと、Codexも読み手も優先順位を判定できません。サービスが動くために絶対必要な条件、今回できれば入れたい条件、将来検討する条件を分けます。「未入力なら次へ進めない」は必須でも、「入力欄の補助文を変える」は希望かもしれません。分類の根拠を一行添えると、実装中に迷ったときに戻れます。

条件を分けるときは、担当者の好みだけでなく、利用者への影響、既存データとの互換性、確認に必要な時間を見ます。難しい条件を必須にするなら、簡単な条件を後回しにする判断も必要です。Codexには分類案を作らせても、最終的な優先順位はレビュー担当者が決め、決定理由を残します。

受け入れ条件を判定できる形にする

「使いやすくする」「安全にする」「速くする」は方向性を示しますが、完了判定には向きません。「入力を保存して再表示できる」「不正な値では保存されず、利用者に修正箇所が伝わる」「既存の利用者が従来の操作を続けられる」のように、確認できる動作へ変えます。数値を置ける場合は、表示時間、件数、対象画面などの条件も添えます。

受け入れ条件は、実装者のためだけでなく、レビュー担当者が差分を読むときの基準です。条件ごとに確認方法を考え、画面確認、テスト、ログ、手作業のいずれで判定するかを書きます。判定方法が決まらない条件は、まだ要件として曖昧なので、実装前の質問に戻します。

要件定義を進める手順

ここでは、要件定義 codexを使うときの具体的な順序を示します。最初から実装を依頼するのではなく、各段階で短い成果物を確認します。途中で前提が変わったら、後続の文章だけを書き換えず、目的や対象範囲まで戻って整合性を見直してください。

この順序は、担当者とCodexの役割を切り替える目印にもなります。背景と範囲は人が決め、現状の確認はCodexに補助させ、受け入れ条件は人が確定し、提案の影響は一緒に読みます。段階ごとに「次へ進める条件」を置けば、曖昧なまま変更が広がることを防げます。

Step 1: 背景を一文で固定する

最初に、困っている状況と実現したい状態を一文にします。「利用者が何をしたいのか」「現在どこで止まるのか」「変更後に何ができればよいのか」を入れると、機能名だけの依頼になりません。背景が一文で書けない場合は、要望が複数混ざっている可能性があります。

依頼文には、発見した事実と推測を分けて書きます。「登録画面の二つ目の入力で離脱が多い」は観測した事実、「説明文が原因かもしれない」は仮説です。仮説を事実として渡すと、Codexがその前提に合うファイルだけを探すため、別の原因を見逃します。

Step 2: 現状を証拠付きで整理する

次に、関係する画面、入口、データ、権限、エラーメッセージ、既存テストを調べます。ファイル名を先に決め打ちせず、「登録」という語を使う場所、ルートから処理へ進む経路、保存前後の変換を追ってもらいます。調査結果にはファイル名や行の位置を添え、実際に確認できた事実として記録します。

既存の仕様書がある場合は、実際のコードと一致するか確認します。文書が古いときは、どちらを正とするかを決めずに「文書と実装の差」として出します。Codexには差分の理由を推測させてもよいですが、推測には確度を付け、担当者が追加確認する項目として残してください。

Step 3: 入力と出力を決める

機能の前後にある情報を、利用者の入力、システムが参照する情報、保存する情報、表示する結果に分けます。入力値の型、必須かどうか、長さ、使用できない値、未入力時の扱いを決めると、要件が画面説明だけで終わりません。出力は成功時だけでなく、該当なし、入力誤り、権限不足、通信失敗などを含めます。

「入力を受け取る」と書いたら、どこで検証するか、エラーを誰にどう伝えるかまで続けます。値を保存するなら、再表示時の形式、既存データとの互換性、重複した場合の扱いも確認します。Codexにはこの項目を表にまとめさせることもできますが、最終文書では意味が伝わる説明を添えます。

Step 4: 受け入れ条件を例に変える

抽象的な条件を、具体的な入力と期待する結果へ変えます。正常な入力、境界に近い入力、空の入力、形式が違う入力、同じ操作を繰り返す場合を一つずつ考えます。条件が五つあるなら、少なくとも各条件をどう確認するかを一つずつ用意し、確認できない条件を残さないようにします。

例を書くときは、画面に表示される文言だけでなく、保存や次の画面への遷移も含めます。表示が正しくても保存されていなければ要件を満たしません。反対に、内部の実装方法を細かく固定しすぎると、より安全で簡単な方法を選べなくなります。必要な結果と禁止する結果を中心に書くのがコツです。

Step 5: 境界条件と対象外を書く

要件定義の抜けは、正常に動く例ではなく境界で見つかります。通信が切れたとき、同じデータを二度送ったとき、古い形式のデータが残っているとき、権限が途中で変わったとき、利用者が戻るボタンを押したときなどを確認します。すべてを一度に解決できないなら、今回扱う境界と、記録だけ残して後回しにする境界を分けます。

対象外も具体的にします。「管理者画面は対象外」「過去データの一括変換は別途判断」「見た目の全面変更は含めない」のように、Codexが調査中に見つけても変更案へ入れない範囲を明示します。対象外があることで、要件の不足ではなく意図的な判断として説明できます。

Step 6: Codexへ調査と提案を依頼する

最後に、整理した要件、参照してほしい場所、変更してよい範囲、出してほしい成果物をまとめて依頼します。最初の依頼では、ファイルの変更を求めず、現状の根拠、関連箇所、矛盾、不明点、実装案の順に出させます。提案を読んでから、必要な範囲だけ次の依頼に進めると、誤解が差分として残る前に戻れます。

Codexに渡す依頼文の作り方

依頼文は、丁寧な長文にすることより、判断に必要な項目が揃っていることが重要です。目的、現状、対象範囲、対象外、制約、成果物、質問の扱いを見出しで分けます。Codexに答えを当てさせるのではなく、調査した事実と判断待ちの事項を分けて報告させる形にすると、要件定義の会話が安定します。

たとえば、次のような骨格を使えます。実際のリポジトリ名や画面名は依頼ごとに差し替え、まだ決まっていない部分は空欄のままにせず「未決」と書きます。

目的:
  [誰のどんな負担を減らし、何をできるようにするか]

現状:
  [確認できた画面、処理、データ、既存テスト]

今回の対象:
  [変更を検討する画面・処理・データ]

対象外:
  [今回の依頼に含めない範囲]

必須条件:
  [完了判定に必ず必要な動作]

受け入れ条件:
  1. [入力]のとき、[期待する結果]になる
  2. [異常な入力]のとき、[表示と保存の扱い]になる

最初の依頼:
  1. 変更せずに関連ファイルと既存テストを調べる
  2. 事実・推測・提案を分けて報告する
  3. 不明点と、確認後に選べる実装案を示す

調査と提案を分ける

調査の依頼では、まず「どこに何があるか」「現在どう動くか」を確認します。提案の依頼では、要件を満たすためにどのファイルを変更し、どの確認を追加し、どんな影響があるかを出させます。この二つを同時に頼むと、調査途中の推測がそのまま提案へ混ざるため、読み手が根拠を追いにくくなります。

最初の返答に、変更対象の一覧だけでなく「変更しない理由」も含めるよう求めます。既存の処理を再利用するのか、似た処理を新たに作るのか、データの形を変える必要があるのかを説明できれば、要件と実装案の距離が分かります。疑問が残るときは、コードを書かせる前に質問へ戻します。

不明点を質問に変える

Codexが「権限が必要」「既存データを移行する」「通知を追加する」と書いた場合、それは要件の確認事項かもしれません。質問は一度に多くしすぎず、答えによって対象範囲や受け入れ条件が変わるものから確認します。「過去データを表示する必要があるか」「未登録の利用者にも同じ画面を見せるか」のように、選択肢を具体化すると判断しやすくなります。

質問に答えたら、回答を依頼文や要件文書へ反映します。会話の中だけで決めると、次のセッションや別の担当者へ伝わりません。決定したこと、保留したこと、採用しなかった案を短く残すことで、後から同じ議論を繰り返さずに済みます。

リポジトリを読むときの確認点

要件定義 codexでは、要件文書だけでなく、現状を裏付けるコードの位置を確認することが大切です。画面、入口、データ、外部サービス、テストを別々に読むのではなく、一つの利用場面がどの経路を通るかを追います。Codexから出たファイル名をそのまま信じるのではなく、実際に目的の動作へ関係しているかを確認します。

確認の目的は、ファイルをたくさん列挙することではありません。要件の一文が、どの入口からどの処理を通り、どの結果として利用者へ返るかを説明できる状態にすることです。根拠が見つからない箇所は、見落としではなく未確認事項として残し、提案へ進む前に調べる対象にします。

入口から保存までを追う

まず利用者が操作する入口を起点にします。画面の入力名、送信先、入力検証、処理の分岐、保存処理、成功時の表示、失敗時の表示の順に追えば、要件のどこがコードへ対応するか見つけやすくなります。APIがある場合は、画面とAPIの両方で値の扱いが一致しているか確認します。

一覧や検索では、取得条件、並び順、ページ分割、空の結果、権限による見え方を確認します。既存の共通処理を使っている場合は、そこを変更すると別の画面へ影響する可能性があります。要件の対象が一画面でも、共有処理を触る提案なら影響範囲を文書に追記します。

既存仕様との衝突を見つける

新しい要件が既存の仕様と衝突することは珍しくありません。たとえば、画面では必須にしたい値が古いデータには存在しない、現在は利用者本人だけが見られる情報を管理者にも見せたい、同じ操作を再送すると二重登録になる、といった問題です。Codexには「要件を満たす場合に壊れる既存動作」を先に探すよう伝えます。

衝突が見つかったら、すぐに実装方法を決めず、互換性の選択肢を並べます。既存データを補うのか、表示時に補完するのか、対象画面だけ別の扱いにするのかで、必要な確認が変わります。担当者が選んだ案と、採用理由を要件に残すと、後のレビューで判断を再現できます。

実装の可否を人が判定する

Codexが「少ない変更で可能」と書いても、運用や説明の負担が少ないとは限りません。逆に、変更箇所が多くても既存の構造に沿うなら、長期的には安全な場合があります。提案は変更行数だけでなく、影響範囲、戻しやすさ、確認方法、既存利用者への影響で比べます。

実装前に、レビュー担当者が要件と提案を並べて確認します。必須条件がすべて提案に含まれているか、対象外へ変更が広がっていないか、失敗時の動作が書かれているかを見ます。疑問が一つでも残るなら、実装を止めて要件を補います。止める判断は遅れではなく、後戻りを小さくする確認です。

受け入れ条件の書き方

受け入れ条件は、完成したコードを評価するための共通の物差しです。条件が曖昧だと、実装者は「動いた」と考え、利用者やレビュー担当者は「使えない」と感じることがあります。成功時、失敗時、境界、既存動作の維持を分け、どの状態なら合格かを一つずつ書きます。

よい条件は、別の担当者が同じ入力を使っても同じ結論に到達できます。画面の印象だけでなく、表示、保存、遷移、再読み込み後の状態を確認対象にし、条件の文だけで確認の始点と終点が分かるようにします。判断が人の感覚に依存する部分は、確認者と観点を先に決めます。

正常な操作を具体化する

正常系では、入力の前提、操作、期待する表示、保存や遷移の結果を記述します。「有効なメールアドレスを入力して送信すると確認画面へ進み、再表示しても入力値が意図した形式で残る」のように、目に見える結果と裏側の結果を合わせます。どの画面で確認するかも書けば、手作業の確認が迷いません。

条件は、実装の細部を過度に縛らないようにします。内部でどの関数を使うかではなく、利用者が観測できる動作、保存されるデータの意味、既存の互換性を中心にします。必要な場合だけ、性能やデータ形式などの数値を指定します。

異常と境界を具体化する

空欄、長すぎる値、形式が違う値、期限切れ、同じ要求の再送、対象データがない場合を考えます。異常時は「エラーになる」だけで終わらせず、利用者へ何を表示するか、入力値を残すか、保存を行わないか、再試行できるかまで決めます。

境界条件には、今回の対象外も添えます。たとえば過去データの変換を扱わないなら、過去データを見たときの表示方針だけを決め、変換作業は別の判断にします。対象外を隠すより、確認できる状態で保留するほうが、実装後の期待値を合わせやすくなります。

既存動作を守る条件を書く

新機能の受け入れ条件だけでは、変更による退行を見逃します。既存の利用者が従来の入口から操作できること、旧形式のデータを読む処理が壊れないこと、関係ない画面の表示と保存が変わらないことを別の条件にします。変更の影響範囲にあるテストを確認し、足りない場合は追加の確認方法を決めます。

Codexには、実装前に「この変更で影響を受ける既存条件」を列挙させます。実装後は、受け入れ条件と照らした結果を短く報告させ、未確認の項目を残さないようにします。すべてを一度に確認できない場合は、未確認であることを明記してから公開の判断をします。

GPT-5.6とCodexの作業単位を選ぶ

要件定義でモデルを選ぶときは、名前の新しさだけでなく、依頼の規模と確認のしやすさを見ます。OpenAIはGPT-5.6をSol、Terra、Lunaの三つの層で提供し、Codexでも利用できると説明しています。難しい設計や複数の関連箇所を調べる依頼と、決まった条件の小さな修正では、必要な推論の深さが異なります（出典: OpenAI「GPT-5.6」）。

大きな課題は小さく分ける

要件定義、実装、確認を一度の大きな依頼にすると、どこで判断を誤ったか追いにくくなります。まず現状調査、次に仕様案、次に実装範囲、最後に確認結果という単位に分け、各返答を読んでから次へ進みます。Codexのセッションを分ける場合も、前提、決定事項、未決事項を短く引き継ぎます。

分割は作業を細切れにすることが目的ではありません。判断が変わる地点に区切りを置くことが目的です。対象範囲が確定する前、受け入れ条件が確定する前、既存動作への影響が分からない間は、実装へ進まずに確認を置きます。

モデルより確認方法を先に決める

高い能力のモデルを選んでも、完了判定がなければ品質は安定しません。先に受け入れ条件、確認するファイル、実行するテスト、目視する画面を決め、その後に作業規模に合うモデルを選びます。軽い調査を軽量な選択肢で行い、難しい整理や複数の案の比較に余力を使うという考え方が実務的です。

モデルを切り替えたときは、前の返答を丸ごと正解として引き継がず、決定事項と根拠だけを渡します。モデル名が変わっても要件の意味が変わらないよう、目的、範囲、受け入れ条件を基準文書にします。こうすれば、更新後のCodexを試す場合も比較しやすくなります。

実例で見る要件定義 codex

ここでは「プロフィール画面で利用者が表示名を変更できるようにする」という小さな例を考えます。最初の要望だけなら、画面に入力欄を追加すれば終わりに見えます。しかし、未入力、長さ、禁止文字、保存失敗、他の画面の表示、過去データとの関係を決めなければ、実装後に判断が分かれます。

この例の目的は、特定の画面を作ることではなく、要望を確認可能な仕様へ変換する過程を見せることです。小さな機能でも、目的、対象外、成功、失敗、既存動作を分ければ、Codexに調査させる範囲と人が決める項目がはっきりします。

目的と範囲を決める例

目的は「利用者が自分の表示名を変更し、次回の表示にも反映できるようにする」です。対象はプロフィール画面と、その表示名を読む画面です。対象外はログイン用の識別子、メールアドレス、他人のプロフィール編集、管理者向けの一括変更とします。これだけで、Codexが認証や管理機能へ調査範囲を広げる理由が減ります。

必須条件は、表示名を入力して保存できること、保存後に同じ表示名が読めること、未入力や許可されない長さを保存しないことです。希望条件として、入力中の文字数表示や保存完了の案内を置くこともできます。必須と希望を分けると、最初の依頼で対応する範囲が明確になります。

受け入れ条件を作る例

正常な入力なら、保存後にプロフィール画面へ戻り、表示名が新しい値になっていることを確認します。未入力なら保存せず、入力欄の近くに修正方法を示します。上限を超える値なら、何文字までかを伝え、保存を行いません。保存処理が失敗した場合は、成功したように表示せず、入力した値を再確認できる状態にします。

さらに、別の画面で同じ利用者の表示名を開いたときも新しい値が表示されることを確認します。過去から表示名が空の利用者を読み込めるか、同時に二つの画面から保存したときにどう扱うかは、仕様として決めるか対象外として明記します。未決のまま実装を始めないことが、要件定義 codexの重要なポイントです。

Codexへの依頼例

この例で最初に渡す依頼は、次のように短くできます。実装を求める前に、関連ファイルと既存テストを調べ、仕様の不足を質問にしてもらいます。

プロフィール画面の表示名変更について、まず変更せずに調査してください。
目的は、利用者が自分の表示名を保存し、別の画面でも新しい値を見られるようにすることです。
対象はプロフィール画面、表示名を読む画面、保存処理、関連する確認です。
対象外はログイン用の識別子、メールアドレス、他人のプロフィール、管理者の一括変更です。
必須条件は、保存、再表示、未入力の拒否、長さ超過の拒否、保存失敗時の表示です。
関連する画面・処理・データ・既存テストを列挙し、事実・推測・提案を分けてください。
不明点、既存動作との衝突、実装前に人が決める項目を最後にまとめてください。

この依頼に対する返答を読んで、実際のファイルと条件が一致したら、次の依頼で実装範囲と確認方法を確定します。一致しなければ、表示名の定義、保存先、対象画面を修正してから再調査します。依頼文の完成度を上げることより、返答を根拠付きで確認して小さく直すことが重要です。

よくある失敗と直し方

要件定義 codexの失敗は、Codexの能力不足より、判断を文章にしないまま作業を始めることから起きます。便利そうな機能を足すことを目的にすると、利用者の問題、対象範囲、完成判定が置き去りになります。失敗した依頼を責めるのではなく、どの情報が不足していたかを要件へ戻して補います。

特に注意したいのは、曖昧な要望が短いほど簡単に見えることです。短い依頼はCodexが自由に補える余地を増やしますが、その補い方がサービスの意図と一致する保証はありません。次の小見出しでは、実際に起きやすい不足を見つけ、依頼文へ戻して直す方法を確認します。

機能名だけで依頼する

「検索を改善」「通知を追加」「画面を今風にする」だけでは、実装候補が多すぎます。背景、対象場面、成功した状態、対象外を一文ずつ追加します。Codexには、依頼を読んで最初に不足している前提を質問させるのも有効です。質問なしでコードを書き始めた場合は、変更を続けず、まず調査結果を返すよう依頼し直します。

成功だけを書いて失敗を決めない

正常な入力が通るだけでは、利用者が困る場面を扱えません。空欄、制限超過、保存失敗、該当データなし、権限変更、再送を確認します。すべてを今回の対象にできない場合は、対象外と保留理由を記録します。何もしないことと、今回扱わないことを混同しないのがポイントです。

既存記事や既存コードを前提にしすぎる

似た機能の記事やコードがあっても、今回の画面や利用者にそのまま適用できるとは限りません。Codexには参照した既存箇所と、再利用できない理由を明示させます。名前が似ているだけの処理を統合する場合は、影響を先に確認し、必要なら別の小さな変更に分けます。

完了判定を最後に考える

最後にテストを足そうとすると、要件の曖昧さが実装後まで残ります。要件を書いた時点で、どの条件をどの方法で確認するか決めます。人が画面を見るのか、既存テストを実行するのか、データを再読み込みするのかを条件の横に置けば、Codexへの依頼も具体的になります。

要件定義 codexを実務に定着させる

要件定義 codexの価値は、Codexに文章を書かせることだけではありません。目的と範囲を揃え、現状の根拠を調べ、受け入れ条件を決め、未決事項を残したまま実装へ進まないことにあります。GPT-5.6やCodex CLIが更新されても、この順序は変わりません。更新は作業を支える材料であり、判断の代わりではありません。

まず小さな機能で、目的・対象外・正常系・異常系の四つを一枚にまとめて試します。Codexには変更前の調査と質問を依頼し、返答を人が確認してから実装を許可します。実装後は受け入れ条件、既存動作、対象外への影響を見直し、次の依頼へ引き継ぐ決定事項を残します。

「作って」から始めるのではなく、「何が分かれば作ってよいか」を先に決める。これが要件定義 codexを使うときの中心原則です。仕様が短くても判定でき、根拠が追え、変更範囲が見えるなら、Codexは調査と実装の両方で力を発揮しやすくなります。