Claude Codeでhelm diffのアップグレード前差分をレビューする手順

helm upgradeを流す前に、helm diff upgradeの出力をClaude Codeに読ませて「何がどこへ波及するか」を要約させると、差分が数百行になるリリースでも見落としが減ります。Claude Codeに任せるのは差分の読解と整理までです。実行して良いかどうかの最終判断は、読む人が持ちます。

この記事では、helm-diffプラグインでの差分の取り方、claude -pへの渡し方、レビュー観点を固定するCLAUDE.mdの書き方、GitHub Actionsでの自動化、そしてrollbackの要否を判断する材料の揃え方を順に扱います。チャートの作成手順はClaude CodeでHelmチャートを作成する手順にあり、ここでは「作った後、本番へ上げる前」の工程だけを対象にします。

helm diffの差分をClaude Codeに読ませると何が変わるか

helm-diffは、稼働中のリリースのマニフェストと、これから適用するチャートとvaluesから描画したマニフェストを比べるHelmプラグインです。helm upgradeが何を変えるかを事前に可視化するために使えます。

差分そのものは機械が正確に出してくれます。読みづらいのは、その先です。

• values.yamlの1行（たとえばimage.tag）が、チャートによってはDeploymentのイメージだけでなくServiceのセレクタやConfigMapのハッシュ注釈にまで波及する
• 3つの環境で差分が少しずつ違い、どれが意図した変更かが分からない
• チャートのバージョンを上げたら、変えていないはずのリソースにも差分が出る

Claude Codeに向くのは、この「波及の読み解き」です。差分を渡して、リソースの種類ごとに何が変わるかを整理させ、再起動を伴う変更とそうでない変更を分けさせます。

一方で、Claude Codeが答えられないことも先に押さえておきます。差分はマニフェストの比較にすぎず、アプリケーションが新しい設定で正常に動くかどうかは差分に現れません。後半の「差分が語らないこと」で詳しく扱います。

helm diffでアップグレード前の差分を取る

プラグインの導入と基本コマンド

helm-diffの導入は、Helmのプラグインコマンドで行います。導入にはHelm 3.18以上が必要です。

helm plugin install https://github.com/databus23/helm-diff
helm diff upgrade my-release ./charts/api -f values-prod.yaml -n prod

引数の形はhelm diff upgrade [RELEASE] [CHART]で、helm upgradeと同じ感覚で-fや--set、-nが使えます。これらのフラグはupgradeのフラグ一覧に載っています。

レビュー用に整える4つのオプション

人が読む場合は標準出力のままで足りますが、Claude Codeに渡すなら出力を絞るほうが精度も費用も有利です。フラグ一覧から、レビュー向きのものを選びます。

--outputにはdiff・simple・template・json・structured・dyffが指定できます。structuredの例では、各エントリにKind・名前・changeTypeと、変更ごとのpath・field・oldValue・newValueが入ります。たとえばDeploymentのreplicasが2から3に、imageがapi:v1からapi:v2に変わる、という形です。

--suppressを使うと、そのKindではchangesSuppressedが真になり、項目の詳細は省かれます。つまり、外したKindの中身は後段のレビューでは見えません。何を外したかは、レビュー結果に必ず添えます。

差分をファイルに保存する

Claude Codeに渡す前に、差分をファイルへ落としておくと、同じ入力を何度も再現できます。

helm diff upgrade my-release ./charts/api \
  -f values-prod.yaml -n prod \
  --no-color --suppress-secrets \
  > /tmp/helm-diff.txt

--no-colorは色付けのエスケープを除きます。--suppress-secrets（短縮形-q）は、Secretの値を出力に含めないためのフラグです。--show-secretsを付けない限りSecretの値は伏せられる仕様なので、既定のままでも伏せられますが、レビュー用の出力には明示しておくと意図が残ります。

claude -pで波及を要約させる

パイプで渡す最小の形

Claude Codeの非対話モードはclaude -pです。claude -pは標準入力を読めるので、他のコマンドと同じようにパイプでつなげます。

cat /tmp/helm-diff.txt | claude -p \
  'この helm diff upgrade の出力を読み、リソースごとに変更内容と
   Pod の再起動を伴うかどうかを表にまとめて。書かれていない事は推測しない' \
  > /tmp/helm-review.md

