pr-maintainer

PR メンテナー

Codex または Claude Code が作成した PR をメンテナンスする際は、リポジトリに PR メンテナンスポリシー／ADR があれば、それに従ってください。

使用するタイミング

エージェントがドラフト PR を含む PR を作成した後、またはエージェントが作成した PR について、CI、レビューコメント、修正コミット、マージまで対応するよう依頼された場合に、このスキルを使用します。

また、エージェントが作成したドラフト PR がレビュー可能になった直後にも、ユーザーがエージェントセッション外で手動でレビュー可能にした場合を含め、このスキルを使用します。この変更を、CI とレビュー状況の監視開始の合図として扱ってください。

リポジトリのワークフローに従ってドラフト PR として作成しただけで、実装がリポジトリで合意されたローカル検証にすでに合格している場合（CI と同等の対象範囲については、プロジェクトのテストルールを確認してください）、同じセッション内でレビュー可能にし、直ちにポーリングワークフローに移行してください。--draft を付けて作成したという理由だけで、レビュー可能なドラフト PR を放置しないでください。

このスキルは Codex と Claude Code で共通です。GitHub への入出力には gh を使用します。エージェント固有の部分は、既存のワークツリーで修正を適用するコード編集セッションだけです。

基本ポリシー

• PR の作成に使用した同じエージェントセッションと専用ワークツリーで作業を続けてください。

• エージェントが作成する PR は、デフォルトでレビュー可能な状態にしてください。ユーザーが明示的にドラフトのみの公開を依頼した場合、または実装がまだレビュー可能でない場合を除き、gh pr create に --draft を指定しないでください。

• PR を作成した直後に、CI のポーリングや自動マージの設定を行う前に、ドラフトでない状態を保証してください。

  IS_DRAFT="$(gh pr view "$PR" --json isDraft -q .isDraft)"
  if [ "$IS_DRAFT" = "true" ]; then
    gh pr ready "$PR"
  fi
  
  IS_DRAFT="$(gh pr view "$PR" --json isDraft -q .isDraft)"
  if [ "$IS_DRAFT" = "true" ]; then
    echo "PR is still draft; aborting auto-merge setup."
    exit 1
  fi
  

• PR がレビュー可能な状態であれば、ドラフト PR の URL を伝えて終了しないでください。まずレビュー可能な状態にし、その後直ちにポーリングワークフローに移行してください。

• ユーザーがドラフトのみの公開を明示的に依頼した場合、ローカル検証が未完了または失敗している場合、意図的にレビュー可能な状態にしていない場合、または報告すべきブロッカーがある場合に限り、PR をドラフトのままにしてください。

• ユーザーがドラフト PR を手動でレビュー可能な状態に変更したと伝えた場合は、直ちにポーリングワークフローに移行してください。

• @codex fix や GitHub コメントを起点とする修正コマンドは使用しないでください。

• 最長 20 分間、3 分ごとにポーリングしてください。

• PR の状態、チェック、失敗したログ、コメント、Issue の作成、ラベル、返信、マージには gh／gh api を使用してください。

• CI の失敗やレビューでの指摘は、同じワークツリーで修正し、その後、リポジトリの通常のプッシュ前検証を実行してください。

• すべてのレビューコメントに日本語で返信してください。

• レビュースレッドを自動で解決しないでください。

• 修正ループは最大 4 回までとします。

• 4 回目の試行後も修正ループが続く場合、またはレビューの修正によって設計レベルの新たな指摘が生じた場合は、作業を停止し、設計についての協議にエスカレーションしてください。

• ボットレビューが問題なく完了し、必須チェックがすべて成功した場合に限り、人手を介さずにマージしてください。

• レビュー／コメントがない状態は、問題なしではなく「レビュー未完了」として扱ってください。

• スカッシュマージを使用してください。

• PR のマージ後は、プロジェクトの worktree ディレクトリ内にあるマージ済みワークツリーを直ちに削除し、.venv などのビルド成果物が残らないようにしてください（リポジトリの git-workflow ルールを参照してください）。

ポーリングのワークフロー

PR を作成したら、PR 番号と現在の head SHA をセッションメモリに記録します。isDraft が true の場合、 PR をレビュー可能かどうか判断します。

• レビュー可能な場合は、ポーリングを開始する前に gh pr ready "$PR" を実行します。
• レビュー可能でない場合は、メンテナンスをまだ続行できない理由をコメントまたは報告し、マージせずに停止します。

成功、修正が必要な状態、エスカレーション、タイムアウト、またはマージに至るまでループします。

状態を取得するコマンド：

gh pr view "$PR" --json \
  number,title,isDraft,headRefName,headRefOid,baseRefName,mergeStateStatus,reviewDecision,statusCheckRollup,labels

gh pr checks "$PR" --json name,state,bucket,link,startedAt,completedAt,workflow

レビュー完了の判定条件：

• CI が成功した直後にマージしてはいけません。

• PR レビュー、レビューコメント、issue コメント、issue リアクション、その他リポジトリ標準のボットレビュー成果物として、期待される Codex／ボットのレビューシグナルが現れるまでポーリングを続けます。

• Codex のレビュー状態は、PR の issue に対する chatgpt-codex-connector[bot] のリアクションで示されます。

  • eyes リアクション：レビュー中です。ポーリングを続け、まだマージしないでください。
  • +1 リアクション：問題のないレビューが完了しています。ブロッキングレビューコメントがない場合、ボットレビューが問題なく完了したものとして扱います。

