upgrade-advisor

アップグレードアドバイザー

ドキュメントの場所

このドキュメントは ~/stuff/gitrepos/gh/vtmocanu/skills/upgrade-advisor/SKILL.md（公開リポジトリ：github.com/vtmocanu/skills）にあります。

注：これが信頼できる唯一の情報源です。~/.claude/skills/upgrade-advisor/SKILL.md にインストールされるコピーは、npx skills パッケージマネージャーによってこのファイルから生成されます。編集する場合はこちらを変更してから、npx skills update を実行して再取得してください。インストールされたコピーは編集しないでください。

アップグレードを実施する前に評価します。何が変わったのか、そのうち実際にこのプロジェクトへ影響するものは何か、採用する価値があるものは何かを確認します。出力は、盲目的なバージョン更新ではなく、判断とチェックリストです。ユーザーから変更の適用を依頼されていない限り、デフォルトでは調査のみにします。

2つのモードがあります。まず依頼内容を確認してください。「Xをアップグレードすべきですか？」は、以下の評価モードです。一方、「Xをすでにアップグレードしました」は検証の依頼です。判断は済んでおり、問題は何が壊れたかです。このモードでの成果物はステップ7（実行環境の監査）であり、ステップ3～4は確認結果の説明にのみ使います。すでに実施されたアップグレードに対して、変更履歴だけに基づく結論を返してはいけません。稼働中のシステムをすぐ確認できるのですから、実際に確認してください。

ワークフロー

以下を順番に実行します。ステップ1～2と、ステップ3の変更履歴の取得は互いに独立しているため、これらのツール呼び出しは並行して実行してください。

1. 現在のバージョンを特定する — 決めつけない

バージョンが実際にどこで固定されているかを確認します。明らかな1か所に記載されていることはほとんどなく、リリース済みのバージョンとこのプロジェクトで実行中のバージョンは異なる場合があります。プロジェクト内で以下を確認してください。

• 言語／ツールのマネージャー：devbox.json／devbox.lock、.tool-versions（asdf/mise）、.nvmrc、runtime.txt、flake.nix。
• パッケージマニフェストとロックファイル：package.json と package-lock.json／yarn.lock／pnpm-lock.yaml、go.mod／go.sum、pyproject.toml／requirements.txt／uv.lock、Cargo.toml／Cargo.lock、Gemfile.lock、pom.xml、build.gradle。
• コンテナ／CI：Dockerfile の FROM、.github／.forgejo／.gitlab-ci のワークフローで固定されたバージョン、Helm の Chart.yaml／values.yaml、アクションの uses: に指定された SHA／タグ。
• 実行中のサービスやアプライアンスのバージョンがリポジトリ内で固定されていない場合 — バージョンは実行環境にあるため、実行環境に問い合わせます（ha core info、/api/config、kubectl version、SELECT version()）。再起動中の読み取りには注意してください。新しいプロセスが起動するまでは古いバージョンが返されるため、値が古く見える場合は2つの情報源で確認してください。

正確な現在のバージョンと、それを固定しているすべてのファイルを報告してください。同じ依存関係が複数の場所（Dockerfile の FROM、マニフェスト、CI の uses: など）で固定されていることが多く、知らないうちに食い違っている可能性があるため、すべて列挙し、差異があれば明示します。モノレポでは、連動して更新する必要がある場合に備えて、パッケージごとに異なる固定バージョンを記載します。リポジトリにリモートがある場合は、ローカルのチェックアウトがリモートの固定バージョンと一致していることを確認します（ローカルブランチが遅れている可能性があります）。ロックファイルはマニフェストのバージョン範囲より優先されます。

2. 最新リリースと、実際にインストール可能な最新バージョンを確認する

「最新リリース」と「このプロジェクトが実際に取得できる最新バージョン」は異なります。両方を確認してください。

• 最新リリース：GitHub リリース API（/repos/OWNER/REPO/releases/latest）またはエコシステムのレジストリ（npm registry.npmjs.org/PKG、PyPI pypi.org/pypi/PKG/json、crates.io、Docker タグ、Maven Central）を確認します。
• このプロジェクトのパッケージマネージャーでインストール可能な最新バージョン：nixpkgs/devbox のピン留めは上流に数日から数週間遅れる場合があります。企業レジストリは一部のパッケージのみをミラーする場合があり、Docker ベースイメージは特定のタグしか公開しない場合があります。推奨する前に、対象バージョンを解決できることを確認してください（例：devbox の場合は search.devbox.sh/v2/resolve?name=X&version=Y、nixpkgs の場合は nixhub、npm の場合はレジストリの versions マップ）。対象バージョンがまだインストールできない場合は、その旨を明記してください。更新が止まっている原因はパッケージ担当者側であり、コード側ではありません。それが回答のすべてです。

