시작 전
작동과 운영은 다른 약속입니다
좋은 입력으로 한 번 성공한 것과 나쁜 날에도 어디서 멈췄는지 알고 다시 시작하는 것은 다릅니다.
- 로그: 시작·판정·실패를 나중에 읽고 설명할 수 있는 기록
- 재시도: 일시적 실패를 정한 횟수와 간격으로 다시 시도하는 규칙
- 중복 방지: 같은 실행이 두 번 와도 결과가 한 번만 남는 설계
- 복구 문서: 멈춘 위치에서 누가 무엇을 확인하고 재개하는 절차
01 · 관찰
로그를 많이가 아니라 판정 가능하게 남기기
모든 내용을 저장하는 로그는 읽히지 않습니다. 다음 사람이 상태를 설명할 최소 필드를 정합니다.
- 01
시작 로그에 입력과 실행 ID 남기기
왜 하나요? 어떤 실행을 따라가야 하는지 알게 합니다.
할 일 시작 시각·입력 식별자·버전·실행 ID를 기록합니다.
복사해서 써도 되는 요청이 파이프라인을 따라갈 시작 로그의 최소 필드를 제안해줘. 민감정보는 기록하지 마.
정상이라면 같은 입력의 실행을 구분할 수 있습니다.
- 02
판정 로그에 기준과 이유 남기기
왜 하나요? 왜 다음 단계로 갔는지 알게 합니다.
할 일 판정 기준·실제 값·다음 단계·판정자를 기록합니다.
정상이라면 “성공”이 아니라 어떤 기준을 통과했는지 보입니다.
- 03
실패 로그에 위치와 재개 정보 남기기
왜 하나요? 처음부터 다시 돌리는 비용을 줄입니다.
할 일 멈춘 관절·오류 종류·재시도 횟수·인계 이유를 기록합니다.
정상이라면 로그만 읽어도 어디서 무엇을 고칠지 말할 수 있습니다.
02 · 재시도와 중복
다시 시도할 때 더 큰 사고를 만들지 않기
모든 실패를 무한히 다시 돌리지 않습니다. 일시적·영구적 오류와 중복 쓰기를 구분합니다.
- 01
일시적·영구적 실패 나누기
왜 하나요? 재시도해도 낫지 않는 오류를 반복하지 않습니다.
할 일 네트워크 지연·제한과 잘못된 입력·권한 거부를 구분합니다.
정상이라면 실패 종류마다 재시도와 사람 인계가 정해집니다.
- 02
횟수·간격·소진 후 인계 정하기
왜 하나요? 재시도가 끝없이 이어지지 않게 합니다.
할 일 최대 횟수·대기 간격·마지막 실패를 받을 사람을 적습니다.
복사해서 써도 되는 요청실패 종류의 재시도 규칙을 횟수·간격·포기 기준·인계로 써줘.
정상이라면 언제 멈추고 누구에게 넘기는지 보입니다.
- 03
같은 실행을 두 번 넣기
왜 하나요? 수동 재실행과 스케줄 겹침을 안전하게 다룹니다.
할 일 실행 ID나 업무 키로 이미 처리됐는지 확인하고 같은 입력을 두 번 실행합니다.
정상이라면 외부 결과가 두 건 생기지 않습니다.
03 · 복구와 품질
문서로 재개하고 Hook/Eval으로 반복 확인하기
복구 절차는 머릿속 요령이 아니라 동료가 실행할 수 있는 순서여야 합니다.
- 01
멈춘 위치에서 재개하는 세 단계 쓰기
왜 하나요? 처음부터 다시 돌리는 일을 막습니다.
할 일 상태 확인 → 원인 해결/승인 → 멈춘 단계 재실행 순서로 적습니다.
정상이라면 문서만 보고 누가 무엇을 확인할지 알 수 있습니다.
- 02
명세와 품질을 따로 점검하기
왜 하나요? 약속과 운영 가능성을 섞지 않습니다.
할 일 행동 문장대로 결과가 나왔는지와 복구 가능한지를 별도 질문으로 만듭니다.
정상이라면 기능 통과와 운영 보강의 부족한 부분이 나뉩니다.
- 03
실패 시나리오를 다시 주입하기
왜 하나요? 보강이 실제로 작동하는지 확인합니다.
할 일 로그·재시도·중복 방지·복구 문서를 재실행합니다.
복사해서 써도 되는 요청완료 기준을 PASS/FAIL로 점검할 Hook/Eval 질문 5개를 만들어줘.
정상이라면 문서와 자동 점검이 같은 기준을 묻습니다.
마지막 확인
runbook.md
운영자가 실패를 읽고 멈춘 곳에서 다시 시작할 수 있도록 적습니다.
# 운영·복구 문서
## 로그 읽는 법
- 실행 ID: [위치]
- 시작: [입력·버전]
- 판정: [기준·결과]
- 실패: [위치·이유·재개 정보]
## 재시도 규칙
- 일시적 실패: [횟수·간격]
- 영구적 실패: [즉시 인계]
## 중복 방지
- 업무 키/실행 ID: [값]
- 이미 처리됨: [건너뜀/같은 결과]
- 확인 방법: [두 번 실행한 기록]
## 복구
1. [멈춘 위치와 마지막 로그 확인]
2. [원인 해결 또는 승인]
3. [멈춘 단계부터 재개하고 결과 확인]
## Hook/Eval
- [반복해서 물을 완료 기준]완료 체크
이 7가지가 보이면 오늘의 목표를 달성한 것입니다
- 정상 작동과 운영 가능성을 구분한다.
- 시작·판정·실패 로그 필드를 정했다.
- 일시적·영구적 실패를 나눴다.
- 재시도 횟수·간격·인계가 있다.
- 두 번 실행해 중복 결과를 확인했다.
- 복구 절차를 문서화하고 실행했다.
- 명세와 품질을 Hook/Eval 질문으로 나눴다.
다음 단계
다음 주에는 동료가 이 흐름을 재현하도록 전달합니다
W10에서 처음 보는 입력·설계 이유·한계를 Coach Kit으로 만들고 Teach-back합니다.
막힐 때
자주 나오는 질문
로그를 많이 남기면 운영이 쉬워지나요?
양보다 판정 가능성이 중요합니다. 시작·판정·실패 이유와 재개 정보가 읽혀야 합니다.
실패하면 무조건 재시도하면 안 되나요?
잘못된 입력이나 권한 거부는 다시 해도 낫지 않습니다. 일시적·영구적 원인을 나눠야 합니다.
중복 방지는 나중에 붙여도 되나요?
외부에 쓰는 흐름이라면 첫 연결부터 확인하세요. 재시도·스케줄 겹침·사람 재실행으로 중복은 흔합니다.
Hook/Eval은 어려운 도구인가요?
처음에는 명세의 행동 문장을 반복 질문으로 만드는 것부터 시작하면 됩니다. 입력·기대·판정이 있으면 체크리스트도 Eval입니다.