resolve-renovate-pr
renovate が作った依存アップデート PR を、マージできる状態まで持っていく。そもそも上げてよいかを先に判断し、CI の失敗をコード起因・承認待ち・一時的な不調に切り分けて、追随が要るものを直す。検討したことは PR にコメントで残す。マージと approve はしない。ユーザーが「renovate の PR を解決して」「依存アップデートを片付けて」「/resolve-renovate-
SKILL.mdhome/.claude/skills/resolve-renovate-pr/SKILL.md
GitHubrenovate 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 の改善・記法の統一・検査の穴)はあちらの担当