Claude Code의 Request timed out, Bash tool 대기 종료, terminal 연결 해제, session 재개는 모두 “장시간 작업이 멈췄다”처럼 보입니다. 그러나 각각 다른 lifecycle이며 남아 있는 state도 다릅니다.
복구할 때 첫 질문은 “다시 할까?”가 아니라 “어느 시계가 끝났고 어떤 부작용이 이미 생겼나?”입니다. Request, command, conversation, file rollback, durable project state를 나눈 뒤에야 retry, resume, rewind, respawn 중 안전한 선택을 할 수 있습니다.
요청 타임아웃과 Bash 타임아웃은 다르다
현재 공식 오류 참조는 API_TIMEOUT_MS 기본값을 600000ms, 즉 model request당 10분으로 설명합니다. 별도의 환경 변수 참조는 Bash tool의 BASH_DEFAULT_TIMEOUT_MS를 120000ms, BASH_MAX_TIMEOUT_MS를 600000ms로 둡니다.
요청 타임아웃은 deadline 안에 model response를 받지 못했다는 뜻입니다. Bash 타임아웃은 tool invocation의 대기 한도가 끝났다는 뜻이며, model request나 모든 child process의 상태를 보장하지 않습니다. 전체 시간, 비용, 위험을 제한하는 job deadline은 사용자가 별도로 정해야 합니다.
공식 문서는 높은 부하나 매우 큰 response가 Request timed out을 일으킬 수 있다고 설명합니다. 단순히 시간을 늘리기보다 작업을 작은 unit으로 나누면 복구 지점이 더 분명해집니다. 느린 network나 proxy가 확인된 병목일 때만 API_TIMEOUT_MS 조정을 고려하세요. 더 긴 시간은 checkpoint나 멱등성을 만들지 않습니다.
Claude Code는 server error, overload, request timeout, 일시적 429, connection drop을 기본 최대 10회 exponential backoff로 자동 retry합니다. 최종 오류가 보일 때는 이 재시도가 이미 소진된 상태입니다. 바깥에 무제한 loop를 추가하면 비용과 side effect만 중복될 수 있습니다.
무엇을 닫아도 계속되어야 하는가
| 필요한 결과 | 적합한 출발점 | 반드시 알아야 할 경계 |
|---|---|---|
| 완료 조건까지 Claude가 다음 turn을 계속 시작 | /goal | 현재 session 기반이며 evaluator는 대화에 나온 증거만 판단 |
| test, build, dev server가 대화를 막지 않음 | Background Bash, Ctrl+B, /tasks | Claude Code를 종료하면 command가 정리됨 |
| 현재 terminal과 local Claude session을 분리 | Agent view background session | 컴퓨터, network, usage, permission에는 계속 의존 |
| 나중에 같은 conversation을 다시 엶 | --continue, --resume | transcript 복구이지 process 복구가 아님 |
| 열린 session에서 주기적으로 상태 확인 | /loop, cron tools | session-scoped이고 만료됨 |
| 컴퓨터를 꺼도 실행 | Remote session, Routines, CI | cloud 환경은 로컬 미커밋 상태를 자동으로 가지지 않음 |
Interactive mode 공식 문서는 background Bash가 Claude Code 종료 시 자동으로 cleanup된다고 명시합니다. 즉 Ctrl+B는 “긴 command 동안 다른 대화를 계속한다”는 문제를 해결하지만 “terminal과 앱을 닫고도 process를 유지한다”는 문제는 해결하지 않습니다.
/goal에는 검증 가능한 종료 조건을 준다
“마이그레이션을 끝까지 해줘”는 끝의 정의가 부족합니다. 장시간 작업에서는 목표, verifier, 변경 금지 범위, 시간·turn 상한을 함께 줍니다.
text/goal auth module을 새 async API로 이전한다. npm test -- auth와 npm run typecheck가 exit 0이고 legacyAuthClient call site가 0개임을 보여라. database schema는 변경하지 않는다. 15 turns 또는 2시간 안에 끝나지 않으면 멈추고 blocker를 보고한다.
/goal 문서에 따르면 각 turn 뒤 별도의 작은 model이 조건 충족 여부를 판단하고, 미충족이면 다음 turn을 시작합니다. 이 evaluator는 command나 file을 직접 확인하지 않습니다. Claude가 실제 test와 search를 실행하고 결과를 transcript에 남겨야 완료 판정에 근거가 생깁니다.
Active goal은 같은 session을 --continue 또는 --resume하면 복원됩니다. 다만 재개 시 timer, turn count, token baseline은 초기화됩니다. 이는 중단 뒤 다시 추진할 수 있다는 뜻이지, 쉬는 동안에도 작업했다는 뜻이 아닙니다.
개발 서버와 긴 테스트는 Background Bash로 분리한다
Dev server, test suite, build, Docker처럼 현재 conversation 안에서 오래 도는 command는 Background Bash가 잘 맞습니다. Bash tool 실행 중 Ctrl+B를 누르거나 Claude에게 background 실행을 요청합니다. tmux에서는 첫 Ctrl+B가 prefix이므로 두 번 눌러야 합니다.
Claude Code는 task ID를 반환하고 output을 file에 기록합니다. /tasks 또는 /bashes에서 확인하거나 attach, stop할 수 있습니다. 서버를 실행하면서 UI를 수정하거나, 전체 test가 도는 동안 다른 failure를 분석하는 식의 병렬성이 가능합니다.
현재 공식 contract에는 output이 5GB를 넘으면 task가 종료된다는 제한도 있습니다. 로그가 많은 command는 verbosity를 낮추고 rotation하거나, 장기 service라면 전용 process manager에 맡기는 편이 낫습니다. Claude Code를 종료할 계획이라면 shell detachment 옵션을 계속 쌓기보다 더 명확한 runner로 이동해야 합니다.
Terminal을 떠나야 한다면 background session을 사용한다
Agent view 문서는 background session을 terminal child가 아니라 사용자별 supervisor가 관리하는 별도 Claude Code process로 설명합니다.
bashclaude agents claude attach <id> claude logs <id> claude stop <id> claude respawn <id>
작업 중이거나 입력을 기다리거나 terminal이 attach된 session은 process를 유지합니다. 완료된 session이 attach 없이 약 한 시간 idle 상태면 supervisor가 resource 확보를 위해 process를 멈출 수 있지만, transcript와 state는 disk에 남고 다음 attach 때 다시 시작됩니다.
이 방식은 특정 terminal 창에 묶이지 않게 해 줍니다. 그러나 실행 위치는 여전히 local computer입니다. Sleep, shutdown, network 문제, usage 소진, 인증 실패, permission prompt는 작업을 멈출 수 있습니다. 노트북을 꺼도 계속되어야 하는 요구에는 local background session이 맞지 않습니다.
체크포인트는 로컬 되돌리기이지 트랜잭션이 아니다
Claude Code는 user prompt마다 checkpoint를 만듭니다. Esc를 두 번 누르거나 /rewind를 실행하면 code, conversation, 둘 다 복원하거나 선택한 범위의 context를 요약할 수 있습니다. Checkpointing 공식 문서에 따르면 checkpoint는 재개한 session에도 남습니다.
하지만 rewind가 추적하는 것은 Claude file editing tool이 만든 변경입니다. Bash command, 수동 또는 외부 변경, 다른 concurrent session의 수정은 되돌리지 못합니다. Database rollback도 아니고 Git 대체물도 아닙니다. Migration, code generation, external API가 섞인 작업은 git diff, generated file, database, 외부 state를 따로 확인해야 합니다.
장시간 작업의 checkpoint를 두 층으로 두면 명확합니다. 내장 prompt checkpoint는 conversation과 직접 edit에 쓰고, project ledger는 완료 unit, verification, 되돌릴 수 없는 side effect를 기록합니다. Ledger의 milestone은 검증이 성공한 뒤에만 완료로 바꿉니다.
/loop와 durable scheduler를 구분한다
/loop와 scheduled tasks는 열린 session에서 deployment, PR, build를 주기적으로 확인할 때 유용합니다.
text/loop 10m integration job을 확인하고, 실패했다면 마지막 failing step과 다음에 시도할 최소 action을 기록한다
Scheduled prompt는 Claude가 현재 turn을 마친 뒤 실행됩니다. 반복 task는 생성 후 7일이 지나면 만료되고, 놓친 interval을 모두 따라잡아 실행하지 않습니다. Resume은 만료되지 않은 schedule을 복원할 수 있지만 Background Bash와 monitor task는 복원하지 않습니다.
더 긴 지속성이 필요하면 다음처럼 runner를 바꿉니다.
- Desktop scheduled task는 local file에 접근하지만 computer가 켜져 있어야 합니다.
- Claude Code Desktop의 Remote session은 Anthropic cloud에서 실행되어 app이나 computer를 닫아도 계속됩니다.
- Routines는 schedule, API call, 지원 event마다 새로운 cloud session을 만들고 결과를 검토할 수 있게 남깁니다.
- CI는 repository event, cron, log, approval gate를 code와 함께 관리할 때 적합합니다.
Cloud로 옮긴 session은 노트북의 uncommitted file, local service, secret, MCP를 자동으로 상속하지 않습니다. 필요한 branch, environment, input artifact를 명시해야 합니다. Run이 끝난 것과 작업이 성공한 것도 별도로 검증합니다.
Model context 밖에 복구 상태를 남긴다
Session 관리 문서에 따르면 CLI conversation은 계속 저장되며 claude --continue, claude --resume, /resume으로 돌아갈 수 있습니다. 그래도 transcript 하나에 모든 state를 두지 않는 편이 안전합니다.
md목표와 금지 범위 - 무엇을 바꾸고 무엇은 건드리지 않는지 완료된 milestone - file, verification command, 결과 현재 blocker - exact error, 최소 재현, 이미 배제한 가설 다음 action - 한 가지 구체적 단계와 중단 조건
Anthropic의 장시간 scientific computing 사례도 progress file, test oracle, 명시적 규칙, Git checkpoint를 사용합니다. 이는 HPC 맥락의 예시이지 모든 project에 필요한 product contract는 아닙니다. 하지만 진행 상태를 model context에만 두지 말아야 한다는 원칙은 일반적입니다.
병렬 작업은 worktree와 file ownership을 분리합니다. 여러 worker가 실제로 필요하면 Claude Code Agent Teams 가이드가 인접한 선택을 설명하지만, 각 lane의 완료 조건은 여전히 따로 필요합니다.
Permission을 없애기 전에 권한 범위를 줄인다
장시간 작업이 밤새 permission prompt에서 기다릴 수 있습니다. Permission mode 문서는 감독 수준을 나눕니다. acceptEdits는 편집 흐름을 줄이고, dontAsk는 pre-approved tool만 실행합니다. Auto mode는 별도 classifier로 action을 확인하며 prompt를 줄이지만 research preview이고 version, plan, model, provider, admin 조건이 바뀔 수 있습니다.
bypassPermissions는 permission layer를 건너뛰므로 Anthropic은 격리 container 또는 VM에만 사용하도록 안내합니다. Unattended task일수록 file system, network, credentials, branch, budget을 좁히고 deployment, purchase, secret 전송, destructive action 앞에서 멈추게 해야 합니다.
Usage limit이 작업을 막았다면 goal, diff, 마지막 verification, 다음 action부터 저장한 뒤 Claude Code 사용량 제한 진단으로 이동합니다.
재시도 전에 이미 일어난 부작용을 대조한다
Response가 실패했다고 turn 안의 action이 rollback되지는 않습니다. 다시 실행하기 전에 목표 file이 이미 있는지, test나 build artefact가 남았는지, process가 예상 owner 아래 살아 있는지, external API가 요청을 받았는지 확인합니다.
가능하면 작업 unit을 멱등하게 만드세요. 원하는 state가 이미 있으면 감지해 skip하고, 외부 system이 operation key를 지원하면 안정적인 key로 중복을 막습니다. 멱등성이 불가능하면 verify, compensate, retry 중 무엇을 선택할지 판단할 evidence를 기록합니다.
API error로 turn이 끝나면 StopFailure hook이 실행됩니다. Hooks 참조는 이 hook의 output과 exit code가 무시된다고 설명합니다. Logging과 알림에는 적합하지만 failed turn을 자동 재개하지는 않습니다. 사용자 recovery loop에도 retry budget과 reconciliation rule이 필요합니다.
재개할 때는 “계속해”만 보내지 않습니다. Task file, git status, 실제 process 존재 여부, 마지막 log, 최소 verification 순으로 확인합니다. 현재 어떤 runtime이 작업을 소유하는지, durable state가 어디 있는지, 어떤 evidence가 완료를 증명하는지 알 수 있다면 terminal이나 session이 멈춰도 추측 없이 복구할 수 있습니다.