対象バージョンの選定を左右する要因は 2 つあります。

• セキュリティ／CVE 主導：まずアドバイザリ（GitHub Security Advisories／osv.dev、またはエコシステムのスキャナー：npm audit／pip-audit／govulncheck／cargo audit）で修正バージョンを特定します。対象は CVE を解消する最小のバージョンとし、メジャーアップデートよりパッチやバックポートを優先します。緊急性が高まるため、許容できる影響範囲は広がります。
• サポート終了主導：現在のピン留めバージョンが EOL／サポート対象外かどうか（endoflife.date）を確認します。必要な機能がない場合でも、メンテナンスされていないこと自体が移行する理由になります。また、対象バージョンの系列が LTS／引き続きメンテナンス中か、短期間でサポートが終了するリリースかを確認し、対象バージョンのサポート期間を明記します。

3. 差分全体にわたって変更履歴を読む

最新リリースだけを読んではいけません。現在のバージョンから対象バージョンまでのすべての中間バージョンを確認してください。破壊的変更はどのバージョンにも含まれる可能性があります。公式の変更履歴／リリースノートと、プロジェクト独自の移行／アップグレードガイドがあれば、それも取得します。信頼できる情報源を優先してください。プロジェクトのリリースノートや移行ドキュメント、利用可能であればライブラリ API を参照する docs MCP（context7）、ソースリポジトリの CHANGELOG／BREAKING ファイルなどです。破壊的変更と非推奨項目は、原文のまま引用してください。言い換えると、grep で探す必要のある正確なシンボル名／フラグ／設定キーが失われます。

4. 各変更を実際の利用箇所と照合する — ここが最も重要です

使用していない破壊的変更は該当しません。破壊的変更と非推奨項目ごとに、影響を受けるシンボル、設定キー、CLI フラグ、API、コンポーネントをコードベースから grep してください。それぞれを次のように分類します。

分類	意味	対応
破壊的変更 — 影響あり	削除／変更された要素を使用している	アップグレード前に必ず修正し、該当箇所を示します
破壊的変更 — 動作上の変更	API は同じだが、デフォルト値／動作が変わる（例：デフォルトのタイムアウトが 30s→5s）	シンボルが変わらないため grep では検出できません。変更履歴にあるデフォルト値／動作変更の記述を読み、呼び出し箇所を手動で確認します
破壊的変更 — 該当なし	どこにも存在しない（grep で該当なし）	確認済みで影響なしと記録します。ただし grep で該当しないことは信頼度の高い判断であって証明ではありません。動的に参照されるもの、再エクスポート経由のもの、文字列キーで指定される設定、推移的依存関係については「おそらく該当なし、要確認」と明記します
非推奨	警告は出ますが、引き続き動作し、削除まで猶予がある	可能な機会に移行し、削除されるバージョンを記録します
機能／改善	新機能、またはパフォーマンス／セキュリティの修正	回避策を削除できる、または追加の作業なしで恩恵を得られる場合は明記します
同梱のアラートルール／ヘルスチェック — 新規または修正済み	アップグレードによってデフォルトで有効な PrometheusRules／/health チェック／合成モニターが追加される場合、または動作しなくなっていたルール（メトリクス名変更、セレクター誤り）が修正される場合	リリース前に、実際のシグナルに対してそれぞれドライランを実行してください。これまで存在しなかった、または動作していなかったルールは、有効化された時点で、既存の潜在的な問題に対して即座に発報することがあります。「監視の純増だから問題ない」と見過ごしてはいけません
リファクタリングの機会	新しいバージョンを利用すれば、コードを簡素化できる	提案してください。自動適用はしないでください

該当なしの項目も明示することが重要です。「確認した結果、影響するものはなかった」と「見出しに目を通しただけ」の違いになります。

5. 下流／推移的な互換性を確認する

ツールのアップグレードは単独では行われません。対象バージョンが、それに依存するすべての要素と互換性があるか確認してください。テーマ／プラグインの min_version とピア依存関係のバージョン範囲、フレームワークのサポートマトリックス、ツールチェーン自体の最低バージョン、同時に更新が必要な関連するバージョン固定などが対象です。必須プラグインが動作しなくなる対象バージョンは、ツール自体に問題がなくても適用できません。

6. 適用を推奨する前に、影響範囲を考慮する

