AI 코딩

Claude Code 작업이 멈췄을 때: 재시도를 중단하고 상태를 복구하는 시점

멈춘 Claude Code 작업을 복구하는 실무 프로토콜입니다. 오류를 분류하고 루프를 중단하며 상태를 기록한 다음, 범위를 좁힌 검증으로 다시 시작합니다.

BT

BetterToken

편집팀
4 분 분량

횟수 제한 없는 재시도는 Claude Code를 사용할 때 불필요한 토큰 소비, 컨텍스트 품질 저하, 손상된 코드 변경을 일으키는 대표적 원인입니다. 에이전트가 같은 테스트에서 계속 실패하거나, 환경 변수가 없거나, 동일한 파일을 순환해서 편집한다면 새로운 외부 신호 없이 다시 시도해도 원인은 해결되지 않습니다. 세션을 막다른 길로 더 밀어 넣을 뿐입니다.

올바른 전략은 루프를 일찍 끊고, API와 코드베이스 수준에서 장애를 분류하며, 실제 저장소 상태를 기록한 뒤 결정적인 검증 단계로 작업을 복구하는 것입니다.

1. 장애 유형 분류: 재시도가 소용없는 경우

모든 오류가 명령을 한 번 더 실행한다고 해결되지는 않습니다. 명확한 진단이 없으면 일시적인 API 제한과 에이전트의 논리 루프를 혼동하기 쉽습니다.

장애 유형징후재시도 동작권장 조치
일시적 네트워크 장애 / 429일시적인 API 타임아웃 또는 요청 제한지수 백오프와 함께 유효할 수 있음(최대 3회)기다린 뒤 외부 API 호출만 다시 시도
논리적 막다른 길에이전트가 같은 2개 파일을 반복해서 수정무의미: 잘못된 가정을 반복함`Ctrl+C`로 세션을 중단하고 Git diff 점검
권한 / 환경 오류`Permission denied`, `.env` 누락무의미: 환경은 저절로 바뀌지 않음권한 또는 로컬 설정을 명시적으로 수정
아키텍처 불일치잘못된 스키마 때문에 통합 테스트 실패무의미: 계획을 다시 세워야 함변경을 되돌리고 작업 경계를 다시 정리

원인을 추측하며 토큰을 소모하지 않으려면 외부 API 문제와 코드 결함을 분리해야 합니다. BetterToken Claude Code 워크플로에서는 Dashboard에서 HTTP 상태, 모델, 응답 시간, 입력·출력·캐시 토큰의 정확한 소비량을 확인할 수 있습니다. 게이트웨이 타임아웃이나 429라면 횟수를 제한한 재시도가 타당할 수 있습니다. 반대로 API가 계속 200 OK를 반환하는데 에이전트만 순환 편집한다면 즉시 세션을 종료하세요.

2. 우선순위 복구 프로토콜

에이전트가 진전 없이 2~3번 연속으로 시도했다면 다음 순서로 진행합니다.

```mermaid
graph TD
A[에이전트가 오류 루프에 빠짐] --> B[1단계: Ctrl+C로 즉시 중단]
B --> C[2단계: Git 상태와 diff 감사]
C --> D[3단계: Recovery Card 저장]
D --> E[4단계: 검증이 있는 깨끗한 세션 시작]
```

단계별 조치:

  1. 1단계: 세션 종료. `Ctrl+C`로 실행을 중단합니다. 긴 변명이나 불필요한 출력 생성에 컨텍스트를 더 쓰게 하지 마세요.
  2. 2단계: 상태 검사 및 정리. `git status --short`로 수정된 파일을 확인합니다. 에이전트가 깨진 코드를 만들었다면 영향을 받은 파일만 되돌립니다. `git checkout -- <file>`
  3. 3단계: 근본 원인 분류. Dashboard의 API 지표와 에이전트 실행 로그를 비교하여 네트워크 장애와 논리 오류를 구분합니다.
  4. 4단계: 구조화된 Recovery Card 저장.

3. 구조화된 Recovery Card

새 복구 세션을 열기 전에 작업의 정확한 상태를 기록합니다.

```markdown

Recovery Card: 가져오기 서비스 장애

  • 원래 목표: `auth/service.ts`에 이메일 검증을 추가한다.
  • 실제 진행 상황: 정규식은 추가했지만 단위 테스트 `auth_test.go`가 실패했다.
  • 근본 원인: 에이전트가 공개 인터페이스 대신 private 메서드를 mock하려 했다.
  • Git 상태: 브랜치는 `fix/auth-email`, `auth/service.ts`의 유효한 diff는 유지한다.
  • 깨끗한 세션의 다음 조치: 공개 인터페이스 `AuthClient`를 이용해 단위 테스트를 리팩터링한다.
    ```

[!IMPORTANT]
시크릿을 기록하지 마세요: Recovery Card에 API 키, 액세스 토큰, 원본 메모리 덤프를 절대 넣지 마세요. 엔드포인트 설정과 키 관리는 BetterToken Claude Code 문서에서 확인하세요.

4. 되돌릴 수 있는 복구와 검증

안전하게 실행을 재개하려면 다음을 따르세요.

  1. 깨끗한 컨텍스트 창으로 새 Claude Code 세션을 시작합니다.
  2. 에이전트에는 작업 목표와 Recovery Card의 “다음 조치” 필드만 전달합니다.
  3. 범위를 좁힌 검사를 요구합니다. `npm test -- tests/auth.test.ts`
  4. 대상 테스트가 통과했는지(`Passed`) 확인한 뒤, 최종 diff를 `git diff --check`로 검토합니다.

이 프로토콜은 통제 불가능한 에이전트 루프를 관리 가능한 점검 지점으로 바꾸고, 코드베이스와 토큰 예산을 보호합니다.

결제와 잔액 충전

API 사용을 위한 결제와 충전은 본인의 BetterToken 계정에서 관리합니다. BetterToken은 사용량에 따라 과금되는 모델 API 접근 서비스이며, 유료로 충전한 잔액은 매월 자동 소멸하지 않습니다. 사용 가능한 결제 수단, 최소 금액, 수수료, 환율, 처리 시간은 변할 수 있으므로 결제 시점의 계정 화면을 확인하세요.

가격과 비용 관리

모델 제공 여부와 구체적인 가격은 동적으로 바뀌는 정보입니다. 비용을 결정하기 전에는 오래된 글의 숫자를 재사용하지 말고 BetterToken 가격 페이지를 확인하세요. 테스트 호출 후 Dashboard에서 모델, 상태, 입력·출력·캐시 토큰과 해당 소비량을 대조할 수 있습니다.

LLM 워크플로를 최적화할 준비가 되셨나요?

하나의 API로 모델을 연결하고 키와 AI 비용을 관리하세요.