pr

プルリクエストスキル

明確なタイトルと変更内容を具体的に説明するプルリクエストのドラフトを作成し、CI のレビューを重ねて準備完了の状態にします。

手順

1. ブランチの変更を分析する：main から分岐して以降のすべてのコミットを把握します
2. リモートにプッシュする：すべてのコミットがプッシュされていることを確認します
3. PR のドラフトを作成する：マージ前のレビュー用として、必ずドラフトで作成します
4. レビューを重ねる：ドラフトに対する CI レビューを実行し、すべての判定が問題なしとなった場合にのみ準備完了に切り替えます（下記の「レビューラウンド」を参照）

PR タイトルの形式

PR タイトルには Conventional Commits の形式を使用します：

<type>: <description>

種類

• feat：新機能または新しい機能
• fix：バグ修正
• refactor：コードの再構成
• docs：ドキュメントの変更
• chore：保守作業
• perf：パフォーマンスの改善

タイトルのルール

• 70 文字未満にします
• 小文字を使い、命令形にします
• 末尾にピリオドを付けません
• *_ee.rs ファイルを変更した場合は、[ee] を先頭に付けます：[ee] <type>: <description>

PR 本文の形式

本文では、変更内容を必ず具体的に説明します。次の構成にします：

## Summary
<Clear description of what this PR does and why>

## Changes
- <Specific change 1>
- <Specific change 2>
- <Specific change 3>

## Test plan
- [ ] <How to verify change 1>
- [ ] <How to verify change 2>

スキルを呼び出したハーネス／ツールは、独自の帰属情報を末尾に追加する場合があります。スキル自体では、そのような記載は指定しません。

スクリーンショット（フロントエンドの変更では必須）

git diff main...HEAD --name-only が ^frontend/ に一致する場合、PR 本文には影響を受ける UI のスクリーンショットを必ず含めます。画面上に見える変化がない場合（型、テスト、ビルド設定）は省略できます。その場合は本文にその旨を記載します。

1. ブラウザーで変更を確認します（frontend/AGENTS.md →「フロントエンドの変更を確認する」を参照）。

2. mcp__playwright__browser_take_screenshot を使って、影響を受ける各ページのスクリーンショットを撮影し、ファイルに保存します。

3. 画像をホストし、公開リポジトリ windmill-labs/agent-screenshots-internal にプッシュして、Markdown の埋め込みコードを取得します。base64 は標準入力経由で渡してください。実際の画像では -f content=… を使うと argument list too long エラーになります：

   REPO=windmill-labs/agent-screenshots-internal
   IMG=screenshot.png                                          # repeat per page
   DEST="shots/$(git branch --show-current)/$(date +%s)-$(basename "$IMG")"
   base64 -w0 "$IMG" | jq -Rs --arg m "add $DEST" '{message:$m, content:.}' \
     | gh api -X PUT "repos/$REPO/contents/$DEST" --input - >/dev/null
   echo "![$(basename "$IMG" .png)](https://raw.githubusercontent.com/$REPO/main/$DEST)"
   

   ファイル名から $DEST を導出します（上記参照）。これにより、異なるページが同じパスで競合することを防げます。固定名を使うと、同じ秒にアップロードされたファイルでパスが再利用されます。その後の 2 回目の PUT は 422 エラーになります（Contents API では、既存ファイルを上書きするために既存ファイルの sha が必要です）。

4. 出力された ![…](…) の行を、PR 本文の ## スクリーンショット 見出しの下に追加します。

gh（repo スコープ）、jq、base64 が必要です。これらはすべて devShell にあります。ホストリポジトリは公開されているため、レビュー担当者はトークンなしで raw URL を表示できます。また、履歴は永久に残ります。シークレットや機密情報を表示するページ（ワークスペース変数、リソース値、インスタンス設定、OAuth／SMTP 設定など）は、絶対にスクリーンショットを撮らないでください。ファイルを削除しても、誤って取得した画像を取り消すことはできません。（GitHub のドラッグ＆ドロップアップローダーにはブラウザーセッションが必要なため、トークンでは操作できません。）

