장애 보고서(포스트모템) 작성 규칙
원인을 사람이 아니라 시스템·절차로 쓰게 하고 재발 방지에 담당·기한을 붙이게 하는 규칙.
내 환경에 맞게 만들기
무엇을 하는 규칙인가
이 규칙을 쓰는 이유
장애 보고서를 AI에게 맡기면 대개 "담당자가 확인 없이 배포해서 발생했다"처럼 **사람의 행위**에서 원인이 멈춘다. 그 사람이 다음에 더 조심한다고 해서 같은 절차가 남아 있으면 같은 장애가 반복된다. 포스트모템의 목적은 책임을 묻는 게 아니라 **절차의 구멍을 찾는 것**이다. 아래 규칙은 원인이 사람에서 멈추지 않고 시스템까지 내려가게 만드는 것이 목적이다.
섹션 순서
이 순서를 바꾸지 않는다. 1. **무슨 일이 있었는지** (타임라인, 영향 범위) 2. **왜 일어났는지** (근본 원인 — 시스템·절차) 3. **재발 방지** (무엇을 바꾸는지, 담당·기한)
타임라인은 시각과 함께 쓴다
"빠르게 대응했다" 같은 문장은 검증할 수 없다. **감지·조치·복구 시각**을 남긴다. - 이렇게 쓰지 않는다: `빠르게 대응해서 큰 피해 없이 복구했다.` - 이렇게 쓴다: `14:02 알림 수신, 14:05 원인 확인, 14:20 롤백 완료. 영향 시간은 18분이다.`
영향 범위는 숫자로 쓴다
"일부 사용자"는 정보가 아니다. **몇 명, 몇 %, 어떤 기능**인지 쓴다. - 이렇게 쓰지 않는다: `일부 사용자가 로그인에 실패했다.` - 이렇게 쓴다: `전체 로그인 요청 중 32%가 18분간 500 오류를 받았다. 영향받은 계정은 약 4,200개다.`
원인은 사람이 아니라 절차로 쓴다
"누가 무엇을 잘못했다"에서 멈추지 않는다. **그 행위가 왜 문제 없이 통과됐는지**까지 쓴다. - 이렇게 쓰지 않는다: `담당자가 확인 없이 배포해서 발생했다.` - 이렇게 쓴다: `배포 전 스테이징 검증이 필수 단계로 강제되어 있지 않아, 검증 없이도 배포가 파이프라인을 통과했다.` 첫 번째 원인에서 멈추지 않는다. "왜 그 절차가 필수가 아니었는가"까지 한 단계 더 내려간다 (5 Whys와 같은 방식).
재발 방지는 담당과 기한이 있어야 한다
"모니터링을 강화하겠다" 같은 문장은 다음 장애 때 지켜졌는지 확인할 수 없다. **무엇을, 누가, 언제까지** 바꾸는지 쓴다. - 이렇게 쓰지 않는다: `모니터링을 강화하고 재발 방지에 힘쓰겠다.` - 이렇게 쓴다: `배포 파이프라인에 스테이징 헬스체크 게이트를 추가한다. 담당은 인프라팀, 다음 스프린트 내 적용한다.`
분량과 톤
- 사람 이름을 원인 문장에 넣지 않는다. 조치·의사결정 기록에는 이름이 필요할 수 있으나, "원인" 섹션에는 절차·시스템만 쓴다. - 평서체로 쓴다. 사과나 변명의 어조를 섞지 않는다. - 확실하지 않은 원인은 확실하지 않다고 쓴다. "아마 이것 때문일 것이다"는 "정확한 트리거는 로그로 재현하지 못했다. 재발 시 확인할 로그 위치를 남긴다"로 쓴다.
쓰기 전에 확인할 것
- 타임라인에 시각이 분 단위로 있는가 - 영향 범위가 숫자(분모 포함)로 쓰였는가 - 원인 문장에 사람 이름·직책이 아니라 절차·시스템이 주어인가 - 첫 번째 원인에서 멈추지 않고 한 단계 더 내려갔는가 - 재발 방지 항목마다 담당과 기한이 있는가 흔히 나오는 실패 예시는 `bad-examples.md`에 정리해 두었다. 처음 몇 번은 그것과 비교해 보면 빠르다.
원문 전문
넣기 전에 전부 읽어보실 수 있습니다. 이 파일은 AI에게 지시를 주는 문서입니다. 내용을 확인하고 넣으세요.
item.md
## 이 규칙을 쓰는 이유 장애 보고서를 AI에게 맡기면 대개 "담당자가 확인 없이 배포해서 발생했다"처럼 **사람의 행위**에서 원인이 멈춘다. 그 사람이 다음에 더 조심한다고 해서 같은 절차가 남아 있으면 같은 장애가 반복된다. 포스트모템의 목적은 책임을 묻는 게 아니라 **절차의 구멍을 찾는 것**이다. 아래 규칙은 원인이 사람에서 멈추지 않고 시스템까지 내려가게 만드는 것이 목적이다. ## 섹션 순서 이 순서를 바꾸지 않는다. 1. **무슨 일이 있었는지** (타임라인, 영향 범위) 2. **왜 일어났는지** (근본 원인 — 시스템·절차) 3. **재발 방지** (무엇을 바꾸는지, 담당·기한) ## 타임라인은 시각과 함께 쓴다 "빠르게 대응했다" 같은 문장은 검증할 수 없다. **감지·조치·복구 시각**을 남긴다. - 이렇게 쓰지 않는다: `빠르게 대응해서 큰 피해 없이 복구했다.` - 이렇게 쓴다: `14:02 알림 수신, 14:05 원인 확인, 14:20 롤백 완료. 영향 시간은 18분이다.` ## 영향 범위는 숫자로 쓴다 "일부 사용자"는 정보가 아니다. **몇 명, 몇 %, 어떤 기능**인지 쓴다. - 이렇게 쓰지 않는다: `일부 사용자가 로그인에 실패했다.` - 이렇게 쓴다: `전체 로그인 요청 중 32%가 18분간 500 오류를 받았다. 영향받은 계정은 약 4,200개다.` ## 원인은 사람이 아니라 절차로 쓴다 "누가 무엇을 잘못했다"에서 멈추지 않는다. **그 행위가 왜 문제 없이 통과됐는지**까지 쓴다. - 이렇게 쓰지 않는다: `담당자가 확인 없이 배포해서 발생했다.` - 이렇게 쓴다: `배포 전 스테이징 검증이 필수 단계로 강제되어 있지 않아, 검증 없이도 배포가 파이프라인을 통과했다.` 첫 번째 원인에서 멈추지 않는다. "왜 그 절차가 필수가 아니었는가"까지 한 단계 더 내려간다 (5 Whys와 같은 방식). ## 재발 방지는 담당과 기한이 있어야 한다 "모니터링을 강화하겠다" 같은 문장은 다음 장애 때 지켜졌는지 확인할 수 없다. **무엇을, 누가, 언제까지** 바꾸는지 쓴다. - 이렇게 쓰지 않는다: `모니터링을 강화하고 재발 방지에 힘쓰겠다.` - 이렇게 쓴다: `배포 파이프라인에 스테이징 헬스체크 게이트를 추가한다. 담당은 인프라팀, 다음 스프린트 내 적용한다.` ## 분량과 톤 - 사람 이름을 원인 문장에 넣지 않는다. 조치·의사결정 기록에는 이름이 필요할 수 있으나, "원인" 섹션에는 절차·시스템만 쓴다. - 평서체로 쓴다. 사과나 변명의 어조를 섞지 않는다. - 확실하지 않은 원인은 확실하지 않다고 쓴다. "아마 이것 때문일 것이다"는 "정확한 트리거는 로그로 재현하지 못했다. 재발 시 확인할 로그 위치를 남긴다"로 쓴다. ## 쓰기 전에 확인할 것 - 타임라인에 시각이 분 단위로 있는가 - 영향 범위가 숫자(분모 포함)로 쓰였는가 - 원인 문장에 사람 이름·직책이 아니라 절차·시스템이 주어인가 - 첫 번째 원인에서 멈추지 않고 한 단계 더 내려갔는가 - 재발 방지 항목마다 담당과 기한이 있는가 흔히 나오는 실패 예시는 `bad-examples.md`에 정리해 두었다. 처음 몇 번은 그것과 비교해 보면 빠르다.
references/bad-examples.md
# 흔한 실패 예시와 교정 장애 보고서에서 반복적으로 나오는 네 가지 패턴이다. 왼쪽이 자주 나오는 문장, 오른쪽이 교정이다. ## 1. 사람 탓으로 원인을 끝내는 문장 **자주 나오는 것** > 담당자가 확인 없이 배포해서 장애가 발생했습니다. 다음부터는 더 주의하겠습니다. 담당자가 바뀌어도, 다음 배포자가 똑같이 확인을 건너뛸 수 있는 구조가 그대로 남는다. **교정** > 배포 전 스테이징 검증이 필수 단계로 강제되어 있지 않아, 검증 없이도 배포가 파이프라인을 통과했다. 배포 파이프라인에 스테이징 헬스체크 게이트를 추가한다. 담당은 인프라팀, 다음 스프린트 내 적용한다. ## 2. 시각 없는 타임라인 **자주 나오는 것** > 장애를 인지하고 빠르게 원인을 파악해 신속히 복구했습니다. "빠르게", "신속히"가 몇 분을 뜻하는지 알 수 없어 다음 장애와 비교할 수 없다. **교정** > 14:02 알림 수신, 14:05 원인 확인(배포 롤백 대상 특정), 14:20 롤백 완료. 감지부터 복구까지 18분이 걸렸다. ## 3. 분모 없는 영향 범위 **자주 나오는 것** > 일부 사용자가 서비스 이용에 불편을 겪었습니다. "일부"가 10명인지 1만 명인지에 따라 대응 우선순위가 완전히 달라진다. **교정** > 전체 로그인 요청 중 32%가 18분간 500 오류를 받았다. 영향받은 계정은 약 4,200개다. ## 4. 첫 번째 원인에서 멈춘 분석 **자주 나오는 것** > 원인: 배포 스크립트에 오류가 있었음. 스크립트 오류 자체는 사실이지만, 왜 그 오류가 검증 없이 배포까지 갔는지가 빠져 있어 재발 방지로 이어지지 않는다. **교정** > 배포 스크립트에 환경변수 누락 오류가 있었다. 이 오류는 스테이징에서도 재현됐지만, 스테이징 결과를 확인하지 않아도 배포가 진행되는 구조여서 그대로 프로덕션까지 갔다. 배포 파이프라인에 스테이징 결과 확인을 필수 게이트로 추가한다. ## 확인 순서 작성 후 위에서부터 훑으며 네 가지를 본다. 1. 원인 문장의 주어가 사람인가 2. 타임라인에 시각이 없는가 3. 영향 범위에 분모가 없는가 4. 원인이 한 단계에서 멈췄는가 하나라도 걸리면 그 문장만 고친다. 전체를 다시 쓸 필요는 없다.