.claude/commands/ — 커스텀 명령어

Purpose

/project:xxx 형식의 커스텀 명령어를 정의합니다. IaC 검증, 플랜 실행, 보안 검사, 영향범위 분석 등 프로젝트 고유의 작업을 자동화합니다.

Key Files

validate.md — IaC 검증

목적

OpenTofu 코드의 포맷, 문법, 유효성을 검증합니다.

사용

/project:validate

실행 단계

1. 포맷 검사 (tofu fmt -recursive -check)

   • 모든 .tf 파일이 표준 형식을 준수하는지 확인
   • 실패 시 수정 명령 제시

2. 문법 검증 (tofu validate)

   • Terraform 설정 유효성 확인
   • 모듈 참조, 변수 타입 검사

3. 코드 품질 (tflint)

   • 명명 규칙, 사용되지 않는 변수 감지
   • 잠재적 버그 식별

출력 예시

Terraform 검증
==============

✅ 포맷 검사 (tofu fmt)
   모든 파일이 표준 형식을 준수합니다.

✅ 문법 검증 (tofu validate)
   environments/dev: VALID
   environments/staging: VALID
   environments/prod: VALID

✅ 코드 품질 (tflint)
   검사 완료 — 문제 없음

결론: 모든 검증을 통과했습니다.

실패 대응

❌ 포맷 검사 실패

수정 방법:
tofu fmt -recursive

또는 환경별:
tofu fmt -chdir=environments/dev

plan.md — Terraform Plan

목적

환경별 변경 사항을 미리 확인합니다.

사용

/project:plan ENV=dev
/project:plan ENV=staging
/project:plan ENV=prod

실행 단계

1. 환경 선택 (dev / staging / prod)
2. tofu init (백엔드 미연결, 로컬 상태)
3. tofu plan (변경 사항 분석)
4. 결과 요약 (추가/변경/삭제 리소스 수)

출력 예시

Terraform Plan — dev 환경
=========================

Plan: 3 to add, 1 to change, 0 to destroy

추가 리소스:
+ aws_vpc.main
  - region: kr-west1
  - cidr_block: 10.0.0.0/16

+ aws_subnet.private[0]
  - vpc_id: (computed)
  - cidr_block: 10.0.1.0/24

변경 리소스:
~ aws_instance.bastion
  - instance_type: s1v2m4 → s1v4m8 (변경)

권장 사항:
1. staging 환경도 검증: /project:plan ENV=staging
2. 변경 사항 검토 후 배포: /usr/bin/make apply ENV=dev

security-check.md — 보안 정책 검증

목적

SCP 보안 정책(CLAUDE.md)을 기반으로 코드 검사

사용

/project:security-check

검사 항목

출력 예시

SCP 보안 정책 검증
=================

✅ 자격증명 정책
   환경변수 사용 확인됨

❌ 리전 정책
   파일: environments/prod/main.tf (line 42)
   문제: region = "us-east-1" (금지됨)
   수정: region = "kr-west1" 또는 "kr-east1"

⚠️ 이미지 태그 정책
   파일: cluster-services/argocd/deployment.yaml
   문제: image: harbor.scp.internal/argocd:latest
   권장: 명시적 버전 (예: v2.10.3)

✅ Pod 보안 컨텍스트
   모든 Pod에 필수 SecurityContext 확인

요약:
- 통과: 5개
- 경고: 1개
- 실패: 1개

다음 단계:
[ ] FAIL 항목 수정
[ ] WARN 항목 검토
[ ] 다시 검증: /project:security-check

review-impact.md — 영향범위 분석

목적

파일 변경 시 영향받는 상위 리소스와 검증 항목을 분석합니다.

사용

/project:review-impact

분석 절차

1. 변경 파일 수집 (git diff)
2. 의존성 조회 (dependency-map.json)
3. 상위 모듈/환경 식별
4. 각 리소스 영향 분석
5. 권장 검증 항목 제시

출력 예시

파일 변경 영향범위 분석
=======================

변경 파일 (3개):
1. modules/security/main.tf
   - security group 규칙 수정
   
2. modules/security/variables.tf
   - 변수 추가/수정

3. policies/opa/networking.rego
   - 네트워킹 정책 추가

영향받는 리소스:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔴 environments/dev/main.tf
   - security 모듈 호출 (line 34-40)
   - 변수: ingress_cidr_blocks, egress_rules
   - 영향도: HIGH (SG 변경은 즉시 영향)

🟡 environments/staging/main.tf
   - security 모듈 호출 (line 28-35)
   - 변수: ingress_cidr_blocks
   - 영향도: MEDIUM

🟡 environments/prod/main.tf
   - security 모듈 호출 (line 41-48)
   - 변수: ingress_cidr_blocks, egress_rules
   - 영향도: MEDIUM (prod는 신중하게)

권장 검증:
━━━━━━━━━━

[] dev 환경
   1. tofu plan -var-file=dev.tfvars | grep security_group
   2. 변경 사항 확인
   3. /project:security-check로 정책 검증

[] staging 환경
   1. tofu plan -var-file=staging.tfvars
   2. 결과 검토

[] prod 환경
   1. tofu plan -var-file=prod.tfvars
   2. 변경 사항 신중히 검토
   3. 검증 후 배포 승인 받기

[] 정책 검증
   1. opa test policies/opa/ -v
   2. conftest test policies/conftest/terraform/ plan.json

[] 통합 테스트
   1. make policy-test
   2. make security-scan

For AI Agents

명령어 구현 패턴

1. 명령어 메타데이터

> 사용: /project:my-command [ARGS]
> 버전: 1.0.0
> 마지막 업데이트: 2026-04-02

## Purpose
명령어의 목적을 간단히 설명

## How It Works
동작 방식 (단계별)

## Example
구체적인 사용 예시

2. 환경변수 처리

ENV="${ENV:-dev}"  # 기본값: dev

# 유효성 검증
case "$ENV" in
  dev|staging|prod) ;;
  *) echo "Invalid ENV: $ENV"; exit 1 ;;
esac

3. 결과 형식화

## 제목

✅ 통과 항목
❌ 실패 항목
⚠️ 경고 항목

### 상세 분석
파일별, 리소스별 세부 결과

### 권장 조치
다음 단계 및 명령어

명령어 추가 시 체크리스트

• 사용법 명확히 (인자, 옵션)
• 동작 단계 상세 설명
• 성공/실패 사례 예시
• 에러 처리 방법
• 관련 명령어 링크
• 주의사항 (prod 환경 등)
• 로컬 테스트 실행

참고 자료

• ../AGENTS.md — .claude/ 디렉토리 개요
• ../agents/AGENTS.md — 에이전트 가이드
• ../../AGENTS.md — 루트 컨텍스트
• ../../CLAUDE.md — 보안 정책
• ../../Makefile — 명령어 래퍼