Claude Code에서 Opus 모델로 장시간 에이전트 작업이 끊길 때 해결법

트러블슈팅

Claude Code에서 Opus 모델로 장시간 에이전트 작업을 돌리다가 갑자기 끊긴 적 있으신가요? 컨텍스트 초과, 타임아웃, 토큰 폭증까지 — 원인별 해결법과 실패 시 복구 방법을 정리했습니다.

📌 3줄 요약

• 장시간 작업 실패의 3대 원인은 컨텍스트 윈도우 초과, 네트워크 타임아웃, 토큰 사용량 폭증입니다.
• 작업을 3~5단계로 분할하고, 중간중간 /compact 명령으로 컨텍스트를 압축하면 성공률이 크게 올라갑니다.
• 실패 시 claude --resume으로 세션을 이어가고, git stash로 중간 결과를 보존할 수 있습니다.

📑 목차

• 1. Opus 모델로 장시간 작업이 실패하는 이유
• 2. 타임아웃 설정과 모델 선택 확인하기
• 3. 작업을 쪼개서 안정적으로 실행하는 방법
• 4. 장시간 작업 실패 시 복구하는 방법

Opus 모델로 장시간 작업이 실패하는 이유

Claude Code에서 최신 Opus 모델을 선택하면, 복잡한 작업을 한 번에 맡길 수 있습니다. 코드 리팩토링이나 대규모 파일 분석처럼 시간이 오래 걸리는 에이전트(agent) 작업을 돌리는 경우가 대표적이에요. 실제로 Opus 모델은 다른 모델 대비 추론 능력이 뛰어나서, 여러 파일에 걸친 복잡한 의존성 분석이나 아키텍처 변경 같은 고난이도 작업에 자주 사용됩니다. 그래서 한 번 실행하면 수십 분씩 작업이 이어지는 경우도 흔하게 발생해요.

그런데 작업 도중 갑자기 멈추거나, context window exceeded 같은 오류가 뜨는 경우가 있습니다. 처음 겪으면 작업 결과가 전부 날아간 것 같아 당황스럽지만, 원인을 알면 대부분 예방하거나 복구할 수 있어요. 장시간 작업이 실패하는 원인은 크게 세 가지입니다.

1

컨텍스트 윈도우(AI가 한 번에 기억할 수 있는 텍스트 양) 초과

Opus 모델은 컨텍스트가 넉넉하지만, 대량의 파일을 읽으면서 누적되면 한계에 도달합니다. 특히 파일을 하나씩 열어 내용을 확인하는 과정에서 이전 대화 내용과 파일 내용이 계속 쌓이기 때문에, 작업 범위가 넓을수록 한계에 빨리 도달해요. 1M 컨텍스트를 지원하는 모델이라도, 수백 개 파일을 연속으로 읽으면 금방 가득 차게 됩니다.

2

네트워크 타임아웃

API 호출이 일정 시간을 초과하면 연결이 끊어집니다. 이건 Claude Code 자체의 문제가 아니라 인터넷 환경이나 API 서버 상태에 따라 발생하는 문제예요. 특히 VPN을 사용하거나 네트워크가 불안정한 환경에서는 타임아웃 빈도가 눈에 띄게 높아집니다. 장시간 작업일수록 중간에 네트워크 불안정 구간을 만날 확률이 올라가기 때문에, 안정적인 네트워크 환경을 확보하는 것도 중요해요.

3

토큰(token) 사용량 폭증

Opus 모델은 출력 품질이 높은 대신 토큰 소모가 빠르고, 비용도 급격히 늘어납니다. 같은 작업을 Sonnet 모델로 돌렸을 때보다 토큰 사용량이 2~3배 많은 경우도 있어요. 이 때문에 일일 사용량 한도에 도달하거나, 예상보다 훨씬 높은 요금이 청구될 수 있습니다.

 

💬 직접 써보니까, Opus 모델은 확실히 결과물의 정확도가 높지만 긴 작업에서는 중간에 끊기는 빈도도 높았습니다. 원인을 모르면 같은 작업을 반복 시도하게 되니, 아래 설정부터 확인하는 것을 권합니다. 아래에서 소개하는 방법들은 실제로 장시간 작업 성공률을 크게 높여주는 검증된 방법들이에요.

타임아웃 설정과 모델 선택 확인하기

장시간 작업을 안정적으로 돌리려면, 먼저 Claude Code의 모델 설정을 확인해야 합니다. 잘못된 모델이 선택되어 있으면, 컨텍스트 부족으로 작업이 일찍 끊길 수 있어요. 터미널에서 아래 명령으로 현재 사용 중인 모델을 확인할 수 있습니다.