元に戻す難しさに応じて慎重さを調整してください。復旧が難しい対象（OTA のみで更新できるファームウェア、本番 DB エンジン、多数の下流ビルドに組み込まれたベースイメージ）は、先にビルド／コンパイル／テストを行い、その後に適用します。簡単に元に戻せる対象（開発用 CLI、CI の管理下にあるロックファイルの更新）は、直接適用できます。どちらのケースに該当するか明示してください。

7. ランタイムを監査する — 変更履歴だけでは、すでに起きている問題は分からない

ステップ 3～4 では、差分から grep 対象のリストを作成するため、差分が見つけられる範囲の上限となります。アップグレード時に経由したバージョンで削除されたシンボルは、この方法では見つかりませんが、コード内ではまだ使われている可能性があります。削除された API は、該当するコードパスが実際に実行されたときに初めて失敗するためです。そのため、まれにしか実行されないパス（夜明けのみ実行されるジョブ、エラー分岐、季節ごとのタスク）は壊れたまま何か月も気づかれないことがあります。差分全体で grep に問題が見つからなくても、動作するとは限りません。

そのため、リリースノートだけでなく、システム自体のエラー情報も確認してください。

• 構造化診断はログの末尾より優れており、通常は 1 回の呼び出しで確認できます。例：Home Assistant の system_log/list、django-admin check、govulncheck ./...、npm ls、ビルド時の非推奨警告、/health エンドポイントや診断エンドポイント。ログの末尾から分かるのは一部の期間ですが、エラー情報からは件数とともに、個別の問題をすべて把握できます。
• ユニット単位の実行ステータスが確認できる場合は、それも確認してください — アプリ自体が正常で、スモークテストがすべて成功していても、コンポーネントが失敗していることがあります（HA の自動化トレースでは script_execution: error が確認できます）。

可能であれば、アップグレード前にベースラインを取得し、アップグレード後にもう一度確認してください。ベースラインがなければ、アップグレードで発生した問題ともともと起きていた問題を区別できず、どちらの方向にも誤った原因の特定をしてしまいます。ログしかない場合は、タイムスタンプで同じことができます。アップグレード／再起動の時点と比較してください。

再起動を含むログの期間では、継続的な発生率を誤って算出してしまいます。 アップグレードによってプロセスが再起動し、起動時に状態が再同期され、その大量のログが指定した期間に含まれます。そのため、アップグレード直後に logs --since=15m を実行し、15 分で割ると、実際には存在しない一定の発生率が算出されます。抑制策（ログパイプラインのドロップルール、ログレベルの引き上げ、アラートの一時停止）を提案する前に、平均値ではなく発生の推移を把握してください。1 分ごとに集計し、変更前のベースラインと比較します。合計値では、急増してから静まるケースと本当に継続しているケースを区別できませんが、必要な対応は正反対です。急増は通常、再起動ごとに一度発生するだけで、抑制する価値はありません。一方、恒久的な除外設定をすると、後で実際のエラーをひそかに見逃すおそれがあります。

測定例：cert-manager の 1.20.3 → 1.21.0 の監査では、既知の無害な警告について、kubectl logs --since=15m の結果から「約 5 行／秒で継続」と報告されました。しかし、該当期間はたまたま Pod の起動と重なっていました。1 分ごとの推移が示した実態は、起動した分に 4,746 行、次の分に 7 行、その後はほぼゼロでした。アップグレード前のベースラインは 10 分あたり 3,475 バイト、アップグレード後の定常状態は 10 分あたり 4,515 バイトでした。実際のコストは再起動あたり約 3.3 MB であり、一定の発生率ではありません。「継続している」という誤った見立てにより、存在しない問題に対して恒久的なドロップルールが設定されかけていました。 実測例：HA 2026.6.4 → 2026.7.2 の監査では、差分全体を検索しても問題は見つからず、修復リストも空で、すべてのダッシュボードが描画されました。判定は「クリーンなアップグレード」でしたが、それは事実であり、同時に役に立ちませんでした。system_log/list を1回実行すると、extra keys not allowed @ data['kelvin'] が見つかりました。light.turn_on の kelvin パラメーターは 2026.3 で削除されており、5つの呼び出し箇所が約3か月間機能していませんでした。2026.7 の差分からこれを見つけることは、そもそも不可能でした。同じ呼び出しで、存在したことのないエンティティに依存して壊れていた自動化も、さらに2つ見つかりました。

