TL;DR
- Issueの品質は実装品質の先行指標。 テンプレートで「書くべきこと」を強制するだけで手戻りが減る。
- 目的・非目的・制約・受入条件の4点セットが揃えば、AIは最適化先を誤りにくくなる。
- テンプレ運用はレビューの前倒し。コードを書く前に仕様の穴を潰せる。
本記事は Spec-Driven Development（SDD）シリーズ の1本です。シリーズ全体の設計思想は親記事を参照してください。
なぜIssueテンプレートが必要なのか
AI開発でもっとも多い手戻りパターンは「仕様の曖昧さ」に起因します。人間同士の開発でも起きる問題ですが、AIエージェントが相手だと深刻度が増します。理由は明確で、AIは「行間を読む」ことが苦手だからです。
たとえば「ログイン画面をいい感じにリファクタして」というIssueを書いたとします。人間の開発者なら「いい感じとは？」と聞き返しますが、AIエージェントはそのまま実装を始めます。結果として以下が起きます。
- 意図しないUIライブラリへの乗り換え
- テストが壊れるレベルのAPI変更
- 触るべきでないファイルへの変更
こうした問題はIssueの書き方、つまり依頼文の解像度を上げるだけで大幅に軽減できます。そしてその解像度を安定させる手段が、Issueテンプレートです。
AIに正確に仕様を伝える技術については、なぜAIエージェントは「仕様書」を無視するのか？ も参考にしてください。
Issueテンプレートの必須5項目
テンプレートに含める項目は多すぎても運用が崩壊します。実務で効果が高い5項目に絞りましょう。
| # | 項目 | 問い | 書かないとどうなるか |
|---|---|---|---|
| 1 | 目的（Why） | この変更で何を達成したいか？ | AIが手段を目的化し、過剰実装する |
| 2 | 非目的（Not Goals） | この変更で意図的にやらないことは？ | スコープが無限に膨らむ |
| 3 | 受入条件（AC） | 何をもって「完了」とするか？ | レビュー基準が属人化する |
| 4 | 制約（Constraints） | 使ってよい技術・時間・範囲の上限は？ | AIが最適解を求めて既存構成を壊す |
| 5 | 変更対象外（Out of Scope） | 絶対に触ってはいけないファイル・機能は？ | 意図しない副作用が発生する |
受入条件の書き方を深掘りしたい場合は、受入条件を先に書くTDD実践 を参照してください。
テンプレートのコード例（GitHub Issue Template）
# .github/ISSUE_TEMPLATE/ai-task.yml
name: AI開発タスク
description: AIエージェントに依頼するタスク用テンプレート
body:
- type: textarea
id: purpose
attributes:
label: "目的（Why）"
description: "この変更で達成したいビジネス/技術上のゴール"
validations:
required: true
- type: textarea
id: not-goals
attributes:
label: "非目的（Not Goals）"
description: "意図的にやらないこと"
validations:
required: true
- type: textarea
id: acceptance-criteria
attributes:
label: "受入条件（AC）"
description: "完了判定の具体条件をチェックリスト形式で"
validations:
required: true
- type: textarea
id: constraints
attributes:
label: "制約"
description: "技術・時間・スコープの制限事項"
validations:
required: false
- type: textarea
id: out-of-scope
attributes:
label: "変更対象外"
description: "触ってはいけないファイル・機能"
validations:
required: false
良いIssueと悪いIssueの比較
テンプレートがあっても、埋め方が雑では意味がありません。具体例で「良い/悪い」の境界線を示します。
悪いIssueの典型
目的: ログイン画面をいい感じに対応 受入条件: なし 制約: なし
このIssueは評価条件がゼロです。AIは「いい感じ」を独自解釈し、高確率で手戻りになります。
良いIssueの例
目的: ログイン画面のフォームバリデーションを追加し、無効な入力時にユーザーへフィードバックを返す 非目的: UI全体のリデザイン、認証ロジックの変更 受入条件:
- メールアドレス形式でない入力時にエラーメッセージが表示される
- パスワードが8文字未満の場合にエラーメッセージが表示される
- 既存のE2Eテストが全件パスする 制約: 既存のReact Hook Formを使用。新しいライブラリは追加しない 変更対象外:
src/auth/配下のファイル
両者の違いを一言で言えば、「完了を判定できるかどうか」です。AIに限らず、完了条件が明文化されていないタスクは管理できません。
なお、こうしたIssueの情報不足が積み重なると「コンテキスト負債」と呼ばれる構造的問題に発展します。詳しくは コンテキスト負債とは何か を参照してください。
テンプレート運用ルール
テンプレートを導入しただけでは定着しません。チームで以下のルールを明文化し、運用に組み込むことが重要です。
着手前ゲート
- テンプレ未記入のIssueは着手しない。 これを最優先ルールにする。
- 受入条件が空欄の場合は、Leadに差し戻す。
- 非目的と変更対象外が空欄の場合は、起票者に確認して埋めてから着手する。
レビュー時の活用
テンプレートの真価はレビュー時に発揮されます。受入条件がチェックリスト形式で記載されていれば、レビュアーはIssueを見るだけで合否判定が可能です。
| レビュー観点 | テンプレなし | テンプレあり |
|---|---|---|
| 完了判定 | レビュアーの主観 | 受入条件で機械的に判定 |
| スコープ確認 | コード差分から推測 | 非目的・変更対象外で即確認 |
| 意思決定の追跡 | Slackを遡る | Issueに集約済み |
意思決定を一箇所に集約する方法については、意思決定ログと証拠管理の型 でさらに詳しく解説しています。
まとめ：Issueの質を上げることがAI活用の最短ルート
Issueテンプレートは「書類を増やす」行為ではなく、レビューを前倒しする仕組みです。
- 5項目のテンプレートで依頼の解像度を強制的に上げる
- 着手前ゲートでテンプレ未記入のIssueを弾く
- レビュー時に受入条件を照合して合否を機械的に判定する
この3ステップを回すだけで、AI実装の手戻りは大幅に減ります。
次のアクション:
- まだテンプレートがないなら、上記のYAML例をそのまま
.github/ISSUE_TEMPLATE/に配置してください。 - 受入条件の書き方を改善したいなら → 受入条件を先に書くTDD実践
- 仕様品質の全体像を把握したいなら → AI時代の仕様品質マネジメント
シリーズ全体に戻る: 親記事
