How I Auto-Resume a Rate-Limited Claude Code Session with PROGRESS.md and Retries

개요

Claude Code 세션에서 발생할 수 있는 속도 제한(rate limit)으로 인한 작업 중단을 자동 재개하기 위해 PROGRESS.md 파일을 활용하고 20줄의 쉘 스크립트를 사용하여 해결하는 방법을 설명합니다.

주요 내용

* 문제점: Claude Code를 사용한 장기 작업 시 속도 제한에 걸리면 프로세스가 종료되고 작업 진행 상황 기록이 사라져 처음부터 다시 시작해야 하는 번거로움이 발생합니다.
* 해결 방안: PROGRESS.md 파일을 "인계 티켓"으로 사용하여 작업 경계를 기록하고, --continue 옵션과 함께 재시도하는 방식을 도입합니다.
* PROGRESS.md 활용: Claude에게 첫 프롬프트에 "각 작업 경계에서 PROGRESS.md를 업데이트하라"고 지시하여 완료된 단계, 남은 단계, 메모 등을 파일에 지속적으로 기록하게 합니다.
* 재개 스크립트 (resume-on-ratelimit.sh): 20줄의 쉘 스크립트로 작성되며, Claude 명령의 비정상 종료 코드(non-zero exit code)를 속도 제한 감지로 활용합니다.
* set -euo pipefail 및 MAX_RETRIES, WAIT_MINUTES 환경 변수를 사용하여 재시도 횟수와 대기 시간을 설정합니다.
* --dangerously-skip-permissions 옵션을 사용하여 자동화된 작업 중 도구 사용 시 발생하는 권한 확인 프롬프트를 건너뜁니다.
* osascript를 이용한 macOS 시스템 알림 기능으로 작업 상태(재개, 완료, 최대 재시도 초과)를 사용자에게 알립니다.
* launchd와의 연동: autopilot.sh와 함께 macOS의 launchd를 사용하여 지정된 시간에 스크립트를 자동으로 실행하도록 설정할 수 있습니다. autopilot.sh는 자율적인 개선 루프에 사용되며, resume-on-ratelimit.sh는 수동으로 시작된 장기 작업이 완료될 때까지 지속시키는 데 사용됩니다.
* 주의 사항:
* --continue 옵션 없이 재실행하면 이전 컨텍스트가 사라지므로 항상 함께 사용해야 합니다.
* PROGRESS.md 업데이트 지시가 없으면 재개 프롬프트가 제대로 작동하지 않습니다.
* 비정상 종료 코드가 속도 제한 외의 오류(구문 오류 등)일 수도 있으므로 최대 재시도 초과 시 수동 확인이 필요합니다.
* set -euo pipefail과 || true를 함께 사용할 때 EXIT 변수 캡처 시점에 주의해야 합니다.
* macOS가 절전 모드일 때 launchd 작업은 건너뛸 수 있지만, resume-on-ratelimit.sh의 sleep 루프는 시스템 복귀 후 재개됩니다.

시사점

이 스크립트는 Claude Code와 같은 AI 모델을 활용한 장기 작업 자동화의 효율성을 크게 높여주며, 반복적인 수동 개입 없이도 안정적인 작업 수행을 가능하게 합니다. PROGRESS.md를 통한 상태 관리와 재시도 메커니즘은 복잡한 AI 워크플로우의 견고성을 확보하는 데 유용합니다.