パイプで渡す標準入力には10MBの上限があり、超えるとClaude Codeは非0で終了します。大きな差分は、ファイルに書いてパスをプロンプトに書く形にします。そもそも数MBに迫る差分は、人にも読めません。--suppressでKindを絞るか、リリースを分けるサインです。

レビュー観点をCLAUDE.mdに固定する

毎回プロンプトに観点を書くと、人によって抜け漏れが出ます。リポジトリのルートにCLAUDE.mdを置くと、レビュー基準をリポジトリ単位で共有できます。GitHub ActionsのBest practicesでも、レビュー基準やプロジェクト固有のルールはCLAUDE.mdへ書く方法が案内されています。

次は、アップグレード前レビューに絞った観点の書き方の一例です。観点そのものは各チームの運用に合わせて入れ替えます。

## helm diff レビューの観点
 
- 差分に出たリソースを Kind ごとに分け、変更前後の値を併記する
- Deployment の spec.template 配下が変わると Pod が作り直される。
  該当箇所を「再起動あり」と明記する
- Service の selector と port が変わる場合は、通信断の可能性として別枠で挙げる
- 差分に現れない事（アプリ側の互換性、DB マイグレーション）は
  「この差分からは判断できない」と書く
- 最後に「適用前に人が確認すべき項目」を箇条書きで 3 件以内にまとめる

最後の2項目が肝です。差分から言えることと言えないことを分けて書かせると、レビュー結果が「問題なし」の一言に潰れません。

構造化出力で読ませる場合

--output structuredのJSONを渡すと、Claude Codeは項目ごとのoldValueとnewValueを表にしやすくなります。通常のdiff形式より、変更点が少ない場合の見通しが良くなります。逆に、リソースの追加や削除が多いリリースでは、diff形式のほうが全体の文脈を保てます。両方を取って、観点に応じて使い分けるのが実務的です。

波及を追う具体例

たとえば、次のような差分が出たとします。

 apps/v1, Deployment, prod, api (MODIFY)
-          image: api:v1
+          image: api:v2
-  replicas: 2
+  replicas: 3
 v1, Service, prod, api (MODIFY)
-    port: 8080
+    port: 9090

見るべき点は3つあります。

1. イメージの変更で、Podが作り直される
2. replicasの増減だけなら、既存のPodは作り直されない
3. Serviceのポートが変わると、他の呼び出し元の設定とずれる可能性がある

Claude Codeに「3つ目は差分の外にある設定、つまり呼び出し元との整合に関わる」と書かせるのが、観点を渡す意味です。差分に現れない呼び出し元の設定は、リポジトリの別の場所をgrepさせる指示を足すと追えます。たとえば「9090をポートとして参照しているマニフェストが他にないか探して」と続けて頼みます。

差分が語らないこと

差分を読んだ結果が「問題なし」でも、安全が保証されたわけではありません。読む側が知っておくべき限界を4つ挙げます。

特に--three-way-mergeは、モードで挙動が変わります。serverはAPIサーバーにdry-runのPATCHを送り、既定値の補完やmutating webhookの結果まで反映した最も忠実なプレビューを返しますが、対象リソースへのpatch権限が必要です。clientは手元で結合するためget権限だけで済みますが、READMEには、手で追加されたフィールドの差異を拾い損ねる場合があるなど、サーバーモードとのずれが4点挙げられています。既定のautoは、まずserverを試し、権限エラーのときだけclientに切り替えます。

レビューの結果を信用してよい範囲は、どのモードで差分を取ったかで変わります。レビュー結果には、使ったコマンドをそのまま添えておくと、後から追跡できます。

rollback要否の判断材料を揃える

アップグレードの前に、「失敗したら戻せるか」「戻したら何が変わるか」を見ておきたい場面があります。helm-diffには、そのためのサブコマンドが用意されています。

helm diff rollback my-release 2 -n prod --no-color > /tmp/helm-rollback-diff.txt

helm diff rollbackは、現在デプロイされているリリースと、戻したい先のリビジョンを比べます。helm rollbackが何を変えるかを予測して可視化するコマンドです。

この出力を、アップグレードの差分と並べてClaude Codeに渡します。頼む内容は判断そのものではなく、材料の整理です。

