Claude Code 장시간 작업 안정화: partial output, retry, background agent를 운영하는 방법

요약: Claude Code의 최근 릴리스는 장시간 코딩 작업에서 자주 보이던 조용한 실패를 줄이는 방향으로 업데이트됐습니다. 실무에서는 기능 자체보다 partial output을 어떻게 저장하고, retry를 어디까지 허용하며, background agent 결과를 어떻게 검증할지가 더 중요합니다.

문제는 모델 성능보다 운영 상태다

코딩 에이전트를 실제 레포에 붙이면 사용자는 처음에 모델의 코드 작성 능력을 봅니다. 하지만 며칠만 지나면 관심사는 바뀝니다. “긴 작업이 중간에 끊기면 어떻게 되나?”, “subagent가 실패했는데 성공처럼 보이면 어떻게 잡나?”, “partial result를 살릴 수 있나?”, “background 작업이 같은 명령을 다시 실행하지 않나?” 같은 운영 문제가 더 중요해집니다.

Claude Code 최신 릴리스는 이 지점을 많이 다룹니다. streaming response가 중간 server error로 끊겨도 partial output을 보존하고 incomplete-response notice를 붙입니다. rate limit이나 server error로 잘린 subagent는 partial work를 부모에게 돌려줍니다. subagent가 usage limit 같은 API 오류를 성공 결과로 보고하던 문제도 고쳤습니다. background agent daemon, SSH cold-start, memory pressure, retry watchdog 관련 수정도 포함됐습니다.

이제 팀이 해야 할 일은 이 기능들을 ‘자동으로 좋아졌다’고 넘기는 것이 아니라 운영 규칙으로 흡수하는 것입니다.

partial output을 결과물로 다루는 기준

partial output은 버리기 아깝지만 그대로 믿기도 어렵습니다. 예를 들어 에이전트가 리팩터링 도중 API error로 끊겼고, 변경 파일 목록과 원인 분석 일부를 남겼다고 합시다. 이 내용은 다음 시도에 도움이 됩니다. 하지만 테스트가 끝나지 않았다면 완료 결과로 취급하면 안 됩니다.

따라서 partial output은 세 단계로 분류하는 것이 좋습니다.

• 참고 가능: 원인 분석, 조사 로그, 실패한 접근, 후보 파일 목록
• 이어서 작업 가능: 적용 전 패치 초안, 수정 계획, 테스트 명령 목록
• 완료 불가: 검증되지 않은 코드 변경, 실행되지 않은 migration, 배포 관련 명령

팀 운영에서는 partial output을 별도 섹션으로 남겨야 합니다. “완료” 메시지와 섞이면 리뷰어가 착각합니다. 특히 자동 PR이나 자동 커밋이 켜져 있다면 partial 상태에서 push하지 않도록 완료 조건을 엄격히 둬야 합니다.

retry는 오류 유형별로 다르게 설정하라

릴리스 노트에는 transient server rate-limit error를 자동 backoff로 재시도하고, CLAUDE_CODE_RETRY_WATCHDOG가 non-capacity transient error의 기본 retry count를 크게 올린다는 내용이 있습니다. 장시간 작업에서는 좋은 변화입니다. 일시적 API 오류 때문에 40분짜리 분석을 날리는 것보다 재시도가 낫습니다.

하지만 retry가 항상 답은 아닙니다. 오류를 네 종류로 나눠야 합니다.

첫째, transient infrastructure error입니다. 네트워크 단절, 5xx, 일시적 429가 여기에 해당합니다. 자동 재시도 가치가 큽니다.

둘째, usage limit 또는 quota error입니다. 구독/조직 한도 문제라면 계속 재시도해도 해결되지 않을 수 있습니다. 일정 시간 대기 또는 사용자 알림이 필요합니다.

셋째, deterministic command failure입니다. 테스트 실패, 타입 에러, lint 실패는 재시도보다 수정이 필요합니다. 같은 명령을 반복하면 시간만 낭비됩니다.

