Terraform 및 OpenTofu를 위한 AI 코딩 에이전트용 모범 사례 스킬

AI 코딩 에이전트(Claude Code, Cursor, Copilot, Gemini CLI, OpenCode, Codex, Kiro 등)를 위한 Terraform 및 OpenTofu의 모범 사례 스킬입니다. 이 스킬은 에이전트가 코드 테스트, 모듈 구조화, CI/CD 설정, 그리고 프로덕션 인프라 코드를 작성하는 데 도움을 줍니다.

AWS, Azure, GCP 모두 일급(first-class)으로 지원됩니다. 예제에서는 AWS가 기본값으로 유지되지만, 동일한 백엔드, 인증, 보안 및 리소스 가이드라인이 세 가지 환경에 모두 적용됩니다. 어떤 패턴의 Azure 또는 GCP 등가물을 요청하면 스킬이 이를 매핑합니다.

테스트 프레임워크

• 네이티브 테스트 대 Terratest 결정 매트릭스
• 테스트 워크플로우(정적, 통합, E2E)
• 예제 및 패턴

모듈 개발

• 구조 및 명명 규칙
• 버전 관리 전략
• 공개 모듈 대 비공개 모듈 패턴

상태 관리

• 원격 백엔드(S3, Azure, GCS, Terraform Cloud)
• 잠금 및 보안
• 다중 팀 상태 격리
• 마이그레이션 및 복구 절차

CI/CD 통합

• GitHub Actions 워크플로우
• GitLab CI 예제
• 비용 최적화
• 규정 준수 자동화

보안 및 규정 준수

• Trivy 및 Checkov 통합
• 정책형 코드(Policy-as-code) 패턴
• 규정 준수 스캐닝 워크플로우

빠른 참고 자료