1. 戻したときに変わるリソースの一覧
2. アップグレードの差分と、逆向きの差分で、対応しない項目（片方にだけある項目）
3. データの移行や外部システムとの契約変更が絡みそうな箇所の候補

3つ目は推測になるため、「差分に現れない事は推測と明記する」という指示をCLAUDE.mdに入れておきます。マニフェストの差分には、DBスキーマの変更が含まれません。スキーマ変更を伴うリリースでは、Helmのrollbackでアプリケーションだけが戻り、スキーマが戻らない構図になり得ます。この種の判断は、差分では取れない情報に依存します。

整理結果を基に、人が決めます。判断の順番を整理すると、次のようになります。

GitHub Actionsでアップグレード前レビューをPRに載せる

毎回手でパイプするのは手間なので、PRごとに差分を取ってレビューを走らせる構成にもできます。prompt入力を指定すると自動化モードで動き、メンションを待たずに実行されます。結果は既定ではワークフローの実行ログに出ます。

次は、差分を取る手順とレビュー手順を1つのジョブに並べた構成の一例です。クラスタへ接続する認証の部分は、環境ごとに違うため省略しています。

name: Helm Upgrade Review
on:
  pull_request:
    paths:
      - "charts/**"
      - "values/**"
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      # クラスタ接続、helm と helm-diff の導入はここに置く
      - name: Render diff
        run: |
          helm diff upgrade my-release ./charts/api \
            -f values/prod.yaml -n prod \
            --no-color --suppress-secrets > helm-diff.txt
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            helm-diff.txt は helm diff upgrade の出力です。
            CLAUDE.md の観点に従ってレビューし、
            結果を PR にコメントしてください。
          claude_args: |
            --max-turns 8
            --allowedTools "Read,mcp__github_inline_comment__create_inline_comment"

プレーンテキストのプロンプトでは、必要なツールを許可するまでClaudeにシェルやGitHub APIへのアクセスがありません。許可はclaude_argsの--allowedToolsか、settings入力のpermissions.allowで与えます。上の--allowedToolsは、差分ファイルの読み取りと、公式のcode-reviewの例にあるインラインコメント用ツールを並べた例です。このツールをclaude_argsで名指ししないと、コメントを投稿するMCPサーバーが起動しません。

費用は、--max-turnsの指定とワークフローのタイムアウト、GitHubの同時実行制御で抑えられます。差分の大きさに比例して入力が増えるので、前述の--suppressで入力自体を絞るのが最初の手です。

認証情報はリポジトリにコミットせず、GitHub Secretsに置きます。クラスタ接続の認証情報も同じ扱いです。クラスタに接続する認証情報には、読み取り専用の権限だけを持たせる構成が、事故を小さくします。--three-way-mergeを使う場合のserverモードがpatch権限を要求する点は、先ほど述べたとおりです。

ワークフローの書き方そのものは、Claude Code GitHub Actionsのワークフロー YAMLと、claude_argsとパラメータの整理に詳しくあります。

レビューの精度を保つための運用

要約させるだけでは、見落としがあったときに気づけません。別の文脈のサブエージェントに、同じ差分を独立に読ませて結果を突き合わせる方法があります。敵対的レビューの設計は、この考え方を整理した記事です。差分レビューに当てはめるなら、1回目の要約に対して「見落としている波及先はないか」を別セッションに問わせます。

もう1つは、人が見る箇所を固定することです。Claude Codeの要約に頼る範囲を、再起動の有無やリソースの対応づけなど、機械的に読める部分に限ります。判断の部分は、先に挙げた「差分の外」の確認項目として人に残します。

まとめ

helm diff upgradeの出力は、Claude Codeに読ませるといちばん効く入力の1つです。差分を--suppressと--no-colorで整え、レビュー観点をCLAUDE.mdに固定し、claude -pかGitHub Actionsで読ませる。この流れで、波及先の整理までは機械に任せられます。

任せきれないのは、差分に現れない領域です。使ったvaluesの指定、クラスタの手作業の変更、Secretの中身、DBスキーマのような外部の状態は、差分の外にあります。rollbackはhelm diff rollbackの出力を並べて材料を揃えるところまでを機械に頼み、戻すか進めるかの決定は、運用の承認手順に残す形が、役割分担として無理がありません。