gh でホストリポジトリにプッシュできない場合（たとえば、CI トークンのスコープが windmill のみに制限されている場合）、PR を失敗させたり、黙ってスキップしたりしないでください。プッシュ権限のあるユーザーにアップロードを依頼し、完了したとの確認を受けてから続行します。

実行手順

1. git status を実行して、未コミットの変更を確認します

2. git log main..HEAD --oneline を実行して、このブランチのすべてのコミットを確認します

3. git diff main...HEAD を実行して、main との差分全体を確認します

4. PR を作成する前に差分をレビューします。両方のレビューを実行し、省略しないでください：

   • local-review — Claude ネイティブのブランチ差分レビュアーです（Claude Code では /local-review、Codex では $local-review、Pi では pi --skill local-review / /skill:local-review）。
   • local-review-codex — 独立した視点で、Claude のレビューが見落とす問題を見つけるための、CI と同じコールド Codex パスです（Claude Code では /local-review-codex、または bash .agents/skills/local-review-codex/run.sh）。codex CLI がない場合、またはそのスキルで指定されているバージョンより古い場合は、概要にその旨を記載して続行してください。codex が利用できないことを理由に PR を止めてはいけません。

   両方を実行してください。異なる問題を見つけます。いずれかで問題が見つかった場合は、修正してコミットしてから続行してください。

5. フロントエンド変更のスクリーンショット：git diff main...HEAD --name-only が ^frontend/ に一致する場合は、PR 本文を書く前に、上記の「スクリーンショット」に従って影響を受ける UI のスクリーンショットを撮影して埋め込みます（目に見える UI への影響がない場合のみ省略できます）。

6. リモートブランチが存在し、最新の状態かを確認します：

   git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "no upstream"
   

7. 必要に応じてリモートにプッシュします：git push -u origin HEAD

8. gh CLI を使ってドラフト PR を作成します：

   gh pr create --draft --title "<type>: <description>" --body "$(cat <<'EOF'
   ## Summary
   <description>
   
   ## Changes
   - <change 1>
   - <change 2>
   
   ## Test plan
   - [ ] <test 1>
   - [ ] <test 2>
   EOF
   )"
   

9. PR の URL をユーザーに返します

10. PR の CI レビューレウンドを進め、準備完了の状態にします（下記の「レビューレウンド」を参照してください）

レビューロウンド（ドラフト → 準備完了）

PR がドラフトを抜けるのは、CI レビューロウンドが問題なく完了した後だけです。それより前に gh pr ready を実行してはいけません。 これは、自律モードを含むすべてのモードで適用されるルールです。問題のないロウンドは必要ですが、それだけで十分とは限りません。以下の「準備完了にするか、先に確認する」を参照してください。唯一の例外は、その PR をドラフトのままにするよう明示的に依頼された場合です（通常は、先にテストするためです）。その PR では依頼に従い、次の PR には引き継がないでください。

1. ロウンドを開始して完了を待つ：待機処理をバックグラウンドの Bash タスクとして起動します（ロウンドには 10～30 分かかります。終了すると通知されるため、実行中にセッションを停止したり、フォアグラウンドでポーリングしたりしないでください）。

   bash .agents/skills/pr/review-round.sh <PR_NUMBER>
   

   PR に /review をコメントします。これにより、ドラフトであっても Codex、Claude、Pi の CI レビュアーが実行されます。起動された PR Review Commands ワークフローの実行が完了するまで待機し、その後、レビュアーごとに判定を 1 行ずつ出力し、レビューコメント全文をファイルに保存します。

   /review（および /codex）は同じ head SHA に対して冪等です。実行中または成功済みのレビューが現在の head を対象としている場合、そのエージェントはスキップされ、新しい投稿は行われません。待機処理はその head の既存の判定を読み取るため、スキップされたエージェントがレビュー不足になることはありません。キャンセルまたは失敗した head の実行はその場で再実行され、head を対象とする実行がない場合に限り、新しい実行が起動されます。そのため、head を変更せずにレビューをやり直してもほぼ何も起きません。レビューを本当にやり直すには、コミットをプッシュしてください。

