AIに渡すIssueの受入条件｜実装前に完了の意味をそろえる

Issueに「プロフィールの表示名を変更できるようにする」とだけ書けば、AIはもっともらしい実装を返せます。しかし、保存APIを直すのか、画面も対象にするのか、空文字を受け取ったときに既存値を消してよいのかは決まりません。コードが動いても、依頼者とレビュー担当者が別の完成像を持ったままです。

受入条件は、変更を受け入れるか、差し戻すかを同じ材料で決めるルールです。Issueには少なくとも「何を入力するか」「何が起きれば合格か」「失敗時に何を壊してはいけないか」「どこを変更対象にしないか」を分けて置きます。各項目に確認方法を結び付けると、実装者がAIでも人でも完了の意味がぶれにくくなります。説明の長さより、採否を再現できることが要点です。

2026年9月21日時点で、NISTのSecure Software Development Framework（SSDF）は、組織の期待を満たすセキュリティチェック基準を定義し、SDLCを通じて追跡することを示しています。実装例には、既存のDefinition of Doneへの基準追加、成果物のレビュー、承認・却下・例外申請の記録があります。公式指針の対象はセキュリティです。Issue全般にも判定基準を置く考え方は、その構造をこの記事が実務へ展開したものです。

題材は「認証済み利用者が自分のプロフィール表示名を変更する」です。要望の要約からは、正常系の入口も、失敗時に残すべき状態も読み取れません。次の記入例は、そのままIssueの欄へ分けて転記できる形にしています。

**入力例：** 認証済み利用者が、既存プロフィールの表示名を有効な文字列へ変更する。

**受入条件：** 保存後の応答に含まれる表示名と、再読込後に取得した表示名が入力と一致する。

**失敗条件：** 表示名が空、または保存に失敗した場合は既存のエラー形式を返し、保存済みのプロフィールデータを変更しない。

**触らない範囲：** 認証処理、DBスキーマ、表示名以外のプロフィール項目、フロントエンドは変更しない。

**確認方法：** 正常系と失敗系の検証結果をPull Requestの説明またはChecksで示し、Files changedで対象外の差分がないことを確かめる。条件を満たしても、触らない範囲を越えた差分があれば受け入れない。

この四分割はNISTやGitHubが公開する公式テンプレートではありません。検証可能な条件をIssueへ移し、Pull Request上の結果と差分で採否を決めるための編集例です。

「保存後の応答」と「再読込後の表示」を分けると、一時的に返した値に加えて、保存された結果まで確認対象になります。入力例の役割は、網羅的なテストデータを用意することではありません。依頼者が成立させたい利用の起点を示し、受入条件と並べたときに何を観測するかが分かる粒度にします。

失敗条件は、単に「エラーになること」では不足します。エラーの形式が既存の契約に沿うことと、保存済みデータを変えないことまでが判定対象です。AIは成功経路を成立させるため、例外時の更新順序や既存データの保全を暗黙に決めることがあります。依頼者が守りたい状態を書かなければ、レビュー時に初めて期待の違いが表面化します。

触らない範囲は、変更に対する責任の外縁を切る欄です。この例では、認証処理やDBスキーマに手を入れれば実現できるとしても、その変更は受け入れません。フロントエンドも対象外です。AIが画面まで直した場合、その差分は依頼の範囲を越えたものとして扱います。実装方法を細かく縛らずに、変更可能な領域を限定できます。

四欄は互いに補完します。入力例だけではデモの手順に寄り、受入条件だけでは正常系の確認に偏ります。失敗条件がデータの保全を定め、触らない範囲が変更の外縁を定めることで、一つの依頼として閉じます。四欄を埋めた事実より、照らし合わせたときに矛盾なく採否を決められるかを確認します。

「適切に保存する」「エラーを正しく処理する」「既存機能に影響させない」は、一見すると条件に見えます。しかし、どの結果を見て適切とするのかが残っています。AIへ渡す前に、動詞の後ろを観測可能な状態へ変えます。「保存する」なら応答と再読込結果、「壊さない」なら失敗後の保存済みデータ、「影響させない」なら変更差分の対象を示します。

Issueの段階では、内部の関数名や実装手順まで固定する必要はありません。今回の受入条件が求めるのは、入力に対して外から確認できる結果です。既存設計によって実装の選択肢が一つに限られる場合を除き、合格状態を中心に書けば、AIが既存コードを読んで手段を選ぶ余地を残せます。

