13｜Issueは何を決め、Pull Requestは何を証明するのか

2026年8月17日

AIとGitHubで、目的・設計・差分・完了を混ぜない

AI Work Governance｜専門テーマ — Issue / Pull Requestの責務

GitHubで仕事を管理するとき、多くの人はIssueとPull Requestを使います。

Issueへ課題を書く。変更を作る。Pull Requestを開く。レビューしてマージする。

流れは単純に見えます。

しかしAIと多くの作業を進めると、IssueとPull Requestを使っているだけでは役割が自然に分かれないことが分かります。

Issueの目的がPR途中で別の目的へ変わる
重要な設計判断がコメントにだけ残る
PRがmergeされたため親Issueまで完了扱いになる
最新説明がPR本文にしかなく、Issueが古い
設計と実装が一つのPRへ混ざる
AIが「新しい文章」を「最上位の正本」と誤認する

問題はGitHubの機能不足ではありません。

どの成果物が、何を所有するのかを決めていないこと。

です。

まずGitHubの機能と、自分たちの運用ルールを分ける

GitHub Issuesは、アイデア、フィードバック、タスク、不具合などの仕事を計画・議論・追跡する柔軟な場所です。

Pull Requestはリポジトリ変更を提案し、議論、レビュー、確認を経てマージするための場所です。

ここまではGitHubの機能です。

一方、

Issue = 問題・目的の責任主体
設計記録 = 設計判断の責任主体
進捗管理Issue = 進捗の責任主体
実装PR = 差分・検証の責任主体

といった分け方は、私たちがAI協働のために追加した運用モデルです。

これをGitHub一般の唯一の正解として扱ってはいけません。

一番短い理解

まずは次だけ覚えると分かりやすいです。

flowchart LR
    accTitle: Issueからマージ後の完了確認までの責務
    accDescr: Issueが目的と範囲を持ち、設計が解き方を決め、Pull Requestが変更と検証を提示し、レビューとマージの後に親の目的まで完了したかを別に確認する。
    I[Issue / なぜ・何を・どこまで] --> D[設計 / なぜこの解き方か]
    D --> P[Pull Request / 何を変え・どう確かめたか]
    P --> R[レビュー / 現在の差分は妥当か]
    R --> M[マージ / リポジトリ変更を受理]
    M --> C{親の目的も完了した?}

IssueとPRだけで全部を表現する必要はありません。

変更が小さければIssue → PRで十分です。

設計判断が重ければ、その間に設計記録や設計PRを置きます。

Issueが主に保持するもの

Issueが強いのは、何を解く仕事なのかを保持することです。

問題
望む結果
対象範囲 / 扱わないこと
関係
完了条件
未解決の問い

問題
  ↓
望む結果
  ↓
対象範囲 / 扱わないこと
  ↓
完了条件

Issueは実装の全履歴を抱える必要はありません。

一方、目的そのものが変わったのにPR本文だけを書き換え、Issueを古いままにすると、仕事の識別が壊れます。

Pull Requestが主に提示するもの

Pull Requestが強いのは、実際の差分をレビューできることです。

何を変更したか
親Issue / 設計との関係
どの選択をしたか
何をテストしたか
何をまだしていないか
既知の限界
レビューで確認してほしい点

親Issueの目的
  ↓
具体的な差分
  ↓
検証の証拠
  ↓
レビュー
  ↓
マージ判断

PRが暗黙にやってはいけないのは、親Issueの目的を勝手に再定義することです。

実装中に「問題自体が違った」と分かったなら、PRの一節で確定するのではなく、Issueや設計の責任主体へ戻します。

設計PRと実装PRを分ける理由

すべての変更で分ける必要はありません。

しかし、次のような変更では「なぜその解き方を選ぶのか」を先にレビューする価値があります。

複数案にトレードオフがある
共有スキーマ / 契約を変える
権限の責任主体を変える
複数実行環境へ影響する
移行 / 巻き戻しコストが大きい

