resolve-renovate-pr

renovate が作った依存アップデート PR を、マージできる状態まで持っていく。そもそも上げてよいかを先に判断し、CI の失敗をコード起因・承認待ち・一時的な不調に切り分けて、追随が要るものを直す。検討したことは PR にコメントで残す。マージと approve はしない。ユーザーが「renovate の PR を解決して」「依存アップデートを片付けて」「/resolve-renovate-

SKILL.md

GitHub

renovate PR はライブラリ側が変わっただけの PR です。差分そのものはバージョン文字列とロックファイルしかなく、直す対象はこちらのコードになります。通常の PR とは逆で、差分をレビューするのではなく、差分が引き起こす追随を探す作業です。

終点はマージではなく「マージできる状態」。マージと approve はユーザーが決めます。

対象

patch は automerge される設定であることが多い(renovate 設定の automerge )。それでも open で残っているなら、automerge が効かなかった、つまり CI が通っていないということなので、対象に含めます。

引数が無ければ open な renovate PR を一覧し、どれを扱うか尋ねる。

gh pr list --author "app/renovate" --state open --json number,title,mergeStateStatus,headRefName

進め方

1. 何を上げる PR かを読む

  • PR 本文の表: パッケージ名と before → after。1つの PR が複数パッケージをまとめていることがある
  • ブランチ名の prefix( renovate/major-* 等)で更新種別を判定する
  • リポジトリの renovate 設定( renovate.json / .github/renovate.json / package.json の renovate キー)

設定にはたいてい運用が書いてあります。 誰がマージするか・approve が要るか・automerge するかが更新種別ごとに分かれている。CI 側にも同じ分岐があるので .github/workflows/ も見る。ここを読まずに進めると、後から「approve が要る PR だった」と気づくことになります。

2. 上げてよいかを、最新事情を調べたうえで判断する

追随を書き始める前に決める。 上げるべきでない依存の追随に時間を費やすのが、この作業で最も高くつく失敗です。

ただし「無理」と結論するにも裏取りが要ります。 依存の状況は週単位で動き、学習時点の知識は必ず古い。上流が回避策を公式に出していることもあります。

調べるもの 当たる一次情報
そのバージョンの成熟度 公式のリリースアナウンス。GA か RC か、既知の制約は何か
周辺ツールが追随しているか npm view <pkg> peerDependencies で実測する。 対応表を書いた記事ではなく、公開されている範囲そのもの
上流が対応を表明しているか 本家リポジトリの issue。not planned で閉じているのか、着手中なのか
公式の回避策 互換パッケージ・移行ガイド・エイリアス指定。「API が無い」と「使う手段が無い」は別

Web で調べ、検索結果の要約で止めない。 要約は出典を落とすので、リンク先の原文まで開く( verify_before_asserting.md )。公式ドキュメントと移行ガイドは /context7-mcp で引き、リリースのページや記事は /ax で開く。ユーザーが参考記事を渡してきたら、それも読む。

見送りに傾く兆候 上げられる目
破壊的変更が、こちらの使い方に直撃する 移行手順が公式に用意されている
周辺ツールが「experimental」「未対応」と明示している 公式が互換パッケージや別名インストールを案内している
出たばかり / RC / prerelease GA 済みで、既知の制約に回避策がある
上げる動機が「新しいから」だけ 脆弱性・必要な機能・他の更新の前提になっている

こちらのどこが壊れるかは /pstack:blast-radius で洗い出す。 破壊的変更の一覧を読んでも、それがこちらのコードのどこに当たるかまでは分かりません。あちらは上げても安全と言える根拠を1〜2点に絞り、実際にコードを動かして確かめるところまでを持ちます。

「見送り」と書く前に、手順3で実際に動かす。 動かさずに出した結論はたいてい外れます。

見送ると判断しても、PR を閉じない・renovate 設定に無視ルールを書かない。 どちらも取り消しにくく、依存と CI の方針はユーザーの領分です( ask_before_editing_claude_assets.md )。理由を PR へコメントし(手順7)、判断を仰ぐ。

3. ローカルで再現する

CI の完了を待つより速く、失敗の全文が読めます。そして CI ログの読み取りを検算できます。

git fetch origin <renovate ブランチ>
git worktree add --detach <一時パス> origin/<renovate ブランチ>

作業ツリーを汚さないよう worktree を使う。 依存を入れ直すので、今のツリーで試すと戻すのが面倒になります。

base を取り込んでから測る。 GitHub Actions の pull_request は、ブランチ単体ではなくPR を base へマージした結果を チェックアウトします。ブランチのまま試すと通ったのに CI では落ちる、という食い違いはここから出ます。 base から遅れている PR ほど差が大きいので、git rev-list --count HEAD..origin/<base> で遅れを見てから決める。