2026年9月21日時点のNIST SSDF PW.8.2は、セキュリティテストの範囲を定め、テストを設計・実行し、結果を文書化することを示しています。また、発見した問題と推奨する修正を開発ワークフローまたはIssue追跡システムに記録し、トリアージするよう示しています。公式の対象はセキュリティ検証ですが、「範囲・実行・結果の記録」を離さない構造は、AIへ渡すIssueの検収設計にも応用できます。

チームで繰り返すなら、四欄をIssueテンプレートにします。自由記述の本文に見出しを置く方法でも始められますが、入力例と受入条件が同じ段落へ混ざると、どちらを変更すべきか分かりにくくなります。欄を分ければ未決定の境界が目立ち、文章量を増やさずに記入漏れを見つけられます。

2026年9月21日時点のGitHub公式ドキュメントでは、Issue Formsのフォームスキーマにtextarea、input、dropdown、checkboxesなどの要素があり、label、description、placeholder、事前入力値によって期待する入力を案内できます。textareaなどのrequired検証は、公開リポジトリで入力が完了するまで送信を防ぎます。この公開リポジトリ限定という条件はrequired検証に付いています。フォームスキーマはpublic previewのため変更される可能性があります。自社の利用可否を確かめてから運用へ組み込みます。

GitHub Issue Formsを利用できる環境なら、「入力例」「受入条件」「失敗条件」「触らない範囲」を別のtextareaにし、各欄の説明に何を書くかを置けます。利用できない環境でも、Markdownテンプレートの同じ見出しで代替できます。requiredは空欄を防げても、条件の質までは保証しません。「なし」と書かれた触らない範囲が本当にないのかは、依頼をAIへ渡す前に人が判断します。

AIが「実装とテストが完了しました」と報告したら、Issueで定めた条件をPull Requestの説明、検証結果、実際の差分へ対応付けます。完了報告は照合の入口にとどめ、採否は記録された証拠から決めます。この手順なら、実装者が誰であっても同じ材料を使えます。

2026年9月21日時点のGitHub公式ドキュメントによると、Pull RequestのConversationには説明・コメント・レビュー、Checksには自動テストやビルドなどの検証、Files changedにはレビュー対象の差分が表示されます。merge statusにはブロッカー、不足する承認、その他の要件が示され、これらを合わせてマージ可能か判断できます。これはGitHub上の公式仕様です。どの情報を受入条件へ結び付けるかはチーム側で決めます。

**入力例と受入条件の照合：** Pull Requestの説明で、実行した確認と得られた結果を対応付けます。

**失敗条件の照合：** Checksやレビュー可能な記録から、エラー形式と失敗後のデータ状態を確認します。

**触らない範囲の照合：** Files changedを見て、認証、DBスキーマ、他のプロフィール項目、フロントエンドに差分がないか人が確認します。

不一致があれば、条件を満たさない理由をConversationに残し、修正、却下、例外のどれにするか判断します。この照合結果が、AIの自己申告に代わる受入判断の材料です。

この書き方が固定するのは、一つの依頼について何が揃えば完了かという点です。プロジェクト全体のタスク分割は対象に含めません。四欄へ書く途中で複数の異なる入力や変更禁止範囲が並び、検証方法も分かれたら、Issueを分ける検討材料になります。分割数を先に決めず、一つの採否を一組の条件で判断できるかを基準にします。

チーム全体の依頼、実装、レビューの流れを整える場合は、AI駆動開発のワークフロー設計も合わせて確認できます。また、AIへ渡す情報や実行権限まで含めた安全面は、Claude Codeを安全に使うためのセキュリティ対策で扱っています。いずれも受入条件の外側にある運用設計を切り分ける資料です。今回のIssueへ項目を無条件に追加する根拠にはしません。

実装を始めてよいのは、入力に対する合格状態、失敗しても残す状態、対象外の差分がないことを、それぞれPull Request上の結果と差分で示せるときです。どれか一つでも確認方法が決まっていなければ、仕様を増やすのではなく、入力例、受入条件、失敗条件、触らない範囲の該当欄を直します。これで、AIの「できました」ではなく、Issueに合意した事実を根拠に完了を判断できます。