第2章：良い Issue テンプレ（背景 / 目的 / スコープ / 受け入れ条件）
この章で学ぶこと
- 受け入れ条件を Given-When-Then などで書く
- スコープ境界（やらないこと）で期待値を揃える
- DoR（着手条件）に必要な根拠・依存・確認方法を揃える
- 不具合・改善・作業でテンプレを使い分ける
成果物（書けるようになるもの）
本文
Issue の品質は、受け入れ条件の明確さで大きく左右される。受け入れ条件がない Issue は、完了が定義できず、終わらないタスクになりやすい。
受け入れ条件は「完了の判定基準」であり、「作業項目」ではない。実装メモや設計案は補足として書けるが、完了判定は受け入れ条件で行える状態にする。
受け入れ条件の例（Given-When-Then）
- Given: 既存ユーザーでログイン済み
- When: プロフィール更新を実行
- Then: 成功メッセージが表示され、DB が更新される
テンプレを固定すると、レビュー観点も固定できる。
受け入れ条件と確認方法を対応づける
受け入れ条件は、PR 作成時に「どの確認で満たしたか」を説明できる粒度にする。条件だけがあり、確認方法がない Issue は、レビュー時に完了判定が属人化する。
| 受け入れ条件 | 確認方法 | PR で示す証跡 |
|---|---|---|
| 必須項目が未入力なら保存されない | 単体テスト / E2E / 手動確認 | テスト名、スクリーンショット、ログ |
| エラー文言で不足項目が分かる | UI 確認 / 文言レビュー | 確認画面、レビューコメント |
| 誤操作率が下がる | メトリクス観測 | 観測期間、ダッシュボード、残タスク |
数値目標を入れる場合は、観測期間と判定タイミングも書く。PR merge 時点で結果が出ない指標は、DoD ではなく follow-up Issue や完了後確認として分離する。
DoR に入れる最小項目
着手前に、次が揃っているか確認する。
- 目的と対象読者/利用者が明確である
- 受け入れ条件と確認方法が対応している
- 根拠（一次情報、調査ログ、再現ログなど）と未確定点が分離されている
- 依存関係、リスク、ロールバック要否が書かれている
- 判断者、実行者、確認者が決まっている
根拠の分類や信頼度は、別冊の evidence-based-engineering-book の考え方に合わせると、Issue と PR の説明が一貫しやすい。
テンプレの使い分け（最小）
- 不具合: 期待結果/実結果に加え、再現手順/環境/ログを揃える（第3章）
- 改善: 背景/目的/スコープ/非スコープ/受け入れ条件を揃える
- 作業: 手順/期待結果（受け入れ条件）/ロールバック/完了条件を揃える
具体例（悪い例→良い例）
悪い例
受け入れ条件: 良い感じになること
スコープ: いい感じに
良い例
背景: 入力不備による差戻しが多い
目的: 入力不備の差戻しを減らす
受け入れ条件:
- [ ] Given: 入力が不正
- [ ] When: 保存を押す
- [ ] Then: 保存されず、どの項目が不正か分かる
非スコープ: デザイン刷新、文言統一の全体対応
チェックリスト
- 受け入れ条件が検証可能な形になっている
- 受け入れ条件ごとの確認方法が書かれている
- 非スコープが明記されている
- 想定読者（利用者/運用者）が意識されている
- 根拠、未確定点、依存、リスクが分離されている
まとめ
- 受け入れ条件は検証可能な形（Given/When/Then など）で書き、完了判定を固定する
- 受け入れ条件と確認方法を対応づけ、PR で示す証跡まで見通せる状態にする
- 非スコープを明記し、期待値のズレを抑止する
- 不具合・改善・作業でテンプレを使い分け、レビュー観点を固定する
次章への接続
- 次章: 第3章