메뉴
Guides systematic infrastructure troubleshooting. Use when services fail, builds break, deployments go wrong, or infrastructure behaves unexpectedly. Use when you need root-cause analysis rather than guessing.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Defines the mandatory footer template for all .md files — GitHub badges, dates, and license. Use when creating or modifying any markdown document.
Defines operating rules for all agents. Use when executing any task — confirms before action, requires rollback plans for dangerous operations, enforces naming conventions and credential placeholders.
Bash 스크립트 작성 시 표준 로깅 함수와 에러 처리 패턴을 적용합니다. 새 스크립트 생성 또는 기존 스크립트 개선 시 사용합니다. 이 skill을 참조할 때 응답 첫 줄에 "🟡 참조: skill://bash-script-template" 를 출력합니다.
Guides test writing with AAA pattern, BVA, EP, and edge case analysis. Use when writing unit tests, integration tests, or infrastructure validation tests.
Provides a structured code review checklist. Use when reviewing code, scripts, or IaC files. Covers correctness, security, error handling, performance, and infrastructure as code.
Subjects non-trivial infrastructure decisions to adversarial review before they stand. Use when making production changes, security-sensitive modifications, irreversible operations, or working in unfamiliar infrastructure code.
| name | debugging-and-recovery |
| description | Guides systematic infrastructure troubleshooting. Use when services fail, builds break, deployments go wrong, or infrastructure behaves unexpectedly. Use when you need root-cause analysis rather than guessing. |
인프라/시스템 장애 발생 시 체계적으로 원인을 추적하고 복구하는 워크플로우입니다. 추측 대신 증거 기반으로 진단하며, 복구 후 재발 방지 조치까지 포함합니다.
장애 발생 시 즉시:
1. STOP — 추가 변경 중단
2. PRESERVE — 증거 보존 (로그, 메트릭, 상태)
3. DIAGNOSE — 트리아지 체크리스트 수행
4. FIX — 근본 원인 수정
5. GUARD — 재발 방지 조치
6. RESUME — 검증 완료 후에만 재개
순서대로 수행합니다. 단계를 건너뛰지 않습니다.
장애를 확인하고 재현합니다.
# 서비스 상태 확인
systemctl status <service>
journalctl -u <service> --since "5 min ago"
# 네트워크 확인
curl -sS -o /dev/null -w "%{http_code}" http://localhost:8080/health
ss -tlnp | grep <port>
# AWS 리소스 상태
aws ec2 describe-instance-status --instance-ids <id>
aws ecs describe-services --cluster <cluster> --services <svc>
# Docker / Container 로그
docker logs --since 5m <container>
docker inspect --format='{{.State.Health.Status}}' <container>
# 시스템 리소스 확인
free -h && df -h && uptime
dmesg | tail -20
어느 계층에서 문제가 발생하는지 좁힙니다.
장애 위치 판별:
├── Network → SG, NACL, Route Table, DNS, NLB/ALB health check
├── Compute → EC2 상태, ECS task, 메모리/CPU, disk full
├── Storage → EBS, S3 권한, RDS 연결 수/스토리지
├── IAM/Auth → Role, Policy, STS assume 실패
├── Config → 환경변수, Parameter Store, Secrets Manager
├── Deploy → 배포 스크립트, Terraform state drift
└── External → 외부 API, 서드파티 서비스 장애
최소 재현 조건을 만듭니다.
git log, Terraform state, 배포 이력)# 최근 인프라 변경 확인
terraform show | diff - <(terraform plan -no-color)
git log --oneline --since="1 hour ago"
# CloudTrail 최근 이벤트
aws cloudtrail lookup-events --lookup-attributes \
AttributeKey=EventName,AttributeValue=StopInstances \
--max-results 5
증상이 아닌 근본 원인을 수정합니다.
증상 수정 (나쁨):
→ 서비스 재시작만 반복
근본 원인 수정 (좋음):
→ OOM 발생 원인 파악 → 메모리 제한 조정 또는 메모리 누수 수정
→ 디스크 풀 → 로그 로테이션 설정 + 불필요 파일 정리
→ SG 규칙 누락 → Terraform에 규칙 추가
재발 방지 조치:
skill://incremental-change 워크플로우 적용복구 후 전체 검증:
# 서비스 정상 동작 확인
curl -f http://endpoint/health
# Terraform state 정합성
terraform plan # "No changes" 확인
# 모니터링 정상화 확인
# CloudWatch 대시보드, 알림 해제 확인
terraform apply 실패:
├── State lock → terraform force-unlock (확인 후)
├── Provider error → 자격증명, 리전, API 제한 확인
├── Resource conflict → state에서 import 또는 taint
├── Dependency error → depends_on 누락, 순서 문제
└── Quota exceeded → Service Quotas 확인, 요청
playbook 실패:
├── SSH 연결 → 키, SG, 호스트명 확인
├── 권한 → become/sudo 설정
├── 패키지 → 리포지토리 접근, 버전 충돌
├── 템플릿 → 변수 미정의, Jinja2 문법
└── 멱등성 → changed vs failed 구분
서비스 접근 불가:
├── 403 Forbidden → IAM Policy, Resource Policy, SCP
├── 503 Service Unavailable → 서비스 상태 페이지, 리전 장애
├── Timeout → SG, NACL, Route Table, VPC Endpoint
├── Throttling → API 호출 제한, 백오프 필요
└── Drift → 콘솔 수동 변경 → terraform import
| 조건 | 조치 |
|---|---|
| 배포 후 5분 이내 장애 | 즉시 롤백 |
| 데이터 마이그레이션 포함 | 롤백 불가 → forward fix |
| 부분 장애 (일부 사용자) | feature flag OFF → 조사 |
| 인프라 변경 후 장애 | terraform apply 이전 state 복원 |
| Rationalization | Reality |
|---|---|
| "재시작하면 될 것 같습니다" | 근본 원인을 모르면 재발합니다. 원인 파악 후 재시작합니다. |
| "로그를 안 봐도 알 것 같습니다" | 추측은 70% 맞고 30%는 시간 낭비입니다. 로그부터 확인합니다. |
| "콘솔에서 빨리 고치겠습니다" | 수동 수정은 drift를 만듭니다. IaC로 수정합니다. |
| "나중에 모니터링 추가하겠습니다" | 지금 추가하지 않으면 같은 장애를 또 겪습니다. |
| "이건 일시적 문제입니다" | 일시적이라도 원인을 기록합니다. 패턴이 보일 수 있습니다. |
장애 복구 후 확인: