15장 현장 트러블슈팅 런북

같은 메일 초안이 여러 개 생긴다

트리거 횟수보다 멱등성 키 저장을 먼저 본다. 키가 요청마다 무작위이면 중복 제거가 되지 않는다. 큐 삽입과 키 기록이 원자적인지, 외부 API에 같은 키를 보냈는지 확인한다. 중복을 삭제하기 전 관련 외부 ID를 감사 기록에 남긴다.

webhook이 가끔 누락된다

공급자 전달 로그, 서명 검증 실패, 응답 시간, 재시도 정책을 확인한다. 처리 전에 빠르게 수신 기록을 영속화했는지 본다. 주기적 reconciliation 작업으로 외부 시스템의 최근 변경과 내부 상태를 비교한다.

승인했는데 ARTIFACT_CHANGED다

승인 후 브리프 상태, 견적, 범위 중 하나가 바뀌었다. JSON 직렬화 순서가 불안정하거나 계산에 현재 시각이 섞였을 수도 있다. 승인 스냅샷과 현재 스냅샷의 비밀값을 제거한 diff를 보여 주고 다시 승인한다. 검증을 우회하지 않는다.

429가 계속 발생한다

동시성, 분당 요청, 토큰 사용량을 본다. 재시도가 서로 동시에 몰리지 않게 jitter를 넣고 큐 소비 속도를 낮춘다. 배치 가능한 작업은 묶되 한 요청이 너무 커지지 않게 한다. 할당량 문제인지 계정·모델 제한인지 공식 콘솔에서 확인한다.

모델 결과가 갑자기 달라졌다

모델 ID, 프롬프트, 스키마, 온도와 입력 전처리 버전을 기록했는지 확인한다. 골든셋으로 회귀를 측정하고 기준을 넘지 못하면 이전 버전 또는 mock·수동 모드로 전환한다. 한 사례의 문구 차이를 품질 저하로 단정하지 않는다.

작업이 processing에 멈췄다

작업 lease와 heartbeat 만료를 확인한다. 워커가 죽었을 때 다른 워커가 안전하게 인계하도록 멱등성을 보장한다. 오래된 작업을 무조건 재실행하지 말고 외부 시스템에 이미 성공했는지 외부 ID로 조회한다.

담당자가 휴가라 승인이 멈췄다

개인 계정 의존을 없애고 역할 기반 대리 승인과 기간을 둔다. 고위험 승인은 2인 승인으로 올릴 수 있다. 대리자가 볼 수 있는 범위와 감사 기록을 제한한다. 승인 SLA가 지나면 자동 실행하지 말고 에스컬레이션한다.

잘못된 대상에게 실제 발송됐다

즉시 해당 자동화를 중지하고 자격 증명을 필요한 경우 폐기한다. 발송 범위와 노출 데이터를 확인하고 조직의 사고 대응·법적 절차를 따른다. 숨기거나 로그를 지우지 않는다. 원인을 대상 선택, 승인 UI, 권한, 멱등성, 테스트 데이터 혼입으로 나누고 재발 방지 테스트를 추가한다.

부록 A 자동화 설계 카드

업무 이름:
촉발 사건 / 시간표:
입력과 데이터 등급:
결정론적 규칙:
AI가 맡을 초안:
사람이 승인할 내용:
허용된 외부 행동:
멱등성 키:
재시도 가능한 오류:
보상 또는 수동 복구:
감사 기록과 보존 기간:
성공·품질·안전·비용 지표:
회로 차단 조건:

부록 B 30일 도입 순서

1주차에는 실제 업무 열 건을 관찰하고 데이터와 예외를 분류한다. 2주차에는 fake connector와 fixture로 초안·dry-run을 만든다. 3주차에는 승인 영수증, 멱등성, 실패 큐, 대시보드를 완성하고 장애 훈련을 한다. 4주차에는 한 팀의 저위험 업무만 제한 실행하며 매일 품질 표본과 보류함을 리뷰한다. 지표가 기준을 넘지 못하면 범위를 넓히지 않는다.

부록 C 완주 프로젝트: 교육 행사 운영 자동화