• 의사 결정 흐름도
• 일반적인 패턴 (DO vs DON'T)
• 치트 시트

하나의 Claude Code 마켓플레이스, antonbabenko/agent-plugins를 통해 설치할 수 있습니다.

(terraform-skill은 여기서 외부 플러그인으로 나열됩니다). antonbabenko/terraform-skill을 별도로 마켓플레이스에 추가하지 마세요. 둘 다 동일한 마켓플레이스 이름을 사용하므로 충돌이 발생합니다.

모든 Agent Skills 호환 도구에서 작동합니다:

npx skills add https://github.com/antonbabenko/terraform-skill

Claude Code

/plugin marketplace add antonbabenko/agent-plugins
/plugin install terraform-skill@antonbabenko

Gemini CLI

gemini extensions install https://github.com/antonbabenko/terraform-skill

gemini extensions update terraform-skill

.

Cursor

git clone https://github.com/antonbabenko/terraform-skill.git ~/.cursor/skills/terraform-skill

Cursor는 .agents/skills/ 및 .cursor/skills/에서 스킬을 자동으로 발견합니다.

Copilot

/plugin install https://github.com/antonbabenko/terraform-skill
# 또는
git clone https://github.com/antonbabenko/terraform-skill.git ~/.copilot/skills/terraform-skill

Copilot은 .copilot/skills/에서 스킬을 자동으로 발견합니다.

OpenCode

git clone https://github.com/antonbabenko/terraform-skill.git ~/.agents/skills/terraform-skill

OpenCode는 .agents/skills/, .opencode/skills/, 및 .claude/skills/에서 스킬을 자동으로 발견합니다.

Codex (OpenAI)

git clone https://github.com/antonbabenko/terraform-skill.git ~/.agents/skills/terraform-skill

Codex는 ~/.agents/skills/ 및 .agents/skills/에서 스킬을 자동으로 발견합니다. 업데이트는 cd ~/.agents/skills/terraform-skill && git pull로 수행하세요.

관리되는 Codex 플러그인 설치를 위해서는 antonbabenko/agent-plugins 마켓플레이스를 사용하세요 (codex plugin marketplace add antonbabenko/agent-plugins 후, terraform-skill을 설치). 별도의 마켓플레이스로 antonbabenko/terraform-skill을 추가하지 마세요. 이는 이름이 agent-plugins와 충돌하기 때문입니다.

Autohand Code

스킬을 전역으로 설치하려면:

git clone https://github.com/antonbabenko/terraform-skill.git
mkdir -p ~/.autohand/skills
cp -R terraform-skill/skills/terraform-skill ~/.autohand/skills/

또는 현재 프로젝트에만 설치하려면:

git clone https://github.com/antonbabenko/terraform-skill.git
mkdir -p .autohand/skills
cp -R terraform-skill/skills/terraform-skill .autohand/skills/

Autohand Code는 ~/.autohand/skills/ 및 .autohand/skills/에서 스킬을 발견합니다.

Kiro

git clone https://github.com/antonbabenko/terraform-skill.git ~/.kiro/skills/terraform-skill

Kiro는 .kiro/skills/(작업 공간) 및 ~/.kiro/skills/(전역)에서 스킬을 자동으로 발견합니다.

Antigravity/Antigravity IDE/Antigravity CLI

git clone https://github.com/antonbabenko/terraform-skill.git
ln -s "$(pwd)/terraform-skill/skills/terraform-skill" ~/.gemini/config/skills/terraform-skill"

git pull로 업데이트하세요.

Kiro

이 레포지토리는 또한 Kiro Power(루트 POWER.md

• 선택적 mcp.json)

입니다. Kiro에서는 **Powers 패널 → "GitHub에서 power 추가"**를 선택한 후 다음을 붙여넣으세요:

Kiro는 키워드 일치(예: "terraform", "opentofu", "state", "modules") 시 power를 활성화합니다. 이를 설치하면 또한 선택적 읽기 전용 HashiCorp terraform-mcp-server(
(mcp.json에서)
)가 ~/.kiro/settings/mcp.json의 Powers 섹션에 등록됩니다.
— 이 기능은 이것 없이도 작동합니다. POWER.md는 skills/terraform-skill/SKILL.md에서 생성됩니다;
; 스킬 내용은 중복되지 않고 공유됩니다.

수동 (symlink 로컬 클론)

git clone https://github.com/antonbabenko/terraform-skill
mkdir -p ~/.claude/plugins
ln -s "$(pwd)/terraform-skill" ~/.claude/plugins/terraform-skill

Claude는 다음 실행 시 skills/terraform-skill/SKILL.md에서 스킬을 자동 발견합니다. 클론된 내용의 수정 사항은 실시간으로 반영됩니다.

설치 후, 다음을 시도해 보세요:

"S3 버킷에 대한 테스트가 포함된 Terraform 모듈 생성"

Claude는 Terraform 또는 OpenTofu 코드를 다룰 때 자동으로 스킬을 가져옵니다.

이것과 함께 code-intelligence 플러그인을 설치하세요:

/plugin marketplace add antonbabenko/agent-plugins
/plugin install code-intelligence@antonbabenko

이는 코드 탐색을 위한 일반적인, 모든 언어 규칙(언어 서버 사용 시점, 일반 텍스트 검색 또는 퍼지 검색; 조회 대상을 특정 위치에 고정하는 방법; 도구가 실패했을 때 할 일; 한 도구가 다른 것으로 교체될 때 알리는 것)을 담고 있습니다. terraform-skill은 이러한 규칙의 Terraform 전용 버전입니다. 왜 설치해야 하는가:

토큰 절감 (Fewer tokens) - 규칙이 한 곳에 존재합니다. 에이전트는 필요할 때 로드하며 모든 언어 스킬에 반복해서 포함하지 않습니다.정확도 향상 (More accurate) - 단순 텍스트 매칭이 아닌 의미로 정의와 참조를 찾기 때문에, 이름 변경(renames)이나 리팩토링을 하더라도 누락되거나 잘못된 부분을 수정하는 일이 없습니다.속도 개선 (Faster) - 재시도하는 대신 처음부터 올바른 도구를 선택하며, 다른 도구를 사용해야 했을 경우 그 사실을 미리 알려줍니다.

terraform-skill은 독립적으로 작동합니다. code-intelligence라는 이름은 고유하지 않으므로, 만약 code-intelligence 스킬이 활성화되어 있다면 antonbabenko/agent-plugins의 것인지 확인하십시오.

테스트가 포함된 모듈 생성 (AWS / Azure / GCP):

"네이티브 테스트가 적용된 AWS VPC용 Terraform 모듈을 생성해 줘"

"Azure 모듈 구축: VNet, 서브넷 및 PostgreSQL Flexible Server를 네이티브 테스트와 함께 포함하여"

"네이티브 테스트가 적용된 GCP VPC 네트워크, 서브네트워크 및 Cloud SQL Postgres용 모듈 작성"

원격 상태 설정 (Set up remote state):

"Terraform 상태에 대한 S3 백엔드를 네이티브 use_lockfile 잠금 기능과 암호화 기능을 사용하여 구성해 줘"
"AWS, Azure 또는 GCP용 원격 상태 백엔드를 선택하고 구성하기 (잠금, 암호화, 버전 관리)"

기존 코드 검토 (Review existing code):

"모범 사례를 따라 이 Terraform 구성을 검토해 줘"

CI/CD 워크플로우 생성 (Generate CI/CD workflow):

"비용 추정 기능이 포함된 Terraform용 GitHub Actions 워크플로우를 생성해 줘"

테스트 전략 (Testing strategy):

"모듈에 대해 네이티브 테스트와 Terratest 중 어떤 것을 선택해야 할지 도와줘"

상태 관리 (State management):

"다중 팀 환경을 위해 상태 파일은 어떻게 구성하는 것이 좋을까?"

(이 예시들은 최신 Terraform/OpenTofu - use_lockfile이 1.10 이상, write_only가 1.11 이상임을 가정합니다.)

AWS: 프로덕션 서비스 (모듈 + 구성, OIDC, 네이티브 잠금)

"AWS에서 새로운 프로덕션 서비스를 구축하고 있어. VPC에 대한 재사용 가능한 Terraform 모듈과 공용/비공용 서브넷을 가진 3개 AZ를 위한 prod/staging 구성을 설계해 줘. ALB 뒤의 ECS Fargate 서비스와 RDS Postgres 인스턴스를 포함해야 해. 네이티브 terraform test도 포함해 줘"}

