create-pr

PR の作成

現在の変更を、検証済みで正確な説明が付いた、レビュー可能なプルリクエストとして公開します。この依頼では、リポジトリで定められたゲート、関連するコミット、PR メタデータの更新、通常のドラフトプルリクエスト 1 件、または変更が所有することを確認済みのネイティブスタックレイヤー、必要なレビューと動作テスト、対象範囲内の修正、レビュー可能状態への移行が許可されます。これには、変更のテストに必要な場合、プロジェクト既存の PR プレビュー経路も含まれます。マージと統合後の配信は /deliver の担当であり、直接依頼された場合は 配信設定に従って引き続き実施します。この依頼で無関係な変更を追加することはありません。

チェック、レビュー、CI の実行に失敗した場合は、停止するのではなく修復に進みます。公開するものがない場合、 重大な未解決の選択肢または新たな権限が必要な場合、安全な代替手段を使い尽くしても外部のブロッカーが残る場合に限り、停止します。 公開の前提となる重大な選択肢がある場合は、プッシュやドラフト PR の作成前に停止します。 必要な証拠や CI が不足、保留中、または失敗している間は、PR をドラフトのままにします。

条件付きの参照資料

• ブランチがネイティブ GitHub スタックに属する場合、または未マージの PR を基盤としている場合（手順 1）、../git-workflow/references/github-stacks.mdを読みます。 この場合、依頼で許可されるのは、現在の変更が所有することを確認済みのスタックレイヤーの提出とメタデータの整合のみであり、無関係なブランチは対象外です。
• 変更に目に見える動作や実演可能な動作がある場合、またはローカルのスクリーンショットや動画を PR に含める場合は、references/walkthroughs.mdを読みます。この資料では、メディアの撮影、アップロード、欠落の報告を扱います。証拠となるメディアをリポジトリにコミットしてはいけません。メディア機能が利用できないことだけを理由に、公開やレビュー可能状態への移行を妨げてはいけません。必要な動作の証拠とプロジェクトのゲートは引き続き適用されます。

プレビューのみのドラフト

必要な動作を PR プレビューでしかテストできない場合は、利用可能なチェックに合格した後、この公開依頼のもとで、そのテストに必要なドラフトを作成または更新します。ネイティブスタックに必要なドラフトは、同じ許可済みのスタック経路を通じて公開します。その正確なリビジョンをテストし、レビュー可能状態にする前にループを再開します。ウォークスルーの記録は、動作テストの代わりにはなりません。

ワークフロー

1. 作業ツリー、ステージ済みの差分、最近のコミット、リモートのデフォルトブランチ、該当する場合はスタックの構成、既存のリモートヘッドを確認します。無関係なローカル作業は保持します。

   PR のターゲットはリモートのデフォルトブランチです。例外は、ユーザーが指定するか、AGENTS.md や CONTRIBUTING.md などのプロジェクトの指示に記載された長期運用のベースブランチです。たとえば、バックポート用のリリースブランチが該当します。この場合は指定されたベースブランチを使います。オープン中の PR のフィーチャーヘッドであるだけのブランチは、指定されたベースブランチにはなりません。指定されたベースブランチとスタックの参照資料にあるネイティブスタック操作を除き、デフォルト以外のブランチを手動で PR のベースに設定してはいけません。 ベースを選ぶ前に、変更が未マージの PR を土台としているか確認します。 次のコマンドでオープン PR を一覧表示します。 gh pr list --state open --limit 1000 --json number,headRefName,headRefOid,isCrossRepository,baseRefName。 一覧の行数が上限と同じ場合、切り詰められている可能性があります。上限を 増やして、返される行数が上限を下回るまで再度一覧表示するか、そこで停止して報告します。 一覧を取得したリポジトリのリモートから、次のように一度に git fetch REMOTE pull/A/head pull/B/head ... を実行して各 head を取得します。このブランチ自身の PR、このブランチの head を含む PR、同じリポジトリ内で head ブランチが指定されたベースである PR は除外します。PR N がこのリポジトリのもので、 head ブランチが意図したベースである場合、または git rev-list HEAD ^BASE ^DEFAULT と git rev-list HEAD-OID ^BASE ^DEFAULT がコミットを共有する場合、この変更は PR N を土台としています。DEFAULT は取得したリモートのデフォルトブランチ、BASE は取得した指定ベースまたは DEFAULT、 HEAD-OID は N の headRefOid です。フォークの PR（isCrossRepository）に一致した場合は、 ここではベースにできないため、停止して報告します。指定ベースがある場合、他のブランチを 土台とする一致があった場合も停止して報告し、バックポートがデフォルトの幹に積み重ならないようにします。 それ以外の一致は、スタック参照の「スタックを開始するタイミング」に従ってネイティブスタックとして公開します。