가상의 모두의 데이터 교실은 매달 오프라인 워크숍을 연다. 참가 신청, 좌석 확인, 대기자 이동, 전날 안내, 출석 뒤 자료 공유가 반복된다. 개인정보와 외부 발송이 있어 단순 연결보다 정책이 중요하다.

업무 계약

신청이 접수되면 필수값과 동의를 검증한다. 좌석은 결정론적 규칙으로 배정하고 정원을 넘으면 대기 상태로 둔다. AI는 참가자의 자유 서술 질문을 주제별로 묶어 강사에게 초안을 제공한다. 건강 정보나 접근성 요청은 일반 요약에서 제외하고 권한 있는 담당자에게 별도로 전달한다. 안내 메일은 사람 승인 뒤 초안으로 만들며 예제에서는 실제 발송하지 않는다.

Trigger: registration.validated
Rules: capacity, duplicate email hash, consent, cancellation deadline
AI draft: anonymized question themes
Human gate: recipient segment, schedule, venue, final message
Actions: create_mail_draft, create_calendar_hold
Never automate: accessibility accommodation decision, refund dispute

fixture 다섯 건

정상 신청, 같은 이메일 중복 신청, 정원 마지막 좌석, 정원 초과 대기, 접근성 요청 포함 신청을 만든다. 이메일은 .invalid, 전화는 가상 형식을 사용한다. 각 건에 예상 상태와 자동화가 멈출 조건을 적는다. 테스트는 구현 뒤가 아니라 fixture와 함께 작성한다.

dry-run 결과 명세

미리보기에는 대상 그룹 수, 제외된 신청 수와 이유, 제목, 본문, 일정, 정책 버전을 보여 준다. 개인 이메일 전체를 한 화면에 노출하지 않는다. 샘플 몇 건과 합계로 검토하고 필요할 때 권한 있는 사용자가 세부 목록을 연다. 승인자는 제외 규칙과 대기자 상태를 확인한다.

장애 주입

메일 API 429, 캘린더 500, webhook 세 번 재전송, 승인 만료, 승인 뒤 장소 변경을 차례로 주입한다. 429는 backoff 후 성공하고, 500은 제한 횟수 뒤 실패 큐로 가며, 중복 webhook은 같은 멱등성 키로 한 건만 남아야 한다. 장소 변경은 기존 승인을 무효화한다.

완료 증거

정상 흐름 테스트, 각 장애의 분류와 복구, 실제 발송 0건, 민감 데이터가 없는 로그, 운영자가 읽을 런북을 제출한다. 자동화 시간 절감과 함께 잘못된 대상 0건, 승인 없는 실행 0건을 기록한다.

부록 D 구현용 데이터 모델

관계형 저장소를 쓴다면 briefs, proposals, approval_receipts, automation_jobs, automation_attempts, audit_events를 분리할 수 있다. 현재 상태만 덮어쓰지 않고 중요한 결정의 스냅샷을 남긴다.

create table automation_jobs (
  id text primary key,
  brief_id text not null,
  action_type text not null,
  approval_receipt_id text not null,
  idempotency_key text not null unique,
  status text not null,
  available_at timestamptz not null,
  attempt_count integer not null default 0,
  locked_until timestamptz,
  external_id text,
  last_error_code text,
  created_at timestamptz not null
);

워커는 available_at <= now이고 잠기지 않은 작업을 제한 개수 가져와 짧은 lease를 잡는다. 외부 호출 전 정책과 영수증을 다시 검증한다. 성공하면 외부 ID와 완료 시각을, 실패하면 분류된 코드와 다음 시각을 저장한다. 본문이나 토큰을 last_error에 통째로 넣지 않는다.

감사 이벤트는 actor_type, actor_id, event_type, subject_id, policy_version, artifact_hash, occurred_at을 가진다. AI 모델은 actor가 아니라 사용된 도구로 기록하고, 책임 있는 사람과 시스템 경로를 별도로 남긴다.

부록 E 커넥터 출시 체크

이메일