넷째, permission/security error입니다. 권한이 없는 파일, 차단된 네트워크, 승인되지 않은 브라우저 상태 변경은 자동 재시도 대상이 아닙니다. 사람 승인이나 설정 변경이 필요합니다.

background agent 결과 검증 루틴

background agent가 기본화되면 병렬성은 좋아지지만, 결과 검증 부담도 늘어납니다. 특히 여러 subagent가 같은 파일을 수정하면 충돌이 생길 수 있습니다. 한 subagent는 테스트를 고치고, 다른 subagent는 리팩터링을 하다가 서로의 변경을 덮을 수 있습니다.

운영 루틴은 다음처럼 잡는 것이 안전합니다.

1. 작업 시작 시 agent별 범위를 명시합니다. 예: “인증 관련 테스트만”, “문서만”, “성능 병목 조사만”.
2. 각 agent는 변경 파일 목록, 실행한 명령, 실패한 명령, 남은 리스크를 보고합니다.
3. 부모 세션은 결과를 합칠 때 diff 충돌과 중복 수정을 확인합니다.
4. 최종 완료 전 최소 검증 명령을 한 번 더 실행합니다.
5. PR을 만들 경우 agent별 요약이 아니라 통합 changelog를 작성합니다.

Claude Code가 partial work와 API error를 더 잘 전달해도, 결과 병합 책임은 여전히 운영자에게 있습니다.

브라우저와 shell 권한을 나누는 이유

최근 Claude Code는 Claude in Chrome GA, read-only browser tool permission 개선, state-changing browser tool call prompt 수정 등 브라우저 자동화 관련 변화도 포함했습니다. 브라우저는 shell보다 더 위험할 수 있습니다. 클릭 한 번으로 결제, 삭제, 배포, 계정 변경이 일어날 수 있기 때문입니다.

따라서 권한은 최소 네 단계로 나누는 것이 좋습니다.

• read-only 파일/브라우저 관찰
• 로컬 파일 수정
• 외부 네트워크 접근
• 상태 변경 작업: 배포, 결제, 삭제, 운영 데이터 변경

Plan mode에서 read-only browser_batch는 자동 허용하더라도, 상태 변경 browser tool call은 반드시 승인 UI를 거치게 해야 합니다. 로컬 개발 서버에서 QA하는 것과 운영 관리자 페이지에서 버튼을 누르는 것은 같은 “브라우저 사용”이 아닙니다.

로그에 남겨야 할 최소 정보

장시간 에이전트 작업은 재현성이 낮아질 수 있으므로 로그가 중요합니다. 최소한 다음 정보는 남겨야 합니다.

• 작업 시작 프롬프트와 범위
• 사용 모델과 모드
• 생성된 subagent 목록과 각 목적
• 실행한 shell/browser 명령 요약
• partial output 여부
• retry 발생 횟수와 오류 유형
• 최종 변경 파일과 테스트 결과
• 사람이 승인한 작업과 승인 시각

이 정보가 있어야 다음 날 같은 오류가 반복될 때 원인을 찾을 수 있습니다. 특히 “에이전트가 뭔가 했는데 왜 이렇게 됐지?”라는 질문을 줄이려면, 결과보다 과정 로그가 더 중요합니다.

실행 체크리스트

• partial output을 완료 결과와 분리해서 표시합니다. 완료, 참고, 이어서 작업 가능 상태를 구분합니다.
• retry 대상 오류를 transient, quota, deterministic failure, permission error로 분류합니다.
• background agent마다 작업 범위와 변경 가능 파일을 제한합니다.
• 여러 agent 결과를 병합하기 전 diff 충돌과 중복 수정을 확인합니다.
• 최종 완료 전 테스트, 타입체크, lint, 빌드 중 최소 하나는 반드시 실행합니다.
• browser tool은 read-only와 state-changing을 분리하고, 운영 화면에서는 별도 승인을 요구합니다.
• 자동 PR 생성은 허용 브랜치와 저장소를 제한합니다.
• 에이전트 작업 로그에는 retry, partial output, 승인 내역을 반드시 포함합니다.