refactor-module

refactor-module スキルの概要

refactor-module ができること

refactor-module スキルは、巨大化した Terraform 設定を、入力・出力・カプセル化・移行計画が明確な再利用可能な module に分解するのを助けます。新規の module 設計向けではなく、既に稼働していて安全に保守しづらくなった Terraform コードをリファクタリングする用途に最適です。

どんな人に向いているか

Terraform の再利用性が低い、テストしにくい、あるいはロジック・リソース・state 管理が混在していて変更が怖いと感じるなら、refactor-module スキルを使う価値があります。実際に動いているスタックを state の文脈を失わずに module 境界へ切り出したい platform engineer、infra maintainer、レビュー担当者にとって、実用的な refactor-module guide になります。

何が違うのか

この refactor-module スキルは意思決定寄りです。ソース設定、module 名、目標の抽象化レベル、state 互換性の計画を前提にするため、単にファイルを並べ替えるだけの「modular にして」という一般的なプロンプトよりも実行性があります。interface、migration、registry packaging まで考慮させるので、結果が具体的になりやすいのが特徴です。

refactor-module スキルの使い方

インストールして、正しいコードを対象にする

refactor-module install では、サイトの hashicorp/agent-skills 向け skill installation flow を使い、実際にリファクタリングが必要な Terraform 設定を指定します。このスキルは source_directory、module_name、abstraction_level、preserve_state、必要に応じて target_registry を前提にしているので、曖昧なクリーンアップ依頼ではなく、これらの値を最初から渡すのが重要です。

最初に読むべきファイルを押さえる

まず SKILL.md を読んで workflow を把握し、そのうえで、命名規則、オーナーシップ、リリース要件を定めている repository context を確認します。周辺ドキュメントや module standard がある環境なら、skill を走らせる前にそれらも読んでおくと、命名、versioning、state migration の扱いが repo のパターンに揃いやすくなります。

雑な依頼を使えるプロンプトに変える

弱いプロンプトは「この Terraform を module 化してください」です。より強い refactor-module usage のプロンプトは、「source_directory=./infra/prod をリファクタリングし、module_name=vpc を作成し、abstraction_level=intermediate を使い、既存の本番環境に対して state 互換性を維持してください」となります。あわせて、重複リソース、interface の不明確さ、将来的に registry へ公開したいといった現在の痛点も入れてください。どこまで攻めたリファクタリングにするかが変わるためです。

手戻りを減らす workflow を使う

最初に現在の設定の分析を依頼し、その後で module の境界、variables、outputs、migration steps を依頼します。初回の結果が広すぎる場合は、networking や IAM のようにサブシステムを 1 つずつに絞ると、module 設計の検証がしやすくなり、state 移行計画の信頼性も保ちやすくなります。

refactor-module スキル FAQ

refactor-module は既存の Terraform コード専用ですか？

はい、refactor-module スキルは主に、保守しやすい module に分解する必要がある既存設定向けです。ゼロから始めるなら通常の design prompt で足りることもありますが、既に resource、dependency、state を維持する必要があるなら、このスキルのほうが適しています。

refactor-module を使う前に何を渡すべきですか？

最低でも、source directory、module 名、そして state 互換性を維持する必要があるかどうかを渡してください。registry target、命名標準、抽象化レベルに関する制約があるなら、それも含めるべきです。そうした情報があると、refactor-module skill があなたの環境に導入しづらい設計を出してしまうのを防げます。

refactor-module を使わないほうがいいのはいつですか？

小さな整理、命名の見直し、単発の Terraform 例だけが必要なら使わないでください。現在の resource や state について十分な文脈を共有できない場合も不向きです。module refactoring は dependency の把握と migration 制約が前提になるためです。

refactor-module スキルを改善する方法

スキルにより強い制約を与える

refactor-module の結果が最も良くなるのは、明確な境界を与えたときです。module に含めるもの、root configuration に残すもの、本番 state の都合で変更できないものをはっきりさせてください。これを曖昧にすると、モデルが resources を過度に抽象化したり、技術的には整っていても運用コストの高い migration path を提案したりすることがあります。

望む結果だけでなく、今の痛みも伝える

なぜリファクタリングが必要なのかを伝えてください。たとえば、重複したスタック、頻繁な drift、変更の遅さ、社内公開の予定などです。そうすると、refactor-module skill は reuse と simplicity のどちらをどこまで優先すべきかを判断しやすくなります。Terraform の module 作業で最も難しいのは、しばしばこのトレードオフです。

出力は interface の品質と migration の現実性で確認する

まず variables、outputs、命名、dependency flow を確認し、そのうえで state migration plan が実際のデプロイ方法と合っているかを検証してください。最初の回答が一般的すぎるなら、より狭い抽象化レベルを指定する、あるいは state をより保守的に維持する方針で再依頼すると改善しやすいです。単に「もっと詳しく」と求めるよりも、そのほうが最終的な refactor-module guide は良くなることが多いです。