커버리지, 설명/유형/검증이 포함된 변수(variables with descriptions/types/validation), 암호화가 적용된 S3 원격 상태(S3 remote state with encryption), 버킷 버전 관리(bucket versioning), 그리고 네이티브 use_lockfile

잠금 기능 (locking) (Terraform 1.10+). 비밀 값은 plan/state에서 제외하고, write_only를 사용하세요.

/*_wo

프로바이더가 지원하는 경우의 인자(arguments where the provider supports them) (Terraform 1.11+)와 런타임 시크릿을 위한 Secrets Manager/SSM 참조. PR에 대해 fmt/validate/tflint/trivy를 실행하고, 검토된 plan 아티팩트를 생성하며, AWS OIDC를 통해 이를 적용하는 GitHub Actions 워크플로우를 추가하세요 (정적 키 사용 금지). 프로덕션/스테이징 상태는 격리하고 명명 규칙을 따르세요.

GCP: AWS 패턴 포팅 (Cross-cloud 매핑, WIF, gcs 백엔드)

"우리는 클라우드 전반에 걸쳐 IaC를 표준화하고 있습니다. 우리의 AWS 모듈 패턴을 GCP로 가져오세요: 재사용 가능한 모듈과 VPC 네트워크, 리전별 서브네트워크, 그리고 Cloud SQL Postgres 인스턴스(google_sql_database_instance)를 위한 환경 구성입니다. 원격 상태에는 gcs 백엔드 (bucket + prefix)를 사용하고, 객체 버전 관리(object versioning), 균일한 버킷 수준 액세스(uniform bucket-level access), 퍼블릭 액세스 방지(public access prevention), 그리고 IAM 바인딩이 적용된 상태 부트스트랩 버킷을 별도로 보여주세요. 키 없는 GitHub Actions 인증(장기 서비스 계정 키 사용 금지)을 위해 Workload Identity Federation을 사용하고 네이티브 테스트도 포함하세요. 또한 팀이 AWS에서 GCP로의 매핑을 볼 수 있도록 교차 클라우드 동등물(리소스 + 백엔드)도 보여주세요."

네이티브 테스트 (Terraform 1.6+) 대 Terratest (Go 기반)에 대한 의사 결정 매트릭스, 그리고 다중 환경 테스트 패턴.

명명 규칙 (terraform-<PROVIDER>-<NAME>), 디렉터리 구조, 입/출력 설계, 버전 제약 조건, 그리고 문서화 표준.

GitHub Actions, GitLab CI, Atlantis, Infracost 비용 추정, Trivy/Checkov 스캐닝, 그리고 규정 준수 검사.

정적 분석(Static analysis), 정책-코드(policy-as-code), 시크릿 관리(secrets management), 상태 파일 보안(state file security), 백엔드 암호화(backend encryption), 그리고 규정 준수 스캔 워크플로우.

변수 명명, 리소스 명명, 모듈 구성, 상태 관리, 프로바이더 구성에 대한 나란히 놓인 DO vs DON'T 예시.

이 스킬은 현장에서 검증된 Terraform 및 OpenTofu 패턴에서 시작되었으며, 필요한 가이드라인을 발견하고 이를 추가한 사람들의 기여를 통해 성장했습니다.

출처:

• terraform-best-practices.com의 패턴
• terraform-aws-modules 컬렉션 전반에 걸쳐 사용된 접근 방식
• 엔터프라이즈 IaC(Infrastructure as Code) 분야에서의 AWS Hero 경험

버전별 가이드라인:

• Terraform 1.0+ 기능
• OpenTofu 1.6+ 호환성
• 네이티브 테스트 프레임워크 (1.6+)
• 현재 도구 생태계 (2024-2026)

의사결정 프레임워크: 단순히 '무엇을 할지'가 아니라 '언제, 왜 해야 하는지'.

• 스킬 지원이 있는 AI 에이전트: Claude Code, Cursor, Copilot, Gemini CLI, OpenCode, Codex, Kiro 또는 모든 Agent Skills와 호환되는 호스트
• Terraform 1.0+ 또는 OpenTofu 1.6+
• 선택 사항: 레지스트리 통합을 위한 Terraform MCP 서버

이 스킬은 언어 서버 없이도 작동합니다. 정의를 따라가거나, 참조를 찾거나, 파일을 개요화하거나, 호버 문서를 표시하는 경우 HashiCorp의 공식 Terraform 언어 서버인 terraform-ls를 사용할 수도 있습니다.

선택 사항. terraform-ls가 없으면 스킬은 텍스트 검색(rg)과 파일 읽기로 대체됩니다. 아무것도 작동하지 않는 것은 아니며, 의미 기반 일치 대신 텍스트 매치를 얻게 됩니다.필수. 작업 공간에서 PATH에 있는 로컬 terraform(또는 tofu) 바이너리와 terraform init 실행이 필요하며, 그래야 모듈과 프로바이더 전반의 이름을 해결할 수 있습니다.설치. terraform-ls 릴리스 페이지에서 받거나 에디터 또는 에이전트 호스트를 통해 활성화합니다. 호스트가 지원하는 버전을 사용하세요.- Claude Code: LSP 플러그인으로 설치 -
/plugin marketplace add boostvolt/claude-code-lsps
후에 /plugin install terraform-ls@claude-code-lsps.

• Claude Code: LSP 플러그인으로 설치 -

스킬이 이를 사용하는 방법:

• 언어 서버를 사용하여 이름이 정의되거나 사용된 곳을 따라가고; 정확한 텍스트, 알려진 이름, .tfvars의 경우 rg와 파일 읽기를 사용합니다.

, 주석 및 non-HCL 파일. - 언어 서버를 먼저 파일의 특정 위치로 지정하세요(발생 지점을 찾은 다음, 해당 위치에 대해 질문하세요).

• terraform-ls는 이름을 대신 변경해 줄 수 없습니다. 변수, 로컬 값 또는 아웃풋을 이름 변경하려면: 모든 참조를 찾은 다음, 각각을 수동으로 편집해야 합니다. 리소스나 모듈 주소(address)를 이름 변경하려면 텍스트 대체가 아닌 moved 블록을 사용하세요.

스킬 개발 가이드라인, 콘텐츠 구조, 개선 제안 방법 및 검증 접근 방식에 대해서는 CLAUDE.md를 참조하세요.

버그 보고 또는 기능 요청은 GitHub Issues를 통해 하세요.

• Terraform Language

• Terraform Testing - 네이티브 테스트 프레임워크

• OpenTofu Documentation

• HashiCorp 권장 모범 사례

• Terraform compliance-as-code 문서 - 규정 준수 프레임워크, 제어(controls), 구현 가이드, 수정 사항 등

• Awesome Terraform

• Awesome Terraform Compliance

• Terraform Best Practices - 이 스킬의 기반이 되는 가이드

• terraform-aws-modules - AWS 모듈 컬렉션

• Terratest - Terraform을 위한 Go 테스트 프레임워크

• Google Cloud Best Practices

• AWS Terraform Best Practices