claude config get model

Opus 모델이 설정되어 있다면, claude-opus-4-6 같은 모델 ID가 출력됩니다. 장시간 작업에는 반드시 1M 컨텍스트를 지원하는 모델을 선택해야 합니다. 기본 설정이 200K 컨텍스트 모델로 되어 있는 경우가 있는데, 이 상태에서 큰 작업을 돌리면 금방 한계에 부딪혀요.

모델을 명시적으로 지정하려면 아래처럼 실행합니다.

claude --model claude-opus-4-6

 

타임아웃 문제가 반복된다면, 작업을 더 작은 단위로 쪼개는 것이 현실적인 해결책입니다. 예를 들어 "이 프로젝트 전체를 리팩토링해줘" 대신 "src/utils 폴더만 리팩토링해줘"처럼 범위를 좁히는 방식이에요. 범위를 좁히면 읽어야 하는 파일 수가 줄어들어 컨텍스트 소모가 크게 감소합니다. 또한 각 단계별로 결과를 확인할 수 있어서, 문제가 생겼을 때 원인을 찾기도 훨씬 쉬워요.

💡 팁: /compact 명령도 장시간 작업의 핵심 도구입니다. 작업 중간에 /compact를 실행하면 대화 컨텍스트를 압축해서 여유 공간을 확보할 수 있습니다. 이 명령은 이전 대화 내용을 요약해서 토큰 수를 줄여주는 역할을 해요. 작업이 길어진다 싶으면 중간중간 /compact를 실행하는 습관을 들이면, 컨텍스트 초과 오류를 사전에 예방할 수 있습니다.

 

🔍 토큰 비용 참고: Opus 모델은 토큰당 비용이 다른 모델보다 높습니다. 장시간 작업 전에 claude --usage로 현재 사용량을 확인하는 습관을 들이면 요금 폭탄을 막을 수 있어요. 특히 Pro 플랜 사용자라면 일일 한도가 있기 때문에, 남은 용량을 확인하고 작업 범위를 조절하는 것이 좋습니다.

작업을 쪼개서 안정적으로 실행하는 방법

장시간 에이전트 작업을 한 번에 던지면, 실패 확률이 높아집니다. 이 문제를 해결하는 가장 확실한 방법은 작업 분할이에요. 작업을 쪼개면 실패 시 손실이 줄어들고, 중간 결과를 확인하면서 방향을 수정할 수도 있습니다.

큰 작업은 3~5단계로 나눠서 각각 별도의 프롬프트(prompt)로 실행하는 것이 안전합니다. 단계별로 결과를 확인하면서 진행하면, 실패 시 처음부터 다시 시작할 필요가 없어요. 각 단계가 끝날 때마다 파일이 저장되기 때문에, 중간에 끊겨도 이전 단계의 결과물은 그대로 남아 있습니다.

실전 예시를 들어보겠습니다. 100개 파일을 리팩토링한다고 가정하겠습니다.

1

먼저 "src/models 디렉토리의 파일 목록을 분석해줘"로 구조를 파악합니다.

2

다음으로 "src/models/user.py만 리팩토링해줘"처럼 파일 단위로 진행합니다.

3

결과를 확인하고, 문제가 없으면 다음 파일로 넘어갑니다.

이렇게 하면 한 파일에서 문제가 생겨도 다른 파일에는 영향이 없어요. 디렉토리 단위로 묶어서 진행하는 것도 좋은 전략인데, 관련 파일끼리 함께 수정하면 일관성을 유지하기 쉽습니다.

 

🔍 서브에이전트 활용: Claude Code의 서브에이전트(subagent) 기능을 활용하는 방법도 있습니다. Agent 도구를 사용하면 메인 대화의 컨텍스트를 소모하지 않고 독립적인 작업을 위임할 수 있어요. 서브에이전트는 별도의 컨텍스트 윈도우에서 동작하기 때문에, 메인 세션이 가벼운 상태를 유지할 수 있습니다. 여러 서브에이전트를 병렬로 실행하면 전체 작업 시간도 단축할 수 있어요.

💡 팁: CLAUDE.md 파일에 작업 단위를 미리 정의해두면 더 편리합니다. "이 프로젝트에서 리팩토링은 디렉토리 단위로 진행한다"같은 규칙을 적어두면, 매번 지시를 반복하지 않아도 됩니다. 프로젝트 루트에 CLAUDE.md 파일을 만들고 작업 규칙을 기록해두면, Claude Code가 매 세션마다 이 파일을 자동으로 읽어요.