ロックファイルを手で編集しない。 依存を入れるのはパッケージマネージャの仕事で、手で書いた木は解決できない組み合わせになります。ロックの通りに入れてから、リポジトリ既定のコマンドで build / lint / test を流す。

パッケージマネージャ自身のメジャー更新では、非対話で止まることがある。 既存の依存ディレクトリを作り直す前に確認を求める実装があり、 TTY が無いと中断します( ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY 等)。CI=true のような非対話フラグを付けて流す。

重いのでバックグラウンドで流し、待つ間に1の調査を進める( background_heavy_work.md )。

新しいバージョンだけを base に当てて測る手もある。 パッケージマネージャの一時実行( pnpm dlx <pkg>@<version> 等)を使えば、 base のツリーはそのままに、そのツールだけ新しくして検査できます。 renovate ブランチ一式を入れ直すより速く、どの変更がどの失敗を生んだかの切り分けもしやすい。

落ちたタスクと、原因のタスクは違うことがある

タスクランナー(turbo 等)では、lint が build に依存していることがあります。 すると build の失敗が lint の失敗として表に出ます。落ちたタスク名だけ見て lint の設定を疑うと、原因に辿り着けません。

ビルドが途中で失敗すると、中間生成物がソースツリーに残ることがあります。 それを次のタスクが検査して、無関係に見えるエラーが大量に出る。まず元のエラーを直し、生成物を掃除してから測り直す。

CI ログは複数タスクの出力が混ざります。 どのタスクのエラーかを取り違えたまま原因を組み立てると、実測で覆ります。ローカルで同じ失敗が再現することまで確かめてから、原因として書く。

ビルドが通ることと、動くことは別

build / lint / test はどれも「動かさずに確かめる」検査です。 型が合ってテストが通っても、 起動したら落ちることがあります。依存の初期化順、実行時にしか読まれない設定、バンドル後にだけ現れる解決の失敗は、静的な検査では出ません。

バージョンを上げたら、一度は実際に動かして応答を確かめる。

対象 確かめ方
Web アプリ 開発サーバを起動し、HTTP で叩いて200を確認する
ライブラリ 生成物を取り込む側から import して、代表的な関数を1つ動かす
CLI --version か、最小のサブコマンドを実行する

/ が404でも慌てない。 basePath や認証で弾かれることがあります。そのアプリの公開パス(healthcheck 等)を探して叩く。 404ページ自体が正しく描画されているかも手がかりです。タイトル・スタイル・スクリプトが揃って出ていれば、ビルドと配信は動いています。

起動に環境変数が要ることがあります。 用意できないなら「起動確認はできていない」と報告する。黙って飛ばさない。

速度改善が売りの更新なら、before / after を測る

「N 倍速い」と謳われている更新では、自分たちのコードベースで何倍になるかを実測する。 リリースノートの数字はベンチマーク環境のもので、手元の構成では同じ効果が出ないことがあります。

測るもの なぜ
その更新が直接速くする工程 速くなるはずの主な工程
CI 全体 速くならないこともある。 速くなる工程が CI の経路に入っていなければ変わらない
周辺の工程(build / lint / test) 「全部速くなる」という誤解を防ぐ

before は、PR の差分表が示すバージョン。 「 ^5.7.2 → ^7.0.0 」なら before は5系です。 追随の過程で入れた互換パッケージや中間バージョンと比べても、それは before ではありません。

前後を並べること自体と、計測の作法は base_records_on_measurements.md が定めます(「改善を主張するなら、前と後を並べる」と「速さを測るなら、3回測って平均を取る」)。 この節が足すのは、renovate の PR でしか要らない判定(before をどのバージョンに取るか・CI 全体も測るか)だけです。

結果は PR に残す(手順7)。速くならなかった工程も書く。期待とのズレは数字より先に伝わるべき情報です。

4. CI の失敗を3つに切り分ける

最も多い事故は、承認待ちをコード起因と読み違えて直そうとすることです。

種類 見分け方 やること
コード起因 ビルド・型・lint・テストのエラーが出ている 5へ
承認 / 権限待ち approval required のような、コードに一切触れないログ 直せない。 状態として報告する
一時的な不調 ネットワーク・キャッシュ・タイムアウト・flaky 再実行する。2回続けて同じなら一時的ではない
gh pr checks <PR>                         # 落ちているジョブの一覧
gh run view --job <job-id> --log-failed   # 中身

落ちているジョブを全部見る。 失敗は層になっていることがあり、1つ直しても次が出ます。成功表示だけを根拠にしないのも同じ理由( verify_before_asserting.md )。

