mergekit

mergekit

プルリクエストのもう半分のライフサイクルです。あなたやエージェント、チームメイトなど、誰かがプルリクエストを作成した後、あなたがそれを 判断 する番になったとき、または自分のプルリクエストに変更が必要だと返ってきたときに実行するのが mergekit です。プルリクエストを git worktree に取得し、ブランチがすでに置かれている worktree があればそれを再利用して、プロジェクトを起動し、意見をまとめるために必要な情報をすべて含むレビュー資料一式を表示します。その後、待機します。マージの指示があればマージし、変更が必要であれば、すでに開いている worktree で修正します。

mergekit は、プルリクエストのマージを許可された唯一のスキルです。これは、PR ツールチェーンの他のスキルが守る「明示的な依頼なしにマージしない」というルールに対する、意図的な例外です。この権限は、「自動的にマージしない」(#never-merge-automatically) に記載された、ただ一つの厳格な前提条件によって得られます。つまり、毎回、人間が その特定のプルリクエスト を確認することです。確認がなければ、mergekit の権限は他のどのスキルとも変わりません。

コードについての意見は一切述べません。ソースを判断するのはコードレビューの仕事です。mergekit はレビューの準備を整え、あなたが下した判断を実行します。

このスキルが呼び出される場面

プルリクエストがすでに存在し、あなたがレビューしているか、作成者であるあなたに変更が必要だと返ってきた場合です。

• list. 「対応待ちのプルリクエストは？」「レビュー可能なプルリクエストを表示して」「mergekit list」。
• start <n>. 「PR #34 を取得してテストできるようにして」「#34 をレビュー用に準備して」「このプルリクエストを QA 用にチェックアウトして」。「Start #34 and sync」は、最新のベースへの同期も追加します。<n> は、ここでのすべてのモードで、デフォルトでは PR 番号です。
• close [<n>]. 「#34 をマージして」「このプルリクエストをクローズして」「これは問題ないので、取り込んで」「#34 は変更が必要です：」。番号が指定されていない場合、close は現在のブランチのプルリクエストを対象にします。
• fix <n>. 作成者側の作業です。「自分のプルリクエストが CI に失敗しているので直して」「#34 のレビューコメントに対応して」「自分のプルリクエストへのフィードバックに対応して」。対応する前にフィードバックを分類するため、見つけたコメントをすべてそのまま適用するわけではありません。

プルリクエストが指定されていても操作が指定されていない場合は、start と解釈します。プルリクエストの準備は安全で元に戻せますが、マージはそうではないためです。

このスキルの対象外： ブランチからプルリクエストを作成すること、またはコードの品質を判断することです。それぞれ、プルリクエスト作成スキルとコードレビュースキルの役割です。mergekit は、オープン中のプルリクエストから始まり、マージ済みまたは更新済みのプルリクエストで終わります。

自動ではマージしない

マージのたびに、そのPRをたった今レビューした人間から、PRごとの明示的な確認を得る必要があります。特定のPRをマージまたはクローズする直接の指示は、その確認にあたります。「#34 をマージ」「このPRをクローズ」、およびブランチにオープンなPRが1件あるワークツリーでの mergekit close は、すべて確認とみなされるため、mergekit は再確認せずにマージします。クローズモードに記載されているように、指示に疑問が残る場合、または状態に異常が見られる場合にのみ確認を求めます。具体的には次のとおりです。

• まとめて実行しない。「全部マージ」は、個々のPRに対する確認にはなりません。PRごとに一度、番号とタイトルを挙げて確認してください。
• **スタックの連鎖マージはひとつの操作なので、スタック内のすべてのPRを挙げた確認が一度必要です。**最上位のPRだけを挙げた指示では、その下のレイヤーは指定されていないため、連鎖マージでは必ず以下の列挙された確認を求めます。スタック内のPRをマージすると、その下にある未マージのPRもすべて下から順にマージされるため、最上位のPRに「はい」と答えたレビュー担当者は、すべてのPRに「はい」と答えたことになります。これは上記ルールの例外ではなく、ルールを正しく適用したものです。確認では、連鎖マージで取り込まれる各PRを、マージ順に番号とタイトルを付けて列挙するため、人間が名前を確認していないものがマージされることはありません。列挙されない連鎖マージは、このルールが禁止する一括処理そのものです。
• **レビュー済みのヘッドに限定する。**確認の対象となるヘッドSHAはひとつだけです。記録された start 時点のヘッド、または指示を受け取った時点で読み取ったヘッドです。確認後のプッシュは新たな変更となるため、新たなレビューと確認が必要です。また、GitHub による強制を確実にするため、マージ呼び出しには --match-head-commit を指定します。
• **推測しない。**CI が成功していること、レビューで承認されていること、未解決のスレッドがないこと、ローカルゲートに合格していることは、人間の判断材料であり、判断そのものではありません。CI がすべて成功しているPRであっても、確認があるまで待ちます。
• **暗黙に「はい」とみなさない。**mergekit が確認を求める場合、無回答ならマージされるような聞き方をしてはいけません。回答がなければマージしません。
• 副作用として実行しない。start はマージしません。修正ラウンドでもマージしません。マージするのは close だけで、確認を得た後に限ります。

同じプレビューと確認のルールは、同期のプッシュ、コメントの投稿、イシューのクローズなど、外部に影響するほかのあらゆる変更にも適用されます。実行内容を示して、承認を待ってください。

**ラベルの変更は、すべてのモードで例外です。**イシューまたはPRへのラベルの追加・削除は確認なしでそのまま実行されます。マージ済みPRのステータスラベルの削除、クローズ済みイシューの in-review または in-progress の削除、依存するイシューの blocked → ready への切り替え、優先度の設定などが該当します。ラベル変更は手軽で、目に見え、ひとつのコマンドで元に戻せます。また、変更を見送ると、トラッカーがマージ済みの作業について誤った状態を示すことになります。引き継ぎでは、ラベルの変更をすべて報告してください。この例外はラベルだけに適用され、それ以外には適用されません。

事前確認

すべてのモードはここから始めます。

gh --version && gh auth status              # GitHub CLI installed + authenticated
gh repo view --json nameWithOwner           # inside a repo

• gh が見つからない、または認証されていない場合は、その旨を伝え、https://cli.github.com / gh auth login を案内してください。別の方法で回避してはいけません。
• ベースブランチは gitkit から取得してください。main と決めつけたり、ここで独自に再導出したりしてはいけません。デフォルトブランチが develop や trunk のリポジトリも実在します。以下で origin/<base> と表記しているものには、gitkit が返す値を使用します。
• start と close では、ファイルシステムに触れる前に、PR が存在し、オープンであることを確認してください。

gitkit が担うこと

mergekit は worktree、base-ref の検出、rebase と merge のどちらを使うかのルール、worktree のセットアップを実装していません。これらは gitkit が担い、mergekit はそのすべてを gitkit に委ねます。mergekit が担うのは、いつ実行するかに関する方針です。つまり、PR を取得する価値があるか、merge に確認が必要かを判断します。同期するかどうかはレビュー担当者が決めることであり、mergekit が決めることではありません。 start はブランチがどれだけ遅れているかを報告して停止します。ただし、人間が同時に同期も依頼した場合（「#34 を開始して同期して」など）は除きます。それ以外の場合、人間が worktree 内で gitkit の sync を実行します。fix はすでにそのブランチにプッシュしているため、常に同期します。worktree のパス規約、base-ref の優先順位、または同期ルールが以下で mergekit 独自のものとして再掲されていたら、それはバグです。

gitkit がインストールされていない場合は、インラインで示されている通常の git コマンドにフォールバックします。ただし、同じ規約を維持し、別の規約を作り出さないでください。

モード

モードの本文はそれぞれ modes/ 内の 1 つのファイルにあります。When this fires に従ってルーティングし、そのファイルだけを読み、指示に従ってください。この行より上の内容はすべてのモードに適用されるため、モードのファイルには再掲されていません。

• モード list → modes/list.md を読み、指示に従ってください。
• モード start <n> → modes/start.md を読み、指示に従ってください。
• モード close [<n>] → modes/close.md を読み、指示に従ってください。
• モード fix <n> → modes/fix.md を読み、指示に従ってください。

注意事項

• merge の例外は限定的です。 人間が目の前にいる場合、mergekit は merge を実行できます。そのため、無人パイプライン内でサブエージェントとして実行してはなりません。確認に応答する人がいないうえ、「オーケストレーターが承認した」というだけでは人間によるレビューとは言えないためです。
• ポーリング、キュー、自動 merge はありません。 mergekit は呼び出されたときに実行されます。PR を監視せず、GitHub の自動 merge を有効にせず、スケジュールに従って動作することもありません。
• fix も対話的です。 レビューのフィードバックを読み、各コメントがこのプロジェクトにとって妥当かどうかを判断するのは、判断を要する作業です。そのため、mergekit は無人でこれを行わず、fix が自動パイプライン内で実行されることもありません。トリアージの手順では、人間が異議を唱えられるようにしています。そのためには人間がその場にいる必要があります。これは start に対する作成者側の対応にあたります。PR に対応しますが、ここにあるどのモードと同じく、merge は決して実行しません。
• 強制プッシュはリース付きで、ゲートを通過した場合に限ります。 fix は実行のたびに同期し、start は明示的な依頼がある場合にのみ同期します。また、gitkit の同期ルールはデフォルトで rebase を行うため、PR ブランチは書き換えられます。--force 単独ではなく、必ず --force-with-lease を使用し、古くなったレビュー スレッドの数を報告してください。履歴を整えるために強制プッシュしてはなりません。mergekit が強制プッシュするのは同期時だけであり、その同期は PR の修正依頼、または開始と同期の依頼によってすでに承認されています。
• フォークからの PR は読み取り専用です。 レビューと merge はできますが、修正をプッシュすることはできません。失敗してからではなく、セットアップ時にその旨を伝えてください。
• Bot のレビュー フィードバックは、レビュー担当者側では報告するだけで、解決しません。 list と start は未解決のスレッドを提示して停止します。それらを判断して返信するのは作成者の仕事であり、それを行うのが fix です。Bot の指摘に人間の指摘以上の権威はありません。変更する前に、どちらもプロジェクト独自の慣例に照らしてトリアージします。
• シェルや gh を利用できない場合（ブラウザベースのエージェントなど）、worktree の作成や gh の呼び出しはできません。ユーザーが提供した情報からレビュー パックを出力し、セットアップと merge のコマンドをコードブロックで提示して、ユーザー自身が実行できるようにしてください。実行できなかった merge が完了したと決して主張しないでください。