GitHub Actions で terraform plan の Conftest（OPA）違反理由を Claude Code に解説させてみた

---
name: conftest-explain
description: Conftest（OPA）のポリシーチェックで検出された違反を解説し、PR の該当行にインラインコメントと修正提案（suggestion)を投稿する。引数に conftest の JSON 出力ファイルのパスを取る。「/conftest-explain <path>」で使う。
---

# Conftest 違反の解説と修正提案

引数で渡された conftest の結果 JSON（例: `terraform-conftest-opa/conftest-result.json`）を読み、違反ごとに「なぜ落ちたか」と「どう直すか」を PR のインラインコメントで解説する。

## 役割分担（このスキルの前提）

- 違反の判定は OPA/Rego で完了している。判定をやり直さない・上書きしない
- 結果 JSON の `failures` に載っている違反だけを扱う。それ以外の指摘や粗探しは行わない
- 修正を適用するかどうかは人間が決める。suggestion は提案であって自動修正ではない

## 手順

1. 引数の JSON を Read し、`failures` の `msg` を列挙する
2. 各 `msg` に含まれるリソースアドレス（例: `aws_security_group.web`）から、Grep で該当の .tf ファイルと行番号を特定する
3. 違反に対応する Rego ルールを `policy/*.rego` から読み、ルールの意図（何を防ぎたいルールか）を把握する
4. `gh pr diff` で PR の差分を確認し、違反行が差分に含まれるかを見る
5. `gh pr view <PR番号> --comments` で既存コメントを確認する（重複回避。次節を参照）
6. 違反ごとに該当行にインラインコメントを投稿する
7. 最後に `gh pr comment` で全体サマリ（違反件数と各違反の1行要約）を1件投稿する

## 再実行時の重複回避

このワークフローは PR が更新されるたびに再実行される。前回の実行が投稿したコメントが残っているので、同じ違反に同じ指摘を重ねて投稿しない。

- 既存コメントに同じリソース・同じ違反内容への指摘がすでにあれば、その違反へのインラインコメント投稿はスキップする
- 全違反が既存コメントで指摘済みなら、サマリコメントも投稿しない（何も投稿せず終了してよい）
- 新しく増えた違反、または行が変わって既存コメントが outdated になった違反だけ投稿する

## コメントの型

各インラインコメントは次の構成で書く。見出しはこの表記をそのまま使う。日本語で書く。

1. **ルールの意図**: `msg` の直訳ではなく、Rego ルールがこの設定を禁止することで何を防いでいるかまで書く。2〜3文
2. **修正方法**: 1〜2文
3. **suggestion ブロック**: 付けられる場合のみ（次の基準を参照）

## suggestion を付ける基準

- 修正後の値が機械的に一意に決まる場合だけ suggestion を付ける（例: `encrypted = true`）
- 修正値に人の判断が要る場合は付けない（例: 許可すべき CIDR、Owner タグに入れる値）。代わりに、考えられる選択肢とその決め方を解説に書く
- 理由: 判断が要る値を suggestion に入れると、ワンクリックで誤った値がコミットされる

## 投稿方法

- CI（GitHub Actions）では `mcp__github_inline_comment__create_inline_comment` を使う。`path`・`line`（複数行なら `startLine` と `line`）・`body` を指定し、`confirmed: true` で投稿する
- suggestion は body 内の ```suggestion フェンスで書く。suggestion は指定した行範囲全体を置き換えるため、置換後の内容は行として構文が完結していること（インデントも元ファイルに合わせる）
- suggestion は PR の差分に含まれる行にしか付けられない。差分外の行を直す必要がある場合は、コメント本文に通常のコードブロックで修正例を示す
- インラインコメントのツールが使えない環境（ローカル実行など）では、投稿予定の内容を「ファイルパス:行番号」付きで標準出力に出力する

       - uses: hashicorp/setup-terraform@v4
       - run: terraform init
       - run: terraform plan -out=tfplan
       - run: terraform show -json tfplan > plan.json
-      - shell: bash
+      - id: conftest
+        shell: bash
         run: |
           docker run --rm -v "$PWD":/project \
             openpolicyagent/conftest:v0.68.2 \
             test plan.json --policy policy --output json | tee conftest-result.json
       - if: always()
         uses: actions/upload-artifact@v7
         with:
           name: conftest-result
           path: terraform-conftest-opa/conftest-result.json
+      # conftest が違反で落ちたときだけ Claude を動かす。
+      # failure() が無いと暗黙の success() が AND され、直前の失敗後は評価されない。
+      # steps.conftest.outcome で「conftest の失敗」に限定する（terraform plan 自体の失敗では動かさない）。
+      - id: claude
+        if: failure() && steps.conftest.outcome == 'failure'
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            /conftest-explain terraform-conftest-opa/conftest-result.json の違反を解説してください。
+            各違反は該当行にインラインコメント（日本語解説 + 修正提案）で投稿してください。
+          claude_args: |
+            --allowedTools "Read,Grep,Glob,mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

[
	{
		"filename": "plan.json",
		"namespace": "main",
		"successes": 1,
		"failures": [
			{
				"msg": "aws_ebs_volume.data: EBS volume not encrypted",
				"metadata": { "query": "data.main.deny" }
			},
			{
				"msg": "aws_security_group.web: ingress open to 0.0.0.0/0 (port 80)",
				"metadata": { "query": "data.main.deny" }
			}
		]
	}
]

  encrypted         = true