push したら、CI の完了まで見る。 待ち方は /wait-for-ci へ委譲する。古い run を掴んで即座に抜ける事故を避ける判定を持っています。 走らせただけで放置しない( keep_records_current.md )。

5. 追随修正は、その renovate ブランチへ入れる

原則、その PR のブランチへコミットする。 依存更新に伴って要る修正は、その更新と一緒にレビューされたほうが意図が伝わります。 分けるとレビュアーは2本を突き合わせて読むことになり、マージ順の制約も生まれます。

renovate が PR を作り直すと、こちらのコミットは消えます。 それでも分けないのは、分けたほうが失うものが大きいからです。 消えたときは当て直せるよう、差分を控えておく。

git diff --output=<パス>   # 当て直せるように控える

別 PR に切り出すのは、その修正が依存更新と無関係に価値を持つときだけ。 判断に迷ったら、renovate ブランチへ入れる側に倒す。

判定は推測でなく実測する。 「今のバージョンでも通る」かどうかは、修正を当てたあと古いバージョンで検査し直せば分かります。

切り出しを考えたときは、必ず実測してから決める。 formatter の出力規則が変わった場合が典型で、 新しいバージョンの整形結果は古いバージョンでは「未整形」と判定されます。この形の修正を別 PR にすると base の CI が落ちます。

追随は、上げた先のバージョンで書く。 移行後の API が既に入っているので、古い書き方のまま通すと非推奨を抱えたままになります( write_for_installed_versions.md )。

ビルド・CI・lint の設定に触るなら、その前に AskUserQuestion で尋ねる( ask_before_editing_claude_assets.md )。依存を上げる依頼は設定への白紙委任ではありません。

コミットとプッシュは /commit-push へ委譲する。明示指示があるときだけ( decide_or_ask.md )。

6. 衝突とロックファイルは、待たずに自分で片付ける

renovate PR の衝突はほぼロックファイルで、手で解くと壊れた依存木ができます。

自分のコミットが乗っていなければ、renovate に作り直させる。 PR 本文の If you want to rebase/retry this PR, check this box のチェックボックスを入れると、renovate が base の最新から作り直す。

schedule は rebase にも効きます。 チェックボックスを入れても、renovate が動く時間帯まで何も起きません。 週 1 回だけ動く設定なら、次の実行まで数日待つことになります。

チェックを入れたら、実際に走ったかを確かめる。 PR の updatedAt は本文を編集しただけでも動くので、 最新コミットの日時で判定する。

gh pr view <PR> --json commits --jq '.commits[-1] | "\(.oid[0:8]) \(.committedDate)"'

既定は renovate を待たずに自分でやる。 renovate に任せるより速く、結果を自分で確かめられます。 「次回 renovate が作り直す」で片付けない。それは何日も先で、その間 PR は落ちたまま置かれます。

やること 自分でやる方法
base の取り込み git merge origin/<base> してロックファイルを再生成
ロックファイルの作り直し 消して作り直す( rm <lock> してから解決のみ実行する)
バージョン指定の追随 マニフェストを直してから再生成

ロックファイルの全体更新(lock file maintenance)も自分でできます。 消して作り直せば、その時点の最新解決になります。

自分のコミットが乗っているなら押さない。 消えます。その場合は base を git merge で取り込み、ロックファイルは再生成で解く。

衝突マーカーが出なくても壊れます。 ロックファイルは行が独立して見えるので、git は衝突と判定せず両側を繋いでしまう。 結果として「マージは成功したのに、参照先のエントリが無い」状態になります。

git merge origin/<base>            # 衝突しなくても油断しない
pnpm install --frozen-lockfile     # ここで壊れが分かる
pnpm install --no-frozen-lockfile  # 壊れていたら再生成する
pnpm install --frozen-lockfile     # 再生成後に通ることまで確かめる

再生成したら、もう一度 frozen で検算する。 生成できたことと、CI と同じ条件で通ることは別です。

ロックファイル以外も同じです。 衝突0件でも参照切れや型の不一致は素通りするので、lint → 型検査 → テストまで通す( verify_merge_with_checks.md )。

順序を間違えると、再生成分がコミットから落ちます。 マージ解決で git add したあとに再生成すると、再生成後の内容はステージされていません。 git commit はインデックスを記録するので、古いまま入って CI だけが落ちます。 再生成 → git add → git commit の順にする。

検証は作業ツリーではなくコミット内容に対して行う。 作業ツリーが汚れたまま --frozen-lockfile を通しても、 push されるものを検証したことにはなりません。git status が空であることを確かめてから測る。

7. 検討したことを PR にコメントする

この作業は結論より過程に価値があります。 次に同じ依存が上がってきたとき、同じ調査をやり直さずに済む。

