毎月の依存パッケージの更新で、変更履歴を自社のコードでの使い方と照らし、破壊的変更・非推奨に当たるかを判定して、更新の可否と直す箇所の一覧を作る

処理の起点を決める

Dependabot がプルリクエストを作ったときの pull_request を起点にします。 ワークフローの条件で、作成者が Dependabot のときだけ動かします。自動テストと同じタイミングで並んで動き、テストの結果が出た後に可否の区分を決めます。

pull_request_target は使いません。 公式の説明では、Dependabot の制限を避ける方法として pull_request_target を使う二段階の手順も挙げられていますが、秘密情報のある環境でプルリクエストの中身を扱う形になるので、この構成では避けます。 判定に要るのは変更履歴と自社のコードの読み取りだけで、書き込みはコメントとラベルに限られるため、pull_request で足ります。

Dependabot が既存のプルリクエストを新しい版で作り直したときも、同じ起点で動きます。前回の判定のコメントは消さずに「古い判定」と印を付け、新しい判定を足します。

入力データを集める

質を決めるのは、4行目の使い方の一覧です。 変更履歴の判定は、照らす相手が正確でなければ意味がありません。一覧はプログラムで機械的に作り、AIに探させません。

5行目の非推奨の警告は、テストのログから拾います。 テストは通っていても、更新後に新しい警告が出ていれば、それは変更履歴の非推奨と対応しているはずです。判定のときに、警告の文も一緒に渡します。

データの取得方法を決める

CHANGELOG を取るときは、application/vnd.github.raw+json を指定して本文をそのまま受け取ります。 大きな CHANGELOG を持つパッケージは珍しくなく、1MBを超えるとこの形式でしか取れません。

使い方の一覧は、言語ごとに次のように作ります。

構文木で読むのは、文字列の検索だと同じ名前の別物を拾うからです。 parse という名前は、どのパッケージにもあります。読み込んだ名前から呼び出しをたどれば、そのパッケージの parse だけを拾えます。 構文木で読めなかったファイルと、文字列の検索で拾った行は、source: "text_search" と印を付けて区別します。

AIへ渡す前に整形する

1. 範囲の切り出し … CHANGELOG の見出しから版の番号を読み、更新前より新しく更新後以下の版の節だけを残します
2. 版の並びの確認 … 見出しの版が飛んでいないか、リリースの一覧と照らします。範囲内の版の節が見つからなければ、そのことを記録します
3. 変更の分割 … 節の中の箇条を1つずつに分け、版番号を付けます
4. 使い方の一覧の圧縮 … 同じ呼び出しが多数あるときは、ファイルごとの代表の行と件数にまとめます
5. 秘密情報の除去 … 前後数行に鍵やパスワードらしい文字列があれば伏せます
6. 0.y.z の印 … 更新前か更新後の版が 0 から始まるときは、印を付けます

1番目と2番目を、AIに任せずにプログラムで行うのが要点です。 範囲の読み違い（第3章の（a））は、人でもAIでも起きます。版の番号の比較は機械で確実にでき、どの節を渡したかが記録に残ります。

6番目は、SemVer の取り決めによるものです。 メジャーの版は互換性の無い変更で上げることになっていますが、0.y.z は初期の開発のための版で、いつ何が変わってもよいとされています。 0 から始まる版はマイナーの更新でも破壊的変更がありうるので、更新の種類にかかわらずメジャーと同じ扱いにします。

AIに処理させる

させるのは、範囲内の変更1つずつについて、自社の使い方に当たるかを判定し、根拠を組で示すことです。

3行目が、この構成でいちばん大事な線引きです。 no_usage_found は「一覧に見つからなかった」という事実で、「影響なし」とは書かせません。 一覧は静的な解析なので、文字列から組み立てた読み込みや、設定ファイルで名前を指定する使い方は漏れます。

指示内容を固定する

あなたは社内の開発チームで、依存パッケージの更新を取り込めるかを
判断する担当者を手伝う立場です。
渡された変更履歴の変更1つずつについて、自社のコードの使い方に
当たるかを判定してください。更新を取り込むかどうかは書かないでください。

【判定の選び方】
- affects ........ 変更の対象（関数・クラス・オプション・既定の動作）を、
                   使い方の一覧の行で使っている
- no_usage_found . 変更の対象が、使い方の一覧に見つからない
- unknown ........ 判定できない。変更の文があいまい、動的な読み込み、
                   設定ファイルでの指定などで一覧から判断できない
- not_breaking ... 機能の追加や不具合の修正で、既存の使い方を変えない
迷ったときは unknown を選んでください。

【厳守事項】
- usage_refs には、使い方の一覧に載っている file と line だけを書いてください。
  一覧に無い箇所を挙げないでください。