2. ロウンドの判定。Codex は必須です。Claude、Pi、cubic は、レビューを投稿した場合に判定に含めます。各レビューは、REVIEW.md に定義された 3 種類の判定のいずれかで始まります。

   • Codex の判定がない → ロウンドは無効です。head に成功した Codex 実行がない場合（キャンセル、失敗、または未実行の場合。すでにレビュー済みのためのスキップは除く）に限り、待機処理が警告します。PR に /codex とコメントすると、中断された実行がその場で再実行されます（実行がない場合は新たに起動されます）。同じ方法で完了を待ち、再度判定してください。
   • **「マージ前に問題への対応が必要」**が 1 つでもある → P0/P1 の指摘を修正し（その際に細かな指摘にも対応し）、コミットしてプッシュし、新しいロウンドを開始します（手順 1）。
   • **「マージ可能ですが、できれば細かな指摘にも対応してください」および／または「マージして問題ありません」**のみ → 細かな指摘にも対応してください。誤りである、または本当に修正する価値がない細かな指摘は、理由を添えてレビューコメントに返信し、却下してもかまいません。細かな指摘のみを修正した場合はプッシュしますが、ロウンド全体を再実行する必要はありません。

3. マーカーコメントを付けて準備完了にする。PR 作成者が現在の head SHA を示すマーカーを投稿しており、かつ PR に対する最新の Codex レビュー（マーカーより前に投稿されたもの）の判定がブロック対象でない場合、レビューのワークフローは ready_for_review によって起動される重複ロウンドをスキップします（これはレビュアーのレビュー結果に基づきます。ロウンドを経ていない単独のマーカーや、マーカーより前の最後の Codex 判定が「問題への対応が必要」の場合、スキップされません）。プレフィックスは正確に保ち、準備完了にする head の 40 文字すべての SHA を使用してください。

   • すべての判定が「マージして問題ありません」だった場合（ロウンド以降、head に変更がない場合）：

     ✅ Review round clean @ <head-sha>

   • 細かな指摘のみのロウンドで、その後に指摘を修正または却下した場合（head がレビュー対象の SHA より先に進んでいる可能性があるため、その旨を示します）：

     ✅ Review round clean @ <head-sha> — nit-only verdicts at <round-sha>; nits addressed in <commit sha(s)> / dismissed in review replies

   gh pr comment <PR_NUMBER> --body "✅ Review round clean @ $(git rev-parse HEAD)"
   gh pr ready <PR_NUMBER>
   

   P0/P1 の指摘に未対応のものがある場合、または細かな指摘の修正以外の理由で head が変更された場合は、マーカーを投稿したり準備完了にしたりせず、代わりに別のロウンドを実行してください。

ラウンドが始まらない場合、たいていは競合です

レビューのワークフローはマージできない PR では実行されないため、判定が出ないラウンドは、CI の障害というより main との競合であることがほとんどです。問題が起きていると決めつける前に確認してください。

gh pr view <PR_NUMBER> --json mergeable,mergeStateStatus

リベースではなくマージで解決してください。リベースするとラウンドの判定とクリーンラウンドのマーカーがキーとしている head SHA が書き換わり、すでに費用をかけて得た作業結果が無効になります。

git fetch origin main
git merge origin/main

マージによって backend/ee-repo-ref.txt が変更された場合は、EE のワークツリーもそれに合わせてください。 このファイルは CE のビルド対象となる EE のコミットを固定します。そのため、このファイルを進めるマージを行うと、EE のチェックアウトが CE の期待する状態より遅れ、cargo check --features private はあなたも CI も意図していないツリーをコンパイルします。

git -C <ee-worktree> merge "$(tr -d '[:space:]' < backend/ee-repo-ref.txt)"

両方をプッシュしてから、新しいラウンドを開始してください。head が移動したため、それ以前の判定は適用されなくなります。

切り替えるか、先に確認するか

