GitHub Issue対応にAIを使うときは、不具合の観察、期待する仕様、原因の仮説、実装の受入条件を分けます。Issueの文章が詳しくなったことと、再現・修正・検証が終わったことは別です。AIには不足情報も残させ、Issueから変更箇所と検証結果へ追える形を作ります。
この記事は、架空のCSV出力の不具合報告をIssue案へ整理する例です。実際のアプリ、CSV出力、GitHubへの投稿、コード修正、PR作成は行っていません。フォーム案もローカルで構文を確認するだけで、GitHubの入力画面を試した結果ではありません。
目次
報告を、再現できる条件へ整理する
「CSVがおかしい」という報告なら、操作、入力条件、画面の状態、出力内容を分けて集めます。想像で環境やエラーコードを足さず、分からない項目をそのまま残します。
以下は説明用に設定したデータです。実システムの記録ではありません。
表は横にスクロールできます
| レコードID | カテゴリ |
|---|---|
| P001 | A |
| P002 | B |
| P003 | A |
| P004 | C |
| P005 | B |
このデータに対し、次の報告があったという架空条件を置きます。
表は横にスクロールできます
| 証拠ID | 設定した観察 | この時点では分からないこと |
|---|---|---|
| E01 | カテゴリAで絞った画面はP001・P003の2件 | データ取得の実装 |
| E02 | その状態で出したCSVにはP001～P005の5件 | なぜ全件になったか |
| E03 | 絞り込みなしでは画面・CSVとも5件 | 他のカテゴリで同じ問題が出るか |
E01～E03は手製の前提で、スクリーンショットや実ファイルから取得した証跡ではありません。実際の報告では、確認した版、アカウントの役割、時刻、再現手順、機微情報を除いた出力などを対応させます。
原因を決める前に、期待仕様を確認する
この観察から「APIがフィルタを無視している」とは確定できません。画面側の状態、出力ボタンへ渡す条件、サーバー処理など複数の調査先が考えられます。コードや通信を確認していない段階では、原因の仮説として分けます。
また、「CSVは現在の絞り込みを反映するべき」という期待も、製品仕様として確認します。全件出力が意図された機能なら、画面の案内を直す課題かもしれません。今回の例では、絞り込みを反映する方向の受入条件案を作りますが、合意済みの実仕様とは扱いません。
Issue案へ、観察と条件案を別に書く
タイトル案：カテゴリAで絞った後のCSVに対象外レコードが含まれる
目的：画面の絞り込みとCSVの出力範囲を一致させる方向で確認する。
説明用データ：P001=A、P002=B、P003=A、P004=C、P005=B。
再現手順という架空条件：
1. この5件の一覧を開く。
2. カテゴリAへ絞り込む。
3. CSV出力を実行する。
観察：
- E01：画面はP001・P003の2件。
- E02：CSVには5件すべてが含まれる。
- E03：絞り込みなしでは画面・CSVとも5件。
期待仕様：現在の絞り込みをCSVへ反映する想定。製品担当へ確認待ち。
原因：未確認。APIの不具合と断定しない。
受入条件案：
- AC01：カテゴリAで出力したCSVは、ヘッダーを除くデータレコード数が2件で、ID集合がP001・P003と一致する。
- AC02：絞り込みなしではP001～P005の5件を出力する。
対象外：新しい出力形式、列定義の変更、データの更新・削除。
未確認：アプリ版、環境、実際の権限、他カテゴリ、0件時の期待仕様。
検証状態：実アプリでの再現・修正・テストは未実施。
受入条件案の件数は、ヘッダーを除くデータレコード数です。AC01では件数とID集合の両方を指定し、順序は指定していません。CSVの並び順が要件なら、それも別に定義します。
0件時の出力を、この例だけから「ヘッダーのみ」と決めません。エラー表示や出力ボタンの状態など、製品の判断が必要な項目は確認事項へ残します。
フォームは情報収集を助けるもので、正しさの判定器ではない
GitHub公式のIssue作成手順（新しいタブで開く）は、Issueを不具合や改善などの追跡に使い、リポジトリにテンプレートがあれば選択できると説明しています。投稿前には、既存のIssueに同じ課題がないかも確認します。
Issue Formsの公式構文（新しいタブで開く）は、YAMLで入力欄や必須条件を定義し、回答をIssue本文のMarkdownへ変換する方式を案内しています。同資料ではpublic previewとされているため、利用時の現行仕様を確認します。
次は、報告欄の小さなフォーム案です。実際のリポジトリへ配置した設定ではありません。
name: Bug evidence
description: Collect observations and unresolved expectations.
body:
- type: textarea
id: reproduction
attributes:
label: Reproduction steps and environment
validations:
required: true
- type: textarea
id: observed
attributes:
label: Observed result and evidence
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected behavior and unresolved questions
validations:
required: true
必須欄へ文章が入ったことは、その内容が正しい、再現した、仕様が合意されたという証明ではありません。ログや環境情報に秘密情報を要求せず、初期判断に必要な範囲を集めます。
AIへは、調査の仮説と実行結果を分けて返させる
次のIssue案を、実装前の調査用に整理してください。
観察、期待仕様、原因仮説、受入条件案、未確認を別にしてください。
根拠IDがある観察を保持し、確認していないログや再現回数を作らないでください。
受入条件案ごとに、見る実装と必要な検証を提案してください。
調査していないファイル名や原因は確定情報として書かないでください。
仕様の不足は質問として残し、範囲外の機能を足さないでください。
実際に実行した確認と、これから行う計画を分けてください。
この依頼では外部投稿、担当割当、コード変更、PR作成は行いません。
入力：［必要な報告と資料］。
実装へ進む場合は、対象リポジトリの指示と既存仕様を読み、受入条件と変更箇所、検証結果を対応させます。Issue案をAIへ渡したことだけで、変更や外部操作の範囲を広げないようにします。
修正後も、条件と証拠を対応させる
今回の例なら、次の追跡欄を使えます。すべて未実行の計画です。
表は横にスクロールできます
| 条件 | 確認すること | 必要な証拠 | 今回の状態 |
|---|---|---|---|
| AC01 | カテゴリAのデータレコード数が2件で、ID集合がP001・P003か | 適用条件、ヘッダーを除く件数、解析したCSVのID | 未実行 |
| AC02 | 絞り込みなしの5件を保つか | 同じ入力版での出力ID | 未実行 |
コードのテストが通ったことと、実際の出力操作や画面が正しいことも分けます。未確認の項目はPRの説明へ残し、Issueの目的が満たされた証拠を確認してから完了を判断します。PRの作成や関連リンクだけを、修正完了の代わりにはしません。
今回確認したのは、手製データの2件・5件というID対応、受入条件IDと追跡表の対応、フォーム案の構文です。実際の不具合を再現したり、GitHubへIssueを作ったりした結果ではありません。
参考資料
公式資料の確認日：2026年10月20日。データ、観察、Issue案は独自の架空例です。実アプリ、CSV出力、GitHub投稿、設定適用、コード修正、PR、フォームや画面の表示は検証していません。