Terragruntのバージョンアップ影響調査をClaude Codeのskillにして公開した話
こんにちは！2年目クラウドエンジニアのうしです。
今のプロジェクトで、開発の途中にTerragruntが1.0.0になりました。その調査がしんどかったので、「Terragruntのバージョンを上げたら何が壊れるか」を調べるClaude Codeのskillを作って、GitHubで公開しました。一番効いた設計判断は、skillに知識を持たせないことでした。
想定読者
- Terragruntのバージョンアップで何が壊れるか、リリースノートを追うのがしんどい人
- Claude Codeのskillを作ってみたいけど、何を書けばいいかわからない人
- 公開されているskillを入れる前に、どこを見ればいいか気になる人
この記事で身につくこと
- 知識を埋め込まず、実行時に一次情報を読ませる設計
- 作ったskillを、正解入りのテストデータで検証する方法
- 他人のskillを使う前に見るところ
自己紹介
- 2年目のクラウドエンジニア
- 今のプロジェクトでTerraformとTerragruntを触っている
- skillを作って公開するのは今回が初めて
目次
- 作ったきっかけ
- 既存のskillの調査
- 設計：知識を持たせず、一次情報を読ませる方針
- 検証：正解入りのテストデータ
- 実在のリポジトリ2つでの検証
- 公開と、skillを使う側の注意
- まとめ
1. 作ったきっかけ
今のプロジェクトでは、次の2つのメジャーバージョンアップが重なりました。
- Terragruntが開発の途中で1.0.0になった
- AzureRMプロバイダが4.xから5.xになった
どちらも「何が壊れるか」を調べるのに苦労しました。AzureRMのほうは、TerraformとTerragruntのコードから影響箇所を洗い出す個人用のツールを作りました。このツールを作ったときの調査の記録をClaude Codeに見せて、「これをskillにしたら面白そうじゃね？」と思ったのが出発点です。
2. 既存のskillの調査
作る前に、同じskillがすでにないかを検索で調べました。
- Terraformのproviderやmoduleのアップグレード用には、ありました（
lgbarn/devops-skillsのprovider-upgrade-analysis） - Terragrunt本体のバージョンアップに絞ったskillは、見つかりませんでした
Terraformのprovider向けには既存のskillがあるので、自分が作るのはTerragrunt本体に絞りました。型はprovider-upgrade-analysisを借りています。原文を読むと、7ステップ、レポートの雛形、安全チェックリストなどが整っていたためです。
3. ワークフロー
このskillは、次の7ステップで検証します。
ベースにしたprovider-upgrade-analysisの7ステップのうち、2ステップを、Terragrunt固有の確認（5）と予行演習（7）に差し替えました。
4. 検証
自分で正解をおいたテスト用のリポジトリを作って、skillを検証しました。
リポジトリは、Terragrunt 0.67.0を使っている想定の小さな構成です。skillが見つけるべき問題と、紛らわしい記述を、入れてあります。
| 種類 | 例 | skillの正解 |
|---|---|---|
| 最新版で削除済みのコマンド・属性 |
apply-all、hclfmt、skip = true
|
「削除済み」と報告する |
| 構造の問題 |
terragrunt.hclとterragrunt.stack.hclが同じディレクトリにある |
報告する |
| 非推奨だが、まだ動く記述 | run-all |
「非推奨」と報告する |
| 名前が似ているだけの記述 | skip_outputs |
報告しない |
1回目はかなーり間違えました。hclfmtとgraph-dependenciesを、「v0.78.0で非推奨。公式ドキュメントにも載っているので、まだ動くはず」と報告（正解は「v0.90.0で削除済み」）。
公式ドキュメントが古かったうえに、全リリースを読まず、抜粋だけで判断したのが原因です。
そこで、skillに2つ足しました。
- 調べたい名前ごとに、全リリースのノートを検索して、最後に書かれた状態を採用する
- 全部を追えていない名前は、「削除済み」「非推奨」と断定せず、
status unverified（未確認）と書く
名前ごとの検索は、たとえばhclfmtならこのコマンドです。
gh api repos/gruntwork-io/terragrunt/releases --paginate \
--jq '.[] | select(.prerelease==false and ((.body // "") | contains("hclfmt"))) | .tag_name'
直したskillで同じ質問をすると、hclfmtとgraph-dependenciesは「v0.90.0で削除済み」と正しく報告されました。run-allも、削除の記録がないので、非推奨のままと報告されています。
5. 実在のリポジトリ2つでの検証
ここまでは自作のデータだったので、公開リポジトリのコードでも試しました。
-
cds-snc/forms-terraform（1.0.8から1.1.6へ）：削除は0件で、generateファイルの権限が0600になる（v1.1.5）などの指摘は、リリースノートと合っていました -
rust-lang/simpleinfraのterragruntディレクトリ：バージョン固定がなく、全項目がstatus unverifiedでした。skillが気になる点として挙げたrun_cmd("--terragrunt-quiet", ...)は、自分で調べるとv1.0.7のノートに現行の書式として出ていて、問題なさそうでした
6. 公開と、skillを使う側の注意
marketplace.jsonを置いたGitHubリポジトリにすると、次の2コマンドで入れられます。
claude plugin marketplace add gyudonmaruapp-cpu/terragrunt-upgrade-impact
claude plugin install terragrunt-upgrade-impact@terragrunt-upgrade-impact
入れる前に、次の2点を確認してください。
- 同梱のスクリプト：skillの隣に
scripts/などを置けます（同上） - 取得先のURL：このskillは実行時にWebを読むので、取得元が信用できるかを見てください
7. まとめ
- Terragruntのバージョンアップの影響を調べるskillを作り、公開した
- 知識は持たせず、リリースノートを実行時に読ませた。公式ドキュメントはリリースノートより古いことがあるので、判定はリリースノートを正とした
- 別のClaudeに使わせると、1回目は「まだ動くはず」と間違えた。名前ごとの追跡と
status unverifiedで防いだ
初めてのskill公開です。使ってみた感想や、ここが違うという指摘があれば、コメントやIssueでお待ちしています！