github-issue-to-pr

GitHub Issue からプルリクエストへ

GitHub Issue を、テストと検証を済ませた PR に仕上げます。このスキルでは、前提の検証、重複の調査、クラス全体の修正、CI の正確な報告など、最初から最後までの規律を担います。関連する GitHub スキルと開発スキルでは、それぞれの手順を扱います。

使用する場面

• 「Issue #123 を修正して PR を作成してください。」
• 「この GitHub の機能リクエストを実装してください。」
• 「このバグを Issue から CI が通る状態まで対応してください。」

次の用途には使用しないでください。既存の PR のレビューや、変更を求められていないコードに関する質問への回答。

手順

1. 現在の Issue を読む — 本文とスレッド全体

terminal を使って gh issue view <N> --comments を実行します。本文は Issue 作成時点のスナップショットです。最新のコメントには、すでにマージされた部分的な修正、新しい根本原因の分析、メンテナーの判断、タスクを変更するあなた宛ての質問など、現在の状況が記されています。また、read_file でリポジトリの指示書（AGENTS.md、コントリビューション用ドキュメント）も読みます。現在求められている動作、対象外の事項、未回答のスレッド内の質問を把握したら完了です。

2. 既存の作業や重複を調べる

何かを書く前に、gh pr list --search "#<N>" --state all と、症状に関するキーワードや同義語を少なくとも 2 種類使った検索（gh pr list --search "<subsystem> <symptom>" --state open）を実行します。人気の Issue には、複数の独立した修正が集まることがあります。重複した作業は、労力と成果を無駄にします。また、最近のコミットですでに修正されていないか、git log --oneline -20 -- <relevant files> で確認します。この Issue に関係するすべてのオープン PR と最近のコミットを把握するか、該当するものがないと確認したら完了です。

3. 現在のコードと設計意図に照らして前提を検証する

search_files と read_file を使って報告された経路をたどり、失敗するテストまたはフィクスチャで再現するか、現在のデフォルトブランチで不足している動作を示します。次に、もう 1 つの疑問を確認します。その「バグ」は、実は意図された設計ではないでしょうか。変更を求められているコードに対して git log -p -S "<symbol>" を実行し、元のコミットの意図を読みます。リンクや制限がないのは、多くの場合、機能として意図されたものです。Issue の説明が古い、または誤っている場合は、盲目的に実装するのではなく、その前提を問い直します。根本原因または機能の不足が現在のコードで確認でき、変更が意図的な設計に反していないと確かめたら完了です。

4. 受け入れ基準とリスクを定める

受け入れ基準、インターフェース、移行や状態変更、互換性、セキュリティとプライバシー、段階的なリリース、ロールバックを列挙します。各基準をテストまたは明示的な検証に対応付けます。レビューで確認する内容が明確に定まったら完了です。

5. 最小限かつ完全な変更を実装し、問題のクラス全体を修正する

独立したブランチまたはワークツリーで作業し、バグの種類に応じて systematic-debugging または test-driven-development を読み込みます。まず回帰テストを追加してから実装します。修正ができたら、search_files で隣接する呼び出し箇所にも同じ種類のバグがないか調べ、PR で問題のクラス全体を修正します。既知の隣接箇所を壊れたまま残す不完全な修正は、何もしないより悪い結果になります。変更したすべての行は Issue に根拠があるものとし、ついでのクリーンアップは行いません。対象のテストが通り、元の不具合が再現せず、隣接箇所も修正されているか、対象外であることが明示されていれば完了です。

6. 回帰テストで不具合を検出できることを証明する（サボタージュ実行）

テスト対象の関数を一時的に以前の動作に戻して新しいテストを実行し、失敗することを確認します。その後、修正を元に戻してテストが通ることを確認します。修正の有無にかかわらず通る回帰テストでは、何も証明できません。修正前のコードでテストが明確に失敗することを確認したら完了です。

7. リポジトリの品質チェックを実行して、すぐに PR を作成する

フォーマッター、リンター、型チェック、およびリポジトリで標準とされているテストのエントリーポイントを、影響を受ける領域に対して実行し、差分には requesting-code-review を使用します。その後、すぐにプッシュして PR を作成します。CI は PR の作成をきっかけに実行され、CI の待ち時間が最大のボトルネックです。完了した作業を放置しないでください。PR の手順については github-pr-workflow を読み込みます。ブランチ名とコミットメッセージは規約に従い、本文には問題、アプローチ、テスト、リスク、対象外事項を記載してイシューにリンクします。PR の内容を読み返し、head SHA、base、タイトル、ファイルを確認します。意図した差分で PR が作成され、CI が実行中であれば完了です。

8. CI の状況を正確に確認し、最後まで対応する

gh pr checks ／ gh run view --log-failed を使用して、実行中のチェックと失敗ログを確認します。差分によって発生した失敗と、既存のベースラインやインフラに起因する失敗を区別します。判断に迷う場合はデフォルトブランチで再現し、実際にインフラの一時的な不具合が原因の場合に限り、一度だけ再実行します。実際の状態を示す証拠なしに「成功」「マージ済み」「リリース済み」と決して言わないでください。PR がマージされたら、報告者が解決経緯を追跡できるよう、PR のリンクと一行の説明をイシューにコメントします。CI の状態、残っているブロッカー、イシューのスレッドがすべて実状を反映していれば完了です。

落とし穴

• イシューのコメントを読まず、重複する PR を調べず、現在のコードも確認せずにコーディングを始める。
• 元のコミットで意図した設計だと分かる動作を「修正」する。
• ある呼び出し箇所で症状を修正しても、同じバグが残る兄弟箇所を放置する。
• 修正がなくても通る回帰テストを追加する。
• 未実行のテストや無関係なフォーマット変更を含む PR を作成する。
• PR が存在することを理由に、イシューへの対応が完了したと主張する。

検証

• イシューのスレッド全体を読み、最新のコメントの状態を計画に反映した。
• イシュー番号とキーワードの異なる候補 2 つを使って、重複 PR を確認した。
• 現在のコードで前提を再現し、git の履歴で設計上の意図を確認した。
• 修正がない場合に回帰テストが失敗することを確認した。
• 兄弟箇所も修正した、または対象外とする理由を明記した。
• 変更したすべての行がイシューに関連している。
• CI の状態は実際に確認した証拠に基づいて報告し、PR のリンクをイシューにコメントした。