<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-04-02 -->

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

## Purpose

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

## Key Files

| 파일 | 명령어 | 역할 |
|------|--------|------|
| `validate.md` | `/project:validate` | Terraform 포맷, 문법, 유효성 검증 |
| `plan.md` | `/project:plan ENV=dev` | 환경별 Terraform plan 실행 |
| `security-check.md` | `/project:security-check` | SCP 보안 정책 검증 |
| `review-impact.md` | `/project:review-impact` | 파일 변경 영향범위 분석 |

## validate.md — IaC 검증

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

### 사용
```bash
/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

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

### 사용
```bash
/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)을 기반으로 코드 검사

### 사용
```bash
/project:security-check
```

### 검사 항목

| 항목 | 정책 | 검사 방법 |
|------|------|---------|
| 자격증명 | 환경변수만 사용 | grep 패턴 |
| 리전 | kr-west1, kr-east1만 | 리소스 속성 |
| 이미지 레지스트리 | harbor.scp.internal | YAML 이미지 필드 |
| 이미지 태그 | latest 금지 | 태그 버전 검증 |
| Pod 보안 | SecurityContext 필수 | YAML 구조 검증 |
| 서버 타입 | s1v*, db1v*, dbh2v* | 인스턴스 타입 패턴 |
| 암호화 | encrypt=true | backend.tf 설정 |

### 출력 예시
```
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 — 영향범위 분석

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

### 사용
```bash
/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. 명령어 메타데이터**

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

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

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

## Example
구체적인 사용 예시
```

**2. 환경변수 처리**

```bash
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` — 명령어 래퍼