クリーンなラウンドになれば切り替えの条件は満たしますが、常に無人で切り替えてよいとは限りません。まず差分から影響範囲を判断してください。ほとんどの場合、git diff --name-only main...HEAD で確認できます。

次の場合は、切り替える前に確認してください。

• *_ee.rs に触れている（シンボリックリンク経由で EE リポジトリにも関わり、対応する PR も必要です）
• backend/migrations/ にマイグレーションを追加している
• openapi.yaml、openflow.openapi.yaml、または生成されたクライアントを変更している
• 認証、権限、またはトークンの処理に触れている
• 共有ワーカーのインフラストラクチャ（ジョブポーラー、handle_child、エグゼキューター）を変更している
• REVIEW.md の「Checklist for new public surfaces」に該当する

自己完結している変更なら、確認せずに切り替えてください。単一ファイルの修正、テストのみ、ドキュメントのみ、1 つの呼び出し箇所のみで、新たなパブリックサーフェスがない変更が該当します。

無人実行（単発実行）では確認する相手がいないため、判断基準は変わりませんが、実行できるアクションは限られます。自己完結している変更は切り替え、それ以外はクリーンなドラフトのままにして、その理由を PR の説明に記載してください。たとえば、left in draft: adds a migration, wants a human look before ready のように書きます。ラウンドの結果がクリーンだからといって、影響範囲の広い変更を切り替えてはいけません。また、誰も読むことのない質問をしてはいけません。

AGENTS.local.md（gitignore 対象のため、存在しない場合があります）には、「PR ready calibration」セクションがあり、過去の判断に迷うケースの結果が記録されています。判断する前に読んでください。なお、まだ本当に判断が難しい場合は確認し、その答えを追記してください。次回はより判断しやすくなります。

ラウンドが収束しない場合

クリーンな判定がないまま 3 ラウンド以上続く場合、独立したバグが尽きないというより、変更の形が適切でないことがほとんどです。次のような兆候があります。

• ラウンドを重ねても、同じファイルで指摘が続く
• ある指摘を修正すると、次の指摘が発生する
• 指摘の内容がロジックの誤りではなく、結合、重複、または多くの箇所にまたがる状態に関するものである

このパターンに当てはまる場合は、ラウンドを続けないでください。ラウンドごとに CI のサイクルが必要になり、収束する見込みもありません。残っている指摘は偶発的なものではなく構造上の問題に見えると明確に伝え、指摘が集中しているモジュールまたは境界を示してください。ユーザーがいる場合は、その領域に対して /improve-codebase-architecture を実行するよう提案してください。これはスラッシュコマンドでしか実行できないため、あなた自身では呼び出せません。また、コードの再構成はスコープ変更にあたるため、ユーザーが選択する必要があります。無人実行の場合は、診断内容を PR の説明に記載し、それ以上ラウンドを重ねずに終了してください。

EE の対応 PR（*_ee.rs ファイルを変更した場合）

windmill リポジトリの *_ee.rs ファイルは windmill-ee-private へのシンボリックリンクです。windmill リポジトリの git diff には変更が表示されません。代わりに EE リポジトリで、コミットされていない変更やプッシュされていない変更を確認してください。

docs/enterprise.md に記載された EE PR ワークフロー全体に従ってください。PR に関する主な注意点は次のとおりです。

1. EE リポジトリ／ワークツリーを見つけます。docs/enterprise.md の「Finding the EE Repo」を参照してください
2. 変更を確認します。git -C <ee-path> status --short
   • EE リポジトリに変更がなければ、このセクション全体をスキップしてください
3. docs/enterprise.md の「EE PR Workflow」の手順 1～5 に従ってください
4. 対応する PR を作成します（タイトルに [ee] の接頭辞は付けません）。

   gh pr create --draft --repo windmill-labs/windmill-ee-private --title "<type>: <description>" --body "$(cat <<'EOF'
   Companion PR for windmill-labs/windmill#<PR_NUMBER>
   EOF
   )"
   

5. ee-repo-ref.txt をコミットし、更新した windmill ブランチをプッシュします