Official References: Best Practices · Review · Worktrees · Automations
왜 이 플레이북이 필요한가
사고 상황의 실패는 대부분 기술보다 프로세스에서 먼저 발생합니다.
- 오너십 불명확
- 약한 근거 스냅샷
- 늦은 롤백 의사결정
이 플레이북은 복구 속도를 유지하면서도 Codex 사고 대응을 결정론적으로 유지하기 위한 기준입니다.
심각도 매트릭스
| 레벨 | 대표 영향 | 기본 대응 자세 |
|---|---|---|
| SEV-1 | 사용자 안전, auth, billing, 데이터 정합성 위험 | 롤백 우선 평가 |
| SEV-2 | 주요 워크플로우 성능/품질 저하 | 범위 제한 hotfix + 강한 검증 |
| SEV-3 | 제한적 비핵심 회귀 | 계획된 보정 릴리스 |
심각도는 사고 시작 시 선언하고, 근거가 생길 때만 수정하세요.
최초 15분 프로토콜
- 사고 오너와 대행 오너 지정
- 영향 영역의 무관한 머지 동결
- 기준 근거 수집(실패 명령, 로그, 영향 반경)
- 레인별 next owner를 포함한 트래커 오픈
next owner가 없으면 연속성 있는 복구가 어렵습니다.
4-레인 복구 모델
경계를 명시한 병렬 실행 기준:
- Triage 레인: 심각도와 신뢰도 분류
- Mitigation 레인: feature-flag 비활성화 / hotfix / rollback 준비
- Verification 레인: 재현 가능한 재실행 + 안전성 점검
- Comms 레인: 내부/외부 이해관계자 업데이트 주기 운영
레인이 같은 파일을 만지면 즉시 단일 merge owner를 지정하세요.
가역 의사결정 사다리
가장 안전하고 되돌리기 쉬운 옵션부터 선택합니다.
- flag/config로 위험 경로 비활성화
- 범위 제한 패치 적용
- 마지막 안정 리비전으로 전체 롤백
선택한 안뿐 아니라 제외한 대안의 이유도 기록하세요.
근거 패킷 표준
각 주요 체크포인트마다 아래를 남기세요.
- 현재 심각도 + 오너 + 시각
- 영향 시스템/사용자
- 실행한 명령과 결과
- 잔여 리스크 문장
- 다음 체크포인트 시각 + 오너
이 패킷이 핸드오프의 단일 진실 원천입니다.
복구 종료 게이트
아래를 모두 만족할 때만 종료합니다.
- 완화 조치 반영 완료
- 최신 재실행 근거가 green
- 잔여 리스크 문서화
- 후속 하드닝 작업 오너/기한 지정
"안정적으로 보인다"는 종료 조건이 아닙니다.
사고 후 하드닝 루프
24시간 내에:
- 핵심 의사결정 타임라인 공개
- 가드레일 자동화 최소 1개 추가
- 원인 클래스 회귀 테스트 1개 추가
- 후속 작업 오너/기한 지정
사고는 비용이 큰 학습입니다. 통제 체계로 전환하세요.
고급 안티패턴
단일 영웅 레인
초반에는 빨라 보이지만, 핸드오프/피로 구간에서 취약해집니다.
커뮤니케이션 주기 없는 완화 조치
코드는 반영돼도 팀은 오래된 가정으로 움직입니다.
재실행 증거 없는 종료 선언
확신 표현은 명령 근거를 대체할 수 없습니다.
빠른 체크리스트
해결 선언 전:
- 심각도/오너십 기록
- 완화 경로 선택 근거 명시
- 최신 재실행 근거 첨부
- 하드닝 후속 작업 배정
Codex는 복구 속도를 높여주고, 이 플레이북은 복구를 통제 가능하게 만듭니다.
시나리오 라이브러리 (실전 압박 패턴)
이 라이브러리는 이상적인 경로가 아니라 실제 압박 상황에서 플레이북을 연습하기 위해 사용합니다.
시나리오 A — 배포 직후 인증 토큰 장애
- 신호: 특정 서비스에서 401/403 급증
- 리스크: 고객 신뢰 저하 + 지원 부하 급증
- 의사결정 분기: feature-flag 롤백 vs 제한적 hotfix
- 최소 근거: 실패 엔드포인트 목록, 첫 이상 배포 해시, 롤백 안전성 체크 결과
- 오너 핸드오프: 조사 오너 → 완화 오너 → 검증 오너
시나리오 B — 과금 상태 불일치
- 신호: 매출 이벤트와 거래 원장이 불일치
- 리스크: 재무/법적 노출
- 의사결정 분기: 즉시 쓰기 동결 vs 범위 제한 재처리
- 최소 근거: 불일치 표본 수, 영향 반경, 재처리 안전 경계
- 오너 핸드오프: 데이터 오너 + 사고 커맨더 이중 승인
시나리오 C — 권한 누수 경로 발견
- 신호: 저빈도지만 심각한 우회 접근 보고
- 리스크: 보안 사고 격상
- 의사결정 분기: 긴급 롤백/권한 회수 우선, 이후 패치
- 최소 근거: 최소 재현 케이스, 회수 완료 증명, 감사 로그 스냅샷
워룸 산출물 번들 (복붙 템플릿)
### Incident Command Snapshot
- Incident ID:
- Severity:
- Incident commander:
- Current phase: detection | containment | recovery | hardening
- Latest stable revision:
- Candidate mitigation path:
- Risk if we wait 30 minutes:
- Next checkpoint at:
- Next owner:### Checkpoint Decision Record
- Timestamp:
- Evidence reviewed:
- Decision: continue mitigation | rollback | escalate+pause
- Why this decision now:
- Rejected alternatives:
- Owner for execution:
- Owner for verification:에스컬레이션 메시지 템플릿
내부 엔지니어링 에스컬레이션
[INCIDENT][SEV-X] <short summary>
Impact: <users/systems>
Current decision: <path>
Immediate ask: <approval/resource>
Next update: <time>
Owner: <name>이해관계자 업데이트
Status: investigating/mitigating/recovered
Customer impact: <plain language>
Current mitigation: <plain language>
Known unknowns: <top 1-2>
Next committed update time: <time>종료 수용 기준 (하드 게이트)
아래를 모두 만족할 때만 incident response를 종료합니다.
- 완화 경로 실행 + 최신 명령 근거로 검증 완료
- 24시간 관찰 구간 동안 롤백 트리거/오너 문서화 유지
- 잔여 리스크를 명시적으로 기록
- 하드닝 백로그 오너/기한 배정
- 커뮤니케이션 타임라인 완결
하나라도 빠지면 상태는 active 유지입니다.
종료 직후 30분 리뷰
즉시 짧은 리뷰를 실행합니다.
- 가장 먼저 왔지만 무시된 신호는 무엇인가?
- 어떤 체크포인트 의사결정이 가장 오래 걸렸는가?
- 오너십이 모호해진 구간은 어디인가?
- 해결 시간을 가장 줄였을 가드레일 1개는 무엇인가?
- 추가/재정의해야 할 지표 1개는 무엇인가?
컨텍스트가 사라지기 전에 백로그 항목으로 전환하세요.
프로바이더별 사전 준비 체크
플레이북 시작 전 아래를 강제합니다.
- 리포지토리 상태: 마지막 안정 리비전 확인 + 롤백 경로 즉시 실행 가능 여부 확인
- 오너 그래프: commander/mitigation/verifier/comms 오너 명시
- 근거 채널: 체크포인트 기록을 남길 단일 문서/스레드 지정
최소 사전 체크 명령
git rev-parse --short HEAD
git log --oneline -n 5
# 서비스 헬스 체크 명령 추가결과를 첫 체크포인트에 첨부하세요.
의사결정 품질 가드레일
각 체크포인트 결정마다 3문장을 요구합니다.
- 가역성 문장 — 이 결정을 얼마나 빨리 되돌릴 수 있는가?
- 영향 반경 문장 — 이 결정이 틀렸을 때 무엇이 악화되는가?
- 검증 문장 — 무엇이 성공 신호인지 정확히 무엇으로 증명하는가?
하나라도 빠지면 고급 수준 의사결정으로 보지 않습니다.
핸드오프 수용 테스트
다음 오너로 넘기기 전에 확인:
- 범위 경계(포함/제외)가 명시됨
- 미해결 unknown 목록이 존재함
- 다음 체크포인트 시간이 커밋됨
- 즉시 롤백 트리거가 기록됨
이 테스트로 레인 간 컨텍스트 손실을 줄입니다.
60분 커맨드 타임라인 블루프린트
심각도가 불명확하지만 영향이 실제로 발생한 상황에서 이 타임라인을 사용합니다.
- T+00–10: 심각도 가설 확인, 고위험 머지 동결, commander+deputy 지정
- T+10–20: 완화 분기 옵션 수립, 롤백 준비성 확인
- T+20–35: 상충 경로 병행 없이 한 분기를 명확히 실행
- T+35–50: 검증 실행 + 사고 전 기준선과 비교
- T+50–60: 의사결정 노트 게시 + 다음 체크포인트 시간 확정
핵심은 단순 속도가 아니라 압박 상황에서의 동기화된 의사결정 품질입니다.
의존성 리스크 매트릭스
완화 선택 전에 영향 의존성을 먼저 분류하세요.
| 의존성 클래스 | 실패 증상 | 기본 대응 자세 |
|---|---|---|
| Auth/identity | 접근 거부 또는 우회 | rollback-first + audit 캡처 |
| Billing/ledger | 거래 불일치 | write freeze + 정합 경계 설정 |
| Messaging/queue | 지연/중복 처리 | 처리량 조절 + replay guard |
| Observability | 신호 누락/지연 | 보수적 롤백 임계값 적용 |
이 매트릭스가 과신 기반 단일 처방을 줄여줍니다.
충돌 의견 처리 프로토콜
오너 간 완화 권고가 충돌하면:
- 두 권고를 하나의 의사결정 기록에 함께 남김
- 가역성과 영향 반경을 각각 점수화
- 반증 근거가 없으면 더 가역적인 경로 우선
- 10분 이내 재평가 체크포인트 예약
의견 충돌은 정상이고, 비구조적 충돌이 위험합니다.
의사결정 신뢰도 계층
각 체크포인트 결정에 신뢰도 태그를 붙입니다.
- L1 (low): 근거 불완전, 가역 액션만 허용
- L2 (medium): 근거 일부 확보, 범위 제한 완화 허용
- L3 (high): 근거 일관, 확장 롤아웃/종료 허용
L1 상태로 incident response를 닫지 마세요.
복구 브랜치 전략 매트릭스
브랜치 전략을 의도적으로 선택하세요.
| 브랜치 유형 | 사용 시점 | 리스크 |
|---|---|---|
| Hotfix 브랜치 | 국소 코드 경로 회귀 | 숨은 부작용 |
| Rollback 브랜치 | 불확실성/안전 리스크가 넓을 때 | 기존 기술부채 재유입 |
| Containment 브랜치 | 조사 중 부분 완화 필요 | 임시 상태 장기화 |
단일 브랜치 오너 없이 3개 브랜치를 동시에 유지하지 마세요.
사고 종료 리뷰 패키지
최종 종료 전 하나의 패키지를 남깁니다.
- 타임라인(핵심 시각+결정)
- 완화 diff 요약
- 검증 명령 번들
- 잔여 리스크 레지스터
- 하드닝 백로그 링크
이 패키지로 신규 오너가 10분 내 상황을 이해할 수 있어야 합니다.
리더십 핸드오프 노트 템플릿
### Incident Leadership Note
- What happened:
- Why this decision path was chosen:
- Current confidence level (L1/L2/L3):
- What remains uncertain:
- What we need from leadership:
- Owner for next 24h watch:짧고 명시적인 리더십 노트가 의사결정 재논쟁을 줄입니다.