2. リモートベースより先にある関連する変更やコミットがない場合は停止します。 すでにコミット済みであれば、空コミットを作成せずに続行します。

3. 現在ベースブランチにいる場合は、課題または変更に基づいた名前で、対象を絞ったブランチを作成します。

4. 何かを公開する前に、PR の主張と公開要件を明確にします。明示的な依頼、リンクされた課題または確認済みのミニ仕様、適用されるプロジェクト指示、製品ドキュメント、ADR または永続的な決定、 最も近い DEFINITION_OF_READY.md、および実装ワークフローで提供された完了証拠を確認します。 主張の根拠となる情報源がない場合は、コミットと差分が裏付ける最も限定的な主張を再構成し、 推定であることを明記します。

5. 現在の要件と変更に対して /code-review fix-all と /test-against-spec fix を適用します。内容、コマンド、 環境、網羅範囲が引き続き一致する結果のみ再利用し、不足または古くなったレビューと実際のインターフェースの確認を実行します。主張を差分から推定した場合は、 仕様テストの前に期待される動作を明示します。実装から要件を作り出すことなく、重要な曖昧さを解消します。

6. 確認済みの対象要件、忠実性、テスト、互換性に関する不足は、重大度にかかわらずすべて /implement の開発ループを通じて修正します。対応するスキルを利用できない場合は、文書化された同じチェックを直接実行します。編集後、公開または準備完了とする前に、影響を受ける範囲についてレビューと仕様テストを改めて実施します。対象を絞った指摘の再検証では、変更されていないレビュー範囲を再利用できますが、指摘を修正しただけではレビュー結果は更新されません。修正が収束したら、不足している、または無効になったプロジェクトゲートを実行します。

7. git-workflow に従って、未コミットの関連作業をコミットします。関連ファイルのみをステージし、シークレットや無関係なローカル作業は除外して、簡潔な Conventional Commit の件名を使用します。amend は行わず、フックもスキップしません。すでに公開された履歴は保持し、修正には新しいコミットを追加します。コミット、push、PR の書き込みのたびに、公開ガードを実行します。

8. 各プルリクエストのタイトルには、変更全体を表す Conventional Commit の件名を使用します。git-workflow の squash merge により、そのタイトルがベースブランチ上のコミットの件名になります。 本文のセクション順と文字数制限については、 ../agent-writing/references/pr-descriptions.md に従い、明示的なプロジェクトテンプレートの要件を保持します。すべての PR テンプレート見出しを原文のまま、順番どおりに保ち、書くことがない見出しの下にも、1 行の None または理由を記載します。これは省略できる定型文ではありません。作成者による検証内容は本文のセクションに含めず、最終引き継ぎで報告します。レビュー結果は本文末尾の レビューとステータス結果 にのみ記載します。本文を書く前に、オープンおよびクローズ済みの課題と、関連する指摘や重複がないか、利用可能であれば最近の関連セッションや隣接ブランチを検索します。クローズキーワードは変更の概要の後に Closes #N の形式でそれぞれ独立した行に記載し、その課題を完了するレイヤーにのみ記載します。 下書きに対して template-check を --kind pr --body FILE 付きで実行し、公開前に報告された見出しの問題をすべて修正します。