• Codex の指摘は、issue レベルのコメントではなく、プルリクエストのインラインレビューコメントとして投稿されます。 gh pr view --comments ではインラインレビューコメントを取得できません。プルリクエストのレビューコメント用エンドポイントを使用して、必ず別途取得してください。GitHub の一覧エンドポイントはページネーションされるため、後続ページのコメントを見落とさないよう、必ず --paginate と per_page=100 を指定してください。

  gh api --paginate "repos/{OWNER}/{REPO}/pulls/$PR/comments?per_page=100" \
    --jq '[.[] | select(.user.login == "chatgpt-codex-connector[bot]") | {id, path, line, body: .body[:300]}]'
  

• P1 または P2 のバッジが付いた Codex のインラインコメントは、ブロッキング指摘です。未解決の P1／P2 インラインコメントは、+1 リアクションの有無にかかわらず、「レビューにブロッキング指摘あり」として扱います。

• CI が成功していても、レビュー、コメント、リアクションがまだない場合は、ポーリングのタイムアウトである 20 分まで待機を続けます。

• ボットレビュー成果物が存在し、ブロッキング指摘が含まれていないことを確認して初めて、レビューに問題がないと判断します。

• 20 分以内にボットレビュー成果物が現れない場合は、CI は成功しているものの、ポーリング時間内にレビューが完了しなかった旨を日本語で PR にコメントし、マージせずに停止します。

問題のないリアクションの状態を取得するコマンド：

gh api --paginate "repos/{OWNER}/{REPO}/issues/$PR/reactions?per_page=100"

GitHub の一覧エンドポイントに対するその他の gh api 呼び出しでは、単一のリソースを返すことが既知のエンドポイントを除き、--paginate と per_page=100 を使用します。最初のページだけの応答から、「レビュー成果物なし」または「ブロッキング指摘なし」と判断してはいけません。

CI ジョブが失敗した場合は、gh を使って失敗ログを取得します。

gh run view "$RUN_ID" --log-failed

gh pr view では不十分な場合は、レビューコメントとレビューのスレッドに gh api を使用します。GitHub API の応答は適切なサイズに抑え、大量のログは内容を推論する前に要約します。

修正ルール

CI が失敗した場合、またはレビューコメントで変更が必要な場合：

1. 失敗ログとレビューコメントを確認します。
2. 各指摘が妥当かどうか判断します。
3. 既存の PR 作業ツリーで、整合性のある最小限の修正を行います。
4. プッシュ前に、必要に応じてテスト、Ruff、mypy を含む、リポジトリ標準の検証を実行します。
5. 修正をコミットしてプッシュします。
6. すべてのレビューコメントに日本語で返信します。

返信形式：

対応しました。

- 修正内容: ...
- 修正commit: ...
- 検証: `...` passed

コメントに対してコードを変更しない場合：

この指摘は対応不要と判断しました。

- 理由: ...
- 確認内容: ...

エスカレーションルール

次のいずれかが発生した場合は、自動修復を停止してエスカレーションしてください。

• 4回目の修復を試みても、CI の失敗やレビューでの指摘が解消されない。
• 修復後、同じ責任範囲でレビューコメントが再発する。
• 修正にワークフロー／権限／シークレットの変更が必要である。
• 修正に main／default ブランチへの直接プッシュ、または履歴の書き換えが必要である。
• 修正に局所的な修復ではなく、大規模な設計変更が必要である。

自動修復で許可されるもの：

• アプリケーションコードの変更
• テスト
• ドキュメント
• DB マイグレーション
• 依存関係とロックファイルの更新

自動修復で許可されないもの：

• .github/workflows/** の変更
• GitHub Actions の権限変更
• シークレットまたは環境設定の変更
• main／default ブランチへの直接プッシュ
• Git 履歴の書き換え
• 大規模な設計のやり直し

エスカレーション時：

1. 利用可能な場合は、PR に設計／エスカレーションのラベルを追加します。
2. 設計上の問題と選択肢を説明する GitHub issue を作成します。
3. issue へのリンク、概要、選択肢、およびユーザーの判断が必要な内容を記載して、PR に日本語でコメントします。
4. マージせずに停止します。

マージルール

マージする前に、次の項目を確認してください。

• PR がドラフトではない。
• PR 作成後の事後条件により isDraft == false が確認されている。PR がまだドラフトの場合は、 gh pr merge --auto を実行しないでください。
• Head SHA が最後に確認した SHA と一致している。
• 必須チェックが成功している。
• ボットのレビューが完了しており、ブロッキングする指摘がない。
• PR のレビュー／コメント、または PR の issue リアクションに、想定されるボットレビューの証跡が含まれている。
• 修復ループの回数がエスカレーションのしきい値未満である。
• PR がエスカレーション状態ではない。

次を実行します。

gh pr merge "$PR" --squash --auto --delete-branch --match-head-commit "$HEAD_SHA"

GitHub から PR がマージされたことが報告されたら、共有チェックアウト（プロジェクトルート）に切り替えて、マージ済みの worktree を削除します。リポジトリにクリーンアップ自動化ターゲット（例：make worktree-cleanup-merged）が定義されている場合は、 それを使用します。そうでない場合は、worktree を直接削除します。

cd "$PROJECT_ROOT"
git worktree remove "$WORKTREE_PATH"

マージ済みの worktree や、その .venv を残さないでください。

状態

ループ回数、最後に確認した head SHA、レビュー生成に関する観察事項をセッションメモリに保持します。現時点では永続的な 状態を追加しないでください。セッションが失われた場合は停止してください。ユーザーから新たな指示があります。

参考資料

• リポジトリに PR のメンテナンスに関する ADR／ポリシー文書がある場合は、その文書（例：docs/decisions/ 配下）
• AGENTS.md／CLAUDE.md が存在する場合は、そのファイル