flowchart TB
    accTitle: 設計と実装を分離する流れ
    accDescr: Issueから設計記録、設計PR、実装PR、検証へ進み、設計受理と実装完了を別状態として扱う。
    I[Issue / 何を解く?] --> DR[設計記録 / なぜ・どう解く?]
    DR --> DP[設計PR / この設計を受理する?]
    DP --> IP[実装PR / 受理設計を差分へ]
    IP --> V[検証]

ここで重要なのは、

設計が受理された
  !=
実装済み
  !=
実行環境で有効
  !=
運用で検証済み

ということです。

AIはリポジトリに文書が存在すると、「もう実装されている」と誤認しやすいため、この状態分離は特に重要です。

進捗管理Issueは「設計」ではなく「進行」を持つ

一つの設計を複数PRで実装するとき、進捗管理Issueが役立ちます。

設計
  ├─ スキーマ
  ├─ adapter
  ├─ 移行
  ├─ docs
  └─ rollout

進捗管理Issueが持つのは、

分割作業
前提条件
依存関係
進捗
残る受け入れ条件
後続作業の責任主体

です。

設計の意味まで進捗管理Issueで再定義すると、正本が二つになります。

逆に、小さな変更へ毎回進捗管理Issueを追加すると保守費用になります。

レビューは「現在の差分」に対する証拠

レビューは、その後の変更まで永続的に保証する承認ではありません。

レビュー結果
  = ある差分 / 対象範囲を見た評価

マージ権限
  = 別の権限

レビュー後に大きな変更が入れば、鮮度を再確認する必要があります。

この分離はAIのレビュー担当を使う場合にも重要です。

レビューする能力があることと、マージしてよいことは別です。

コメントは重要だが、隠れた正本にしない

GitHubのコメントには重要な判断が残ります。

しかし、長く使う判断をコメントだけに残すと、後から見つけにくくなります。

flowchart LR
    accTitle: コメントの重要判断を正本へ昇格する流れ
    accDescr: コメントで出た重要判断が長期利用されるかを確認し、必要ならIssue、設計、方針など適切な正本へ昇格して元コメントを根拠として残す。
    C[コメントで重要判断] --> Q{長期的に使う?}
    Q -- いいえ --> E[議論 / 記録として保持]
    Q -- はい --> P[Issue / 設計 / 方針等へ昇格]
    P --> R[元コメントを根拠として参照]

コメントを無価値にするのではなく、長期的な権限・正本になるなら適切な責任主体へ昇格すると考えます。

マージは「親Issueの完了」と同じではない

PRのマージが証明するのは、基本的には、

そのリポジトリ変更が受け入れられた。

ということです。

必ずしも証明しないものがあります。

親Issueの全受け入れ条件
実行環境で有効化済み
移行完了
外部公開
後続リスク解消
進捗管理Issueの全分割作業完了

PRがマージされた
  ≠ 親の目的が完了
  ≠ 配備済み
  ≠ 公開済み
  ≠ 検証済み

この区別があると、「マージしたから全部クローズ」という機械的な誤りを減らせます。

すべてを重くしない

責務を分けることと、成果物を増やすことは同じではありません。

小さな変更なら、

Issue
  ↓
実装PR

で十分です。

設計判断を独立させる経路が必要なのは、独立した設計判断を残す価値があるときです。

責務分離
  !=
成果物の増殖

です。

まとめ

IssueとPull Requestの役割を一言で分けるなら、

Issue
  = なぜ、何を、どこまで解くか

Pull Request
  = 何を変え、どう確かめたか

です。

ただし本当に大切なのはこの文言そのものではありません。

目的、設計、差分、検証、進捗、完了判断を、一つの成果物へ暗黙に押し込まないこと。

AIとGitHubで長い仕事を続けるほど、この責務分離が効いてきます。

この記事を書いた人

shippo