💬 작업을 쪼개면 속도는 조금 느려지지만, 중간에 날아가는 일이 사라집니다. 특히 Opus 모델처럼 토큰 비용이 높은 모델에서는 실패 1회가 곧 비용 손실이므로, 분할 실행이 결국 더 경제적이에요. 처음에는 번거롭게 느껴질 수 있지만, 한두 번 실패를 경험하고 나면 분할 실행의 가치를 체감하게 됩니다.

장시간 작업 실패 시 복구하는 방법

설정을 잘 맞춰도 장시간 작업 중 끊기는 경우는 발생합니다. 완벽한 예방은 없기 때문에, 실패 후 빠르게 복구하는 방법을 알아두는 것이 중요해요. 다행히 Claude Code는 세션 복구 기능을 제공하고, Git과 함께 사용하면 작업 손실을 최소화할 수 있습니다.

가장 먼저 할 일은 claude --resume 명령으로 마지막 세션을 이어서 시작하는 것입니다. Claude Code는 이전 대화 내용을 기억하고 있어서, 끊긴 지점부터 다시 진행할 수 있어요. 이 기능 덕분에 작업이 끊겨도 처음부터 다시 설명할 필요가 없습니다.

claude --resume

세션 목록에서 특정 대화를 선택해서 이어갈 수도 있습니다. claude --resume 실행 후 목록에서 원하는 세션을 고르면 됩니다. 최근 세션이 목록 상단에 표시되기 때문에, 방금 끊긴 세션을 쉽게 찾을 수 있어요. 세션을 이어가면 이전 대화에서 했던 파일 분석이나 중간 결과가 그대로 유지됩니다.

⚠️ 주의: 만약 컨텍스트 초과로 실패했다면, 복구 전에 /compact 명령을 먼저 실행하는 것이 좋습니다. 압축 없이 바로 이어가면 같은 오류가 반복될 가능성이 높아요. 세션을 재개한 직후 /compact를 실행해서 컨텍스트를 정리하고, 그 다음에 남은 작업을 이어가는 순서가 가장 안전합니다.

 

작업 중간 결과물이 파일로 저장되어 있는지도 확인해야 합니다. Claude Code는 작업 도중에도 파일을 저장하므로, git diff로 변경된 부분을 확인할 수 있어요.

git diff --stat

이 명령을 실행하면 어떤 파일이 얼마나 변경되었는지 한눈에 볼 수 있습니다. 변경된 파일이 있다면 작업이 부분적으로 완료된 것이므로, 남은 파일만 이어서 처리하면 돼요.

최악의 경우, 세션 복구가 안 되면 git stash로 현재 변경사항을 임시 저장하고 새 세션에서 이어가면 됩니다. 아래 명령으로 변경사항을 안전하게 보관할 수 있어요.

git stash save "opus-장시간-작업-중간결과"

나중에 git stash pop 명령으로 저장해둔 변경사항을 다시 꺼내올 수 있습니다. 이 방법을 쓰면 새 세션에서 깨끗한 상태로 시작하되, 이전 작업 결과는 잃지 않아요.

장시간 작업에서 가장 중요한 건 "실패해도 복구할 수 있다"는 안전망을 미리 만들어두는 것입니다. Git을 쓰고 있다면 작업 전에 브랜치를 하나 만들어두는 것만으로도 충분해요. git checkout -b opus-refactor 같은 명령으로 작업 전용 브랜치를 만들면, 문제가 생겨도 메인 브랜치에는 영향이 없습니다. 이 한 가지 습관만으로도 장시간 작업의 불안감을 크게 줄일 수 있어요.

✍️ 마치며

Opus 모델의 장시간 작업 실패는 대부분 컨텍스트 초과, 네트워크 타임아웃, 토큰 폭증 중 하나가 원인입니다. 1M 컨텍스트 모델을 선택하고, 작업을 3~5단계로 분할하며, 중간중간 /compact로 컨텍스트를 정리하세요. 실패하더라도 claude --resume과 git stash로 빠르게 복구할 수 있으니, 안전망을 갖춘 상태에서 Opus의 강력한 추론 능력을 최대한 활용해 보세요.

#ClaudeCode #Opus모델 #장시간작업 #컨텍스트윈도우 #에이전트작업 #트러블슈팅 #AI코딩