実測例 — 監視レイヤー自体がアップグレードの対象です。 certmon（x509-certificate-exporter）の 4.1.0 → 4.2.0 への更新では、デフォルトで有効になる新しい PrometheusRules が追加され、長い間機能していなかったアラートも修復されました（X509ExporterReadErrors は、4.0.0 で名前が変更されて使われなくなったメトリクスを参照していました）。評価では新しいアラートを確認し、「プラスの効果があり、アラート疲れも最小限」と判断して更新を実施しました。その数分後、18件が発報しました（SourceDown／SourceErrors／SourceErrorsSustained × 6ポッド）。新たな障害が発生したのではなく、ホストパスのエクスポーターが 4.1.0 でも継続して出力していた broken_symlink／out_of_scope_symlink エラーが原因でした。以前のルールが機能していなかったため、これまで一度もページャー通知が送られていなかっただけです。証明書に問題はなく（x509_cert_not_after は引き続き取得できていました）、発報したものはすべて誤ったクリティカルアラートでした。差分でアラートルールが追加または修復される場合は、評価の一環として各ルールの PromQL を現在のメトリクスに対して実行してください（変更前は生の式、変更後は count(ALERTS{...})）。「動作するアラートを得た」ことと「以前からあった無害な状態で自分たちにページャー通知を送った」ことは、同じ出来事です。この2つを区別できるのは、実環境でのチェックだけです。

出力

最初に判定を示し、その後に根拠を示します。

• 判定 — 次のいずれかを使用します：already current / safe bump / stay put (installable & clean, not worth the churn) / blocked (reason) / needs work (N items) / clean, but N pre-existing faults found（ステップ7で、このアップグレードが原因ではない不具合が見つかった場合。「クリーン」が「正常に動作している」という意味に誤解されないよう、そのことを明確に伝えてください）。
• バージョン — 現在のバージョン（＋ソースファイル）→ 最新リリース → インストール可能な最新バージョン。
• 利用状況に対する破壊的変更 — ステップ4の表を記載します。影響があるものは引用をそのまま示し、該当なしの一覧も記載してください。
• 非推奨化 — 削除までの猶予期間を記載します。
• メリット／リファクタリング — 採用する価値のある機能と、不要になる回避策を記載します。
• 下流互換性 — プラグイン／テーマ／ピアの制約を確認します。
• 計画 — 具体的なチェックリストを記載します（コンパイル優先か直接適用か、失敗時のフォールバック、同時に更新する関連バージョン、再生成するドキュメント／ロックファイル）。追跡用の issue 作成や変更の適用を提案してください。ただし、求められていない変更は適用しないでください。

落とし穴（見落としやすい点 — それ以外は上記の手順でカバーしています）

• grep で問題が見つからなくても、確実とは限りません。 動的アクセス、再エクスポート、文字列キーの設定、ラッパーレイヤー、推移的な依存関係によって、シンボルの grep では見つからない使用箇所が隠れていることがあります。明確に問題なしとせず、「おそらく該当なし、要確認」としてください。
• 動作の変更では、シンボルは同じままです。 デフォルト値やセマンティクスが変更されていれば、grep で呼び出し箇所に変更が見つからなくても影響を受けます。そのため、シンボルだけを grep しても見過ごしてしまいます。変更履歴にあるデフォルト値や動作変更の注記を読み、呼び出し箇所を手動で確認してください。
• アップグレードしないのも妥当な判断です。 インストール可能で grep でも問題が見つからない一方、必要な修正も使いたい機能もなく、影響範囲が小さくない場合は、stay put を推奨し、その理由を説明してください。無理にアップグレードの理由を作らないでください。
• 簡素な変更履歴は、問題がないことを意味しません。 リリースノートが乏しい場合や、プロジェクトがリリースノートなしでタグを付けている場合は、比較ビュー（github.com/OWNER/REPO/compare/vA...vB）またはコミットログを確認してください。破壊的変更がコミットにしか記載されていないこともあります。
• 非推奨と削除は同じではありません。 非推奨は警告であり、移行までの猶予があります。削除されるバージョンを記録し、自分のスケジュールで移行してください。慌てて修正する必要はありません。
• 新しいアラートや修正されたアラートは、以前から存在する問題を検知します。 デフォルトで有効なアラートルールを含むアップグレードや、機能しなくなっていたルールを修正するアップグレードでは、以前から存在していたものの監視されていなかった潜在的な状態が、アラートとして通知されます。評価中に、同梱されたルールを実際のシグナルに照らして確認してください。監視機能が追加される「安全なアップグレード」が、自動的に通知の少ないアップグレードとは限りません。