발신 도메인 인증과 회신 주소를 확인한다. 개발 수신자를 allowlist로 제한하고, 운영 전환은 별도 설정과 2인 검토로 한다. 수신 거부와 반송을 처리한다. 대량 발송은 개인 BCC로 흉내 내지 말고 적합한 서비스를 쓴다. 초안 생성과 발송 권한을 가능하면 분리한다.

캘린더

시간대, 종일 일정, 중복, 초대 메일 발생 여부를 확인한다. 외부 이벤트 ID를 저장한다. 일정 변경은 새 이벤트를 무작정 만들지 않고 기존 ID를 갱신한다. 취소 시 참가자에게 어떤 알림이 나가는지 미리보기한다.

문서 저장소

폴더와 공유 권한을 템플릿으로 고정한다. 링크를 아는 모든 사람 공개를 기본값으로 쓰지 않는다. 파일명에 개인정보를 넣지 않고, 같은 문서의 버전을 추적한다. AI가 생성한 문서는 초안 표시와 검토자를 가진다.

메신저

개인 DM보다 운영 채널과 스레드를 사용한다. 토큰이 볼 수 있는 채널을 제한한다. 긴 개인정보와 비밀값을 알림 본문에 넣지 않는다. 알림 폭주를 막기 위해 집계와 quiet hours를 둔다. 실패 알림이 같은 장애로 무한 반복되지 않게 한다.

부록 F 운영 당번이 보는 한 장

장애를 발견하면 먼저 외부 쓰기를 멈추되 접수 데이터는 보존한다. 최근 배포, 정책·모델 버전, 커넥터 상태, 큐 지연, 실패 코드 상위를 확인한다. 영향받은 작업의 시작과 끝 ID를 고정하고 개인정보 없이 상황을 공유한다.

복구 선택은 네 가지다. 안전한 자동 재시도, 사람 확인 뒤 재시도, 보상 작업, 수동 완료다. 어떤 경우에도 감사 기록과 멱등성 키를 지우고 다시 돌리지 않는다. 복구 후 골든셋과 회귀 테스트를 통과시키고 제한된 속도로 큐를 연다.

사후 검토는 개인의 실수보다 방어선이 왜 잡지 못했는지를 본다. 탐지 시간, 중단 시간, 사용자 영향, 데이터 노출, 복구 경로를 기록한다. 재발 방지는 “주의한다”가 아니라 테스트, 권한 축소, 승인 UI, 정책, 알림 중 하나의 구체적 변경이어야 한다.

부록 G 자동화 변경 요청서

자동화 수정은 코드 티켓 하나로 끝내지 않는다. 바꾸는 업무 규칙, 영향받는 입력과 커넥터, 이전 정책으로 진행 중인 작업, 권한 변화, 되돌리기 계획을 적는다. 모델이나 프롬프트 변경이면 골든셋 비교와 수동 표본 결과를 붙인다.

승인자는 변경된 diff와 위해 시나리오를 확인한다. 스테이징에서는 실제 자격 증명 대신 제한 계정과 allowlist를 쓴다. 배포 뒤 처음 100건 또는 24시간은 속도를 제한하고 품질·실패 큐를 집중 관찰한다. 문제가 생기면 새 작업 수신을 멈출지, 큐 소비만 멈출지, 전체를 수동으로 전환할지 사전에 정한다.

변경이 끝나면 정책 버전, 적용 시각, 검증 증거, 남은 위험을 운영 기록에 남긴다. “작은 문구 수정”도 수신자나 승인 의미를 바꾸면 정책 변경이다. 반대로 내부 리팩터링이 외부 계약을 바꾸지 않았다면 불필요한 재승인을 요구하지 않는다.

참고와 저작권

본문의 코드, 도형, 화면, 조직과 사례는 교육용으로 새로 제작했다. 모든 이메일은 예약된 .invalid 도메인을 사용한다. 외부 제품명은 각 소유자의 상표이며, 실제 연결 전 최신 API 약관·개인정보 처리 조건·조직 보안 정책을 확인해야 한다.

공식 자료: OpenAI Tools, Structured Outputs, NIST AI RMF, OWASP Top 10 for LLM Applications, CloudEvents Specification, RFC 2606 예약 도메인