残すもの。

  • 何が壊れて、なぜ壊れたか
  • 見送るなら、その理由と、いつなら上げられるか
  • 別 PR へ切り出したなら、その参照( owner/repo#123 の形。github_writing.md )
  • 調べたが問題なかったことも1行。書かないと「見ていない」と区別が付かない
  • 速度を測ったなら、その結果と計測条件。速くならなかった工程も併せて書く

アノテーションは [fyi] を使う。書式と使い分けは github_writing.md が定めます。

書き方は github_writing.md と /format-post に従い、末尾へ生成者表示を置く( github_note_generated_by_claude.md )。renovate は bot なので、投稿に追加の許可は要りません( responding_to_reviews.md の対象外)。

同じ内容を重ねて投稿しない。 既に自分のコメントがあるなら、gh api でそのコメントを編集して更新する。

ただし判断が覆ったときは編集しない。 前のコメントを Outdated で畳み、新しい判断は別コメントで投稿する( keep_records_current.md )。 書き換えると訂正したこと自体が消え、「前回の判断を訂正します」と書いても読み手には何のことか分かりません。

新しい側から前のコメントへリンクを貼る。 畳まれているので、リンクが無いと読み手が探すことになります。

push するたびに、投稿済みのコメントを読み返す。 状況を書いたコメントは、自分が手を動かした時点で古くなります( keep_records_current.md )。

書いたこと push 後に反転しやすい
「まだ走っていません」 自分で走らせた
「renovate を待つしかありません」 手元で片付けた
「CI が落ちています」 直して緑になった

書いた側は実態を知っているので気づけません。 読む側は説明を信じて動くので、ズレを残すと誤解が固定化します。

8. マージできる状態かを判定して終わる

マージも approve も実行しない。 ここが終点です。

状態 報告すること
マージできる CI が緑・衝突なし・起動して動くことを確かめた。残っている外部条件(approve が要るなら、それが要ること)
承認待ちだけ残っている コード側は片付いたと明示する。承認は自分では解けない
別 PR 待ち その PR の URL と、マージする順序
見送り推奨 理由と、再検討の目安(対応したバージョンが出たら 等)

出力の目安

  • そのまま緑だった: 上げた依存・確認した範囲・残る条件を3〜5行
  • 追随が要った: 4の分類ごとに何をしたか、押したコミットのハッシュ、切り出した別 PR、投稿したコメントの URL
  • 見送り推奨: 何が対応していないかを1〜2行で。判断は AskUserQuestion で尋ねる
  • いずれも PR の URL を添える( report_formatting.md )

やってはいけないこと

  • マージ・approve・PR のクローズを実行すること。いずれも外向きで取り消せない
  • 上げてよいかを判断する前に、追随を書き始めること
  • 検索結果の要約だけで「対応していない」と結論すること。原文と npm view の実測まで当たる
  • 実際に動かさずに見送りを決めること。動かさずに出した結論はたいてい外れる
  • 速度改善が売りの更新で、実測せずにリリースノートの数字を引くこと。手元では同じ効果が出ないことがある
  • build / lint / test が通ったことを「動く」と報告すること。どれも動かさずに確かめる検査で、起動時の失敗は出ない
  • CI ログだけで原因を決めること。複数タスクの出力が混ざるので、どのタスクのエラーか取り違える
  • 落ちたタスク名だけを見て、その設定を疑うこと。依存元のタスクが原因のことがある
  • ロックファイルを手で編集する / 手で衝突を解くこと。再生成が正
  • 自分のコミットが乗った renovate ブランチで、rebase チェックボックスを押すこと。コミットが消える
  • 承認待ちの失敗を、コード起因として直そうとすること
  • 原因のログを読まずに再実行を繰り返すこと
  • 「次回 renovate が作り直す」で止めること。数日先まで PR は落ちたまま置かれる。自分で作り直す
  • renovate 設定・lint 設定・CI を「ついでに」変えること。尋ねてから
  • 追随修正を、理由なく別 PR へ切り出すこと。依存更新と一緒に読めなくなる
  • 同じ検討コメントを重ねて投稿すること

関連

  • /resolve-conflicts: base の取り込みとコンフリクト解消。ロックファイルは再生成で解く点だけ本スキルが上書きする
  • /wait-for-ci: CI の完了待ち。古い run を掴む事故を避ける判定は向こうが持つ
  • /commit-push: 追随修正のコミットとプッシュ
  • /ship-pr: 切り出した別 PR を出すとき( use_ship_pr_for_pr_creation.md )
  • /propose-tech-updates: こちらは PR が出た後、あちらはPR が無い段階で何をすべきか決める。renovate が拾わないもの(CI の改善・記法の統一・検査の穴)はあちらの担当