- no_usage_found を「影響なし」と言い換えないでください。
- change_quote には、変更履歴の文を一字一句そのまま写してください。
- 既定の動作の変更（default を変えた、挙動を変えた）は、その関数を
  使っていれば、引数を指定していても affects にしてください。
  指定の内容で影響が無いと言えるときだけ、理由を書いたうえで no_usage_found にしてください。
- テストのログに出た非推奨の警告と対応する変更があれば、warning_match に警告の文を写してください。
- fix_hint には、直し方の方針を1〜2文で書いてください。コードは書かないでください。
- 渡された範囲の外の版について書かないでください。

【パッケージ】{name} {previous_version} → {new_version}（{update_type}）
【範囲内の変更（版番号付き）】{changes}
【自社のコードの使い方の一覧（file、line、名前、前後の行、source）】{usages}
【テストのログの非推奨の警告】{warnings}

「既定の動作の変更は、使っていれば affects」を明記しないと、引数を渡している箇所を外します。 既定の値が変わっても、明示的に値を渡していれば影響はありません。しかし、渡しているのが別の引数なら影響を受けます。 その見分けを人に回すために、まず affects に寄せます。

change_quote を一字一句で写させるのは、後で照らすためです。 プログラムで変更履歴の原文と照らし、一致しない行は判定から外します。

出力形式を固定する

Claude API の構造化出力で、次の形のJSONを受け取ります。

{
  "package": "",
  "previous_version": "",
  "new_version": "",
  "findings": [
    {
      "version": "",
      "change_quote": "",
      "kind": "breaking | deprecation | default_change | other",
      "verdict": "affects | no_usage_found | unknown | not_breaking",
      "usage_refs": [ { "file": "", "line": 0 } ],
      "warning_match": "",
      "fix_hint": "",
      "reason": ""
    }
  ]
}

1つ目の理由は、usage_refs をプログラムで照らせることです。 書かれた file と line が使い方の一覧にあるかを確かめ、無いものは判定ごと unknown に落とします。

ワークフローは、判定とテストの結果から、次の規則で可否の区分を決めます。

deps:candidate でも、自動では取り込みません。 担当者がコメントを流し見て取り込みます。

システムへ連携する

dependabot.yml とワークフローの骨組みは、次のようになります。

# .github/dependabot.yml（抜粋）
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "monthly"
    groups:
      minor-and-patch:
        update-types: ["minor", "patch"]

# .github/workflows/deps-impact.yml（抜粋）
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  impact:
    if: github.event.pull_request.user.login == 'dependabot[bot]'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: meta
        uses: dependabot/fetch-metadata@v3
      - run: python tools/deps_impact.py
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}  # Dependabot のシークレット
          UPDATED: ${{ steps.meta.outputs.updated-dependencies-json }}

deps_impact.py が範囲の切り出し、使い方の一覧、判定の呼び出し、照合、区分の決定までを行い、最後にコメントとラベルを付けます。 テストの結果を待つ場合は、テストのジョブの後に動くよう needs でつなぎます。

コメントには、affects と unknown の行を先頭に置き、変更の文・使っている行へのリンク・直し方の方針を表で並べます。no_usage_found と not_breaking は折りたたんで後ろに置きます。

人が確認する

1. affects の行を開く … 使っている行と変更の文を見比べ、本当に直す必要があるかを決めます
2. unknown の理由を読む … 動的な読み込みや設定での指定なら、該当の箇所を自分で探します
3. 範囲の切り出しができなかったパッケージを読む … 変更履歴が無い、版の節が見つからないものは、人が読みます
4. 取り込むか、直してから取り込むか、保留にするかを決める … 保留にするときは、理由をコメントに残します
5. 判定を覆したら記録する … no_usage_found だったのに影響があった場合は、使い方の一覧の作り方を見直す材料にします

5番目を省かないでください。 判定の漏れの多くは、AIではなく使い方の一覧の漏れから起きます。どんな使い方が一覧から漏れたかを集めると、集め方を直せます。

目標は、120件をならして1件6分です。 deps:candidate は数十秒で流し見て、affects と unknown に時間を使います。

例外に対処する

記録を残す

• プルリクエストの番号、パッケージ、更新前と更新後の版、更新の種類
• 切り出した変更の範囲と、取得した変更履歴の場所
• 使い方の一覧（集めた方法の印を含む）
• Claude API の出力と、そのとき使った指示の版
• 照合で外した判定と、その理由
• 可否の区分と、担当者の最終の決定、覆した判定

最後の行が、仕組みを育てる材料です。 覆した判定が多いパッケージは、使い方が特殊か、変更履歴の書き方が独特です。 パッケージごとの注意書きを足していきます。