Issueは、作業の題名ではなく、背景・目的・範囲・完了条件を共有し、担当者が次の判断へ進める作業単位です。 「ログイン画面を改善する」だけでは、誰の何が困っていて、何をもって完了か判断できません。
なぜIssueが必要か
口頭依頼や短いチャットは、決定の経緯と対象外が失われやすく、実装者と確認者が別の完成像を持つ原因になります。Issueに目的と観測可能な完了条件があれば、実装方法を選ぶ余地を残しながら、レビューとテストの基準を共有できます。
良いIssueは実装を細かく命令するものではなく、解く問題と境界を明確にします。
登場人物と対象
問題を報告する利用者・運用担当、優先順位を決めるプロダクト担当、実装者、デザイナー、レビュー・QA担当が関わります。起票者が全仕様を知っている必要はありません。分からない点は未決事項として残し、誰がいつ決めるかを示します。
作成から完了までの流れ
- 観測した問題と影響を事実で書く。
- このIssueで可能にしたい利用者行動を一文にする。
- 完了条件を画面・API・データなどで確認可能にする。
- 対象外と依存関係を明示する。
- 未決事項を解消し、実装可能な大きさへ分ける。
- PRとテストを関連付け、完了時に条件を照合する。
テンプレート
## 背景
どんな利用者の問題があるか
## 目的
この変更で可能にしたいこと
## 完了条件
- 確認できる動作
- 失敗時や空状態
## 対象外
今回変更しないもの
## 参考情報
画面、ログ、関連Issue、設計記録
## 未決事項
実装前に確認が必要なこと
不具合なら再現手順、期待結果、実際結果、環境、頻度を加えます。新機能なら利用者、利用場面、成功・空・失敗状態を加えます。セキュリティ問題は公開Issueへ詳細を書かず、リポジトリのセキュリティポリシーに従います。
Issueの主要パターン
| 種類 | 中心になる情報 | 完了の証拠 |
|---|---|---|
| 不具合 | 再現手順と期待との差 | 再現テストと修正確認 |
| 新機能 | 利用者の目的 | 受け入れ条件 |
| 技術改善 | 現在のリスク・負債 | 測定・テスト・削除結果 |
| 調査 | 判断したい問い | 調査結果と次の決定 |
| 運用作業 | 対象環境と安全条件 | 実行記録と事後確認 |
調査Issueはコード変更を完了条件にせず、判断材料と次の選択を成果にできます。
具体例
## 背景
提出一覧が0件の時、読み込み中表示のままに見える。
## 目的
受講生が「提出がない状態」と通信中を区別できるようにする。
## 完了条件
- 読み込み中は進行中であることが伝わる
- 成功して0件なら空状態が表示される
- 取得失敗なら再試行できる
## 対象外
- 一覧の検索・並べ替え
## 確認
- 0件、1件、通信失敗を確認する
この例では技術名を固定せず、利用者が区別すべき状態を定義しています。
手段より目的を書く
実装方法が未決なら、最初から特定ライブラリを指定しません。制約と目的を書き、選択肢を検討します。
大きすぎる兆候
完了条件が10個以上、複数画面とDB移行を同時に含む、途中成果を確認できない場合はIssueを分けます。
分割後も親Issueやチェックリストで目的との関係を残します。単にフロントとバックへ分けると、利用者価値を確認できない半完成が増えることがあります。可能なら、薄くても一つの利用経路が完了する単位を選びます。
よくある誤解
Issueは最初から完全である必要はありません。情報が増えたら本文を更新し、重要な決定はコメントだけに埋めません。一方、実装開始後に完了条件を無言で変えるとレビュー基準が動くため、変更理由を共有します。「担当者を付けたから準備完了」でもなく、未決事項と依存関係が残っていないか確認します。
注意とベストプラクティス
- 顧客情報、認証情報、非公開脆弱性を公開Issueへ載せない。
- 「使いやすくする」を観測可能な状態へ分ける。
- 解決策を指定する時は、法令・互換性など制約の根拠を書く。
- 重複Issueは関連付け、片方を正本にする。
- ラベルや優先度の意味はチーム内で統一する。
デバッグ・確認方法
第三者が本文だけを読み、「誰の問題か」「今回どこまでか」「どう確認するか」を答えられるか試します。リンク切れ、再現手順、環境情報、受け入れ条件を確認し、実装前に未決事項をゼロにするか、明示的に保留します。
ケーススタディ：プロフィール保存の失敗を扱う
「プロフィール画面を直す」という依頼を受けた時、すぐ通知部品の実装Issueにしてはいけません。調査すると、通信失敗時にも編集画面が閉じ、利用者は保存できたと思って離脱していました。ここで解く問題は通知の見た目ではなく、保存結果を区別できず再試行もできないことです。
目的は「受講生がプロフィールの保存結果を判別し、失敗時に入力を失わず再試行できる」と置けます。完了条件は、成功時に更新内容が再取得後も表示される、入力不備では該当項目と理由が分かる、通信失敗では編集内容を保持して再試行できる、権限がない場合は保存済みと表示しない、のように状態ごとに書きます。対象外にはプロフィール項目の追加と画面全体のデザイン変更を置きます。これで実装者は通知方式を選べますが、守るべき利用者行動は変わりません。
着手判断の手順
最初に、報告された現象が再現できるか、対象利用者と頻度が分かるかを確認します。次に、目的を一つの利用者行動で表し、成功、空、入力不備、通信失敗、権限なしのうち関係する状態を列挙します。その後、各完了条件にテストや操作確認を割り当て、API契約、デザイン、データ移行などの依存を洗い出します。最後に、未決事項の答えが実装を大きく変えるなら着手を止め、調査Issueへ分けます。変えないなら、担当者と決定期限を明記して並行できます。
着手可能とは、すべてが決定済みという意味ではなく、未決事項が作業境界を壊すかどうかを判断できる状態です。
失敗条件と観測方法
Issueは、実装者ごとに異なる完成像になる、完了条件を実行しても合否が決まらない、対象外の変更なしでは完了できない、必要な権限やデータ条件が後から発覚する、という時に失敗しています。「エラーを適切に表示する」「レスポンシブにする」「いい感じに高速化する」は、観測対象や境界値がないため、そのままでは完了条件になりません。
観測には、状態別のテスト結果、再現動画、画面キャプチャ、API応答、計測値などを使います。ただし画像一枚で再試行やデータ保持まで証明したことにはしません。各完了条件の末尾に「どの環境で、誰が、何を操作し、何が見えれば合格か」を補うと、レビュー時の解釈差を見つけやすくなります。完了時には条件へチェックを付けるだけでなく、対応するテスト名やPR内の確認記録へ結びます。
良い例と悪い例
悪い例は「保存ボタンを押したらトーストを出す」です。手段だけを指定し、失敗時の入力保持や権限エラーを見落としています。良い例は「通信失敗時、編集内容を保持したまま失敗を識別でき、同じ入力で再試行できる」です。さらに「成功通知の色はデザイナー確認待ち。通知方式にかかわらず保存結果を読み上げ可能にする」のように、未決の見た目と確定した振る舞いを分けると、並行作業の範囲が明確になります。
実践演習：曖昧な依頼を分解する
「プロフィール画面を改善する」を題材に、観測事実を一つ書きます。「保存失敗時も成功時と同じ画面に戻り、結果を区別できない」は確認可能ですが、「使いにくい」はそのままでは判定できません。成功、入力不備、通信失敗、権限なしのうち今回扱う状態を選び、対象外も書きます。
別の人にIssueだけを渡し、実装案を二つ考えてもらいます。どちらも目的と完了条件を満たせるなら、手段を過剰に固定していません。完成像が大きく異なるなら、利用者、状態、データ境界のどれが曖昧かを補います。
着手可能の判定では、依存Issue、デザイン、API契約、権限、移行の未決事項を確認します。未決でも並行調査できる場合は担当と決定期限を付けます。完了後は各条件へテスト、画像、操作結果などの証拠を対応させます。
まとめ
実装へ進めるIssueは、背景、目的、確認可能な完了条件、対象外、未決事項を一つの作業境界として共有します。 手段を先に固定せず、必要な制約だけを根拠付きで残します。完了時はPRの存在ではなく、受け入れ条件を証拠と照合します。
