Claude Code 6월 29일 릴리즈에서 streaming idle watchdog이 모든 provider에 기본 활성화됐습니다. 응답 스트림이 5분 동안 이벤트를 내지 않으면 작업을 abort하고 retry하는 기능입니다. 환경변수 CLAUDE_ENABLE_STREAM_WATCHDOG=0으로 비활성화할 수 있지만, 대부분의 팀은 끄기보다 안전하게 쓰는 방향을 잡는 게 맞습니다.
AI 코딩 도구를 오래 써 본 팀이라면 “멈춘 것 같은데 죽은 건 아닌 상태”를 겪어 봤을 겁니다. 터미널은 살아 있고, 프로세스도 종료되지 않았고, UI도 완전히 실패로 표시하지 않습니다. 그런데 10분, 20분이 지나도 결과가 없습니다. 사람은 기다리다 결국 Ctrl+C를 누르고, 에이전트는 어디까지 했는지 애매한 상태로 남습니다.
스트리밍 기반 도구에서 가장 위험한 상태는 실패가 아닙니다. 실패는 재시도하거나 알림을 보낼 수 있습니다. 진짜 문제는 상태가 멈춘 채로 남는 것입니다. CI 잡, 원격 세션, 백그라운드 에이전트, 자동 리뷰처럼 사람이 계속 보고 있지 않은 작업에서는 무한 대기가 전체 파이프라인을 막습니다.
watchdog은 이 문제를 줄입니다. 5분 동안 이벤트가 없으면 해당 스트림을 비정상으로 보고 끊은 뒤 다시 시도합니다. 이 기준은 완벽하지 않지만 운영에서는 충분히 유용합니다. “영원히 기다리는 것”보다 “정해진 기준으로 실패 처리하고 다음 상태로 넘어가는 것”이 낫기 때문입니다.
다만 retry는 항상 안전하지 않습니다. 그래서 이 기능을 이해 없이 켜 둔 채로 외부 side effect가 있는 작업을 맡기면 다른 사고가 날 수 있습니다.
가장 위험한 유형은 외부 상태를 바꾸는 작업입니다. 배포, 데이터베이스 migration, 결제 처리, 이메일 발송, Git push, PR 생성, SaaS 설정 변경 같은 작업입니다. 스트림이 5분 동안 조용했다고 해서 작업이 실행되지 않은 것은 아닙니다. 모델 응답은 멈췄지만 도구 호출은 이미 끝났을 수 있습니다.
예를 들어 에이전트가 배포 명령을 실행했고, 배포는 성공했지만 이후 로그 요약 단계에서 스트림이 멈췄다고 가정해 봅시다. watchdog이 retry하면 에이전트가 같은 배포를 다시 시도할 수 있습니다. 배포는 보통 재실행 가능하지만, migration이나 결제성 작업은 그렇지 않습니다.
두 번째 위험은 긴 명령입니다. 대규모 테스트, 빌드, 모델 평가, 데이터 변환처럼 5분 이상 출력이 없는 명령은 watchdog 입장에서는 idle처럼 보일 수 있습니다. 명령 자체가 조용한 타입이라면 주기적으로 progress output을 내게 해야 합니다.
watchdog을 안전하게 쓰려면 도구 호출이 가능하면 idempotent해야 합니다. 같은 요청이 두 번 실행돼도 결과가 한 번 실행과 같아야 한다는 뜻입니다.
API 호출에는 idempotency key를 붙입니다. 배포 작업에는 release ID나 commit SHA를 기준으로 이미 실행된 작업인지 확인합니다. 데이터 변경 작업은 dry-run과 apply 단계를 분리합니다. 이메일이나 알림은 발송 로그를 먼저 확인한 뒤 중복 발송을 막습니다.
Git 작업도 마찬가지입니다. PR 생성은 브랜치명과 제목 기준으로 기존 PR을 찾은 뒤 없을 때만 만들어야 합니다. 커밋은 같은 diff인지 확인하고, 이미 커밋된 변경이면 새 커밋을 만들지 않아야 합니다. 이런 장치가 있어야 retry가 운영 편의가 됩니다.
watchdog 기준이 5분이라면, 긴 명령은 1~2분마다 진행 상태를 출력하는 편이 좋습니다. 테스트 러너나 빌드 도구가 자체 progress를 내면 괜찮지만, 그렇지 않다면 wrapper를 둬야 합니다.
예를 들어 데이터 변환 스크립트는 1,000건마다 처리 수를 출력하고, 대규모 lint는 패키지 단위로 시작과 종료를 출력하면 됩니다. “아무 로그도 안 내는 20분짜리 명령”은 자동화 환경에서 좋지 않습니다. 사람도 불안하고 watchdog도 구분하기 어렵습니다.
Claude Code에게 장기 작업을 맡길 때 프롬프트에 “5분 이상 출력 없는 명령은 피하고, 긴 작업은 진행 로그가 나오는 명령으로 실행하라”고 명시하는 것도 좋습니다. 에이전트가 알아서 해줄 거라고 기대하기보다 작업 규칙으로 주는 편이 안정적입니다.
재시도가 일어났을 때 가장 먼저 해야 할 일은 같은 작업을 다시 실행하는 게 아닙니다. 현재 상태를 확인하는 것입니다. 배포라면 현재 배포 버전, migration이라면 schema version, PR이라면 기존 PR 존재 여부, 파일 수정이라면 git diff를 먼저 봐야 합니다.
에이전트 프롬프트에 이 규칙을 넣을 수 있습니다. “이전 시도가 중단되었거나 재시도된 경우, 명령을 재실행하기 전에 상태 확인부터 수행하라.” 간단하지만 효과가 큽니다.
또한 작업 종료 조건을 명확히 해야 합니다. “테스트 통과”인지, “PR 생성”인지, “보고서 파일 저장”인지 모호하면 retry 후 에이전트가 불필요한 일을 더 할 수 있습니다. 자동화에서 모호함은 비용입니다.
대부분은 켜 두는 게 낫지만 예외는 있습니다. 모델 provider나 네트워크 특성상 정상 요청도 5분 이상 이벤트가 없는 일이 잦고, 작업이 읽기 전용이며 중단 비용이 큰 경우입니다. 예를 들어 매우 긴 단일 응답을 생성하는 내부 provider가 있고 스트리밍 이벤트를 늦게 보내는 구조라면 일시적으로 CLAUDE_ENABLE_STREAM_WATCHDOG=0을 고려할 수 있습니다.
하지만 끄기 전에 먼저 provider 설정, 프롬프트 크기, 출력 길이, 네트워크 프록시, 터미널 로그를 확인해야 합니다. watchdog을 끄는 것은 증상을 덮는 조치일 수 있습니다. 장기적으로는 provider가 주기적 이벤트를 보내거나, 작업을 작은 단위로 쪼개는 편이 더 낫습니다.
CLAUDE_ENABLE_STREAM_WATCHDOG=0을 쓰고, 이유와 범위를 문서화합니다.스트리밍 watchdog은 작은 안정성 기능처럼 보이지만, AI 에이전트를 운영 자동화에 넣는 팀에는 필수 안전장치입니다. 핵심은 재시도를 막는 게 아니라, 재시도돼도 망가지지 않는 작업 구조를 만드는 것입니다.