9. 公開チェックに合格した後、または上記のプレビュー専用下書きルールに従う場合は、通常のブランチを通常どおり push し、必要に応じて upstream を設定してから、リモートのデフォルトまたは指定ベースを対象にドラフト PR を 1 件開きます。 確認済みのネイティブスタックでは、スタック参照に従います。凍結された承認済み PR の上に新しい最上位レイヤーを作成する場合は、保護された push、個別の PR 作成、ネイティブな追加を使用します。凍結された下位 PR 上に新しいスタックを作成する場合は、保護された gh stack link を使用します。より広範な送信が許可されている場合は、gh stack submit を使用します。公開するすべてのレイヤーについて、最新の証拠を必須とします。rebase または force-with-lease を伴う push が許可されるのは、ガード付きの公式スタック操作のみです。下から上へのトポロジーを維持し、各レイヤーはドラフトのままにします。

10. PR 固有のフェーズを実行します。実際の PR 差分、本文、リンク、メタデータ、コミット済みのテストとドキュメント、提供された完了証拠、および公開後にのみ確認できる事実を比較します。ライブの本文に対して --pr N 付きで template-check を実行します。見出しの問題が報告された場合、それはメタデータのみの不足です。メタデータのみの不足は、コミットせずに修正します。

11. PR 固有のフェーズまたは CI により、対象範囲内のリポジトリ、動作、忠実性、テスト、ドキュメント、互換性に関する不足が判明した場合は、開発ループを通じて修正します。影響を受ける要件を再検証してから、同じ PR に対して /update-pr を使用し、新しい head を確認します。確認済みの要件不足がすべて解消されるまで続けます。

12. delivery-wait の wait checks-terminal 操作を、その実行ルールに従って実行します。リポジトリ、PR 番号、正確な head、--all-workflows、絶対期限、--json を指定します。--all-workflows は、後続の段階で追加されるジョブも含め、head 上のすべての GitHub Actions の実行とジョブが完了するまで待機します。コミットステータスや、適用される他のアプリのチェック（デプロイプレビューなど）ごとに --check を 1 つ追加します。待機開始時に表示されているチェックだけから --check の一覧を作成してはいけません。その一覧は部分的であることがよくあります。ディスパッチされた実行のチェックが PR に表示されない場合は、wait workflow-terminal --run-id <id> --head <sha> も実行します。意味のある状態遷移を受動的に待ちます。受動的な待機の代わりにモデルターンの繰り返しを使わず、ホスト機能を利用できない場合は報告します。失敗ログを調べ、対象範囲内で原因が確認された場合はステップ 11 に戻します。想定される PR チェックが実行されていない場合は、マージ可能かどうかを調べ、再実行を検討する前に、確認済みの競合を /update-pr で解消します。利用できない外部依存関係は、合格ではなく保留またはブロックとして扱います。現在の head に対して待機結果がチェックを満たしたと報告した後にのみ CI がグリーンとし、その旨を平易な言葉で伝えます。ローカルチェックの合格は、テスト対象の内容に対する実際の結果に基づいて判断します。失敗ログで断続的な失敗が確認された後にのみ、失敗をフレークまたは一時的なものとして扱います。変更以外を原因として非難する場合や、失敗を修正対象から外す場合は、個別の証拠が必要です。変更によって発生したフレークな失敗は対象範囲に含まれます。

13. 公開フェーズと PR 固有フェーズで必要なものがすべて揃い、適用されるすべての CI が正確な head に対してグリーンであることを確認したら、レビュー可能な状態にします。影響を受けるすべての URL とリンクされた課題、該当する場合はネイティブスタックの順序、最終状態、メタデータの変更、提供された完了証拠、公開ガードが書き換えた内容、確認された準備完了状態と CI の証拠を報告します。PR が準備完了であっても、未完了のウォークスルー要件と、実行可能な解決策を含めます。直接開始された場合は、配信設定に従って続行します。entry-points: deliver の場合、準備完了の PR は /address-feedback に進みます。