최종 업데이트: 2026년 5월 12일.

리팩터링(refactor)을 진행하며 세 번째 파일을 파고들고 있는데, Claude Code가 "컨텍스트 부족(context low)" 경고를 띄웁니다. 혹은 더 최악의 상황으로, 대화 내용을 조용히 요약해버리는 바람에 20분 전에 내린 결정을 잊어버리고, 이미 고쳐놓은 부분을 다시 "수정"하고 있는 상황을 마주할 수도 있습니다. 이런 일은 항상 잘못된 타이밍에 발생합니다. 아래에서는 왜 이런 일이 발생하는지, 그리고 가장 빠르게 컨텍스트 여유 공간을 확보할 수 있는 순서대로 어떻게 이를 멈출 수 있는지 설명합니다.

왜 이런 일이 계속 발생하는가

Claude Code는 세션의 모든 것, 즉 모든 메시지, 읽은 모든 파일, 모든 명령의 출력값을 한곳에 모아둡니다. 대부분의 모델에서 이는 대략 200,000 토큰(tokens) 정도의 창(window)을 가집니다. 무엇이 이 창을 채우는지 확인하기 전까지는 엄청나게 커 보일 것입니다.

긴 대화는 명백한 원인입니다. 모든 주고받은 내용이 그 안에 머뭅니다. 대화가 많은 2시간 동안의 세션은 엄청난 양의 토큰을 소모합니다.

대용량 파일 읽기는 교묘한 원인입니다. Claude에게 "인증 모듈(auth module)을 살펴봐 줘"라고 요청하면, 2,000줄짜리 파일을 통째로 가져올 수 있습니다. 그러면 그 파일은 세션이 끝날 때까지 컨텍스트(context)를 차지하게 됩니다.

그다음은 도구 출력(tool output)입니다. 전체 npm run build 로그, 거대한 git diff, 실수로 실행한 node_modules의 ls 결과 — 이 모든 것이 있는 그대로 컨텍스트에 담깁니다. MCP 서버는 여기서 가장 심각한 원인이 될 수 있습니다. 500개의 행을 반환하는 데이터베이스 서버나, API 레퍼런스 페이지 전체를 넘겨주는 문서 서버는 단 한 번의 호출만으로도 여러분의 토큰 예산을 바닥낼 수 있습니다. (아직 MCP 서버를 설정하지 않았다면, MCP 서버의 작동 방식에 대한 가이드에서 실제 역할을 확인할 수 있습니다.)

마지막으로, "혹시 몰라서" 붙여넣는 로그들입니다. 여러분이 던져 넣은 400줄짜리 스택 트레이스(stack trace)? 그 400줄은 이제 Claude가 계속 짊어지고 가야 할 짐이 됩니다.

컨텍스트 창이 거의 가득 차게 되면, Claude Code는 자동 압축(auto-compacts)을 수행합니다. 즉, 지금까지 일어난 일들을 요약하고 원본 히스토리(raw history) 대신 그 요약본을 가지고 계속 진행하는 방식입니다. 세션은 유지되지만, 이것이 핵심입니다. 하지만 요약 과정에서 무언가 유실됩니다. 정확한 줄 번호(line numbers), 당신이 첫 번째 접근 방식을 거부했던 이유, "데코레이터(decorators)가 아니라 미들웨어(middleware)를 사용하기로 합의했다"는 결정 같은 것들 말이죠. 따라서 진짜 목표는 단순히 충돌(crash)을 피하는 것이 아니라, Claude가 실제로 무엇을 기억할지 제어권을 유지하는 것입니다.

해결 방법, 빠른 순서대로

요약 버전입니다. 자세한 내용은 아래에 있습니다.

관련 없는 작업 사이의 /clear

방금 로그인 버그 수정을 마쳤습니다. 이제 CSV 내보내기 작업을 시작하려 합니다. 이때 /clear를 입력하세요. 대화 내용을 비우고 다시 전체 창을 확보해 줍니다. 로그인 디버깅 히스토리를 내보내기 작업까지 끌고 갈 이유는 전혀 없습니다. 솔직히 말해서, "컨텍스트가 계속 부족하다"는 불평의 대부분은 사실 "세 가지 서로 다른 작업을 하면서 한 번도 비우지 않았다"는 뜻입니다. 이것이 문제를 해결하는 습관입니다.

/compact, 그리고 무엇을 남길지 지시하기

작업 중간에 여유 공간이 필요할 때는 /compact를 사용하세요. 아무 지시 없이 사용하면 대화 전체를 요약하고 계속 진행합니다. 대신 다음과 같이 힌트를 주는 것이 더 좋습니다:

/compact keep the auth refactor details — which files changed, the new token flow, and the decision to use middleware not decorators
(인증 리팩토링 상세 내용을 유지해줘 — 어떤 파일이 변경되었는지, 새로운 토큰 흐름, 그리고 데코레이터가 아닌 미들웨어를 사용하기로 한 결정)

이러한 지시사항은 무엇을 남길지 방향을 잡아줍니다. 지시가 없으면 Claude가 무엇이 중요한지 결정하지만, 지시가 있으면 당신이 결정하게 됩니다. 연속성이 필요할 때는 /compact를, 필요 없을 때는 /clear를 사용하세요.

세션당 하나의 작업

세션당 하나의 작업

"이 실패하는 테스트를 수정해줘"로 시작했다가 "API 클라이언트도 리팩토링하고, 아 그리고 문서도 업데이트하고, 배포 파이프라인에 대해서도 얘기해보자"로 커지는 세션은 결국 공간이 부족해질 것이며, 그 과정에서 작업의 질도 점점 나빠집니다. 하나의 세션에는 하나의 작업만 담으세요. 완료되었나요? /clear를 입력하세요. 만약 무언가를 다음으로 이어가고 싶다면, 세션 종료 요약(이와 관련된 패턴은 저희 Claude Code 팁 포스트에 있습니다)을 요청한 뒤, 이를 다음 세션의 첫 번째 메시지로 붙여넣으세요.

구체적으로 요청하여 읽기 양 줄이기

"결제 흐름(checkout flow)의 버그를 수정해줘"라고 하면 Claude는 탐색을 시작합니다. 장바구니 컴포넌트, 결제 컴포넌트, 결제 서비스, 주문 모델 등 아마 그중 세 개 정도를 통째로 읽게 될 것입니다. 반면 "src/checkout/PaymentForm.tsx에서 validateCard가 유효한 Amex 번호를 거부합니다. 정규 표현식(regex)이 너무 엄격합니다"라고 하면 단 하나의 함수만 읽게 됩니다. 수정 사항은 동일하지만, 사용하는 토큰(token)은 아주 적습니다. 경로(path)와 심볼(symbol)을 알고 있을 때마다 명시적으로 말해 주세요.

매번 프로젝트를 다시 학습하지 않도록 하는 CLAUDE.md

레포지토리 루트(repo root)에 당신의 컨벤션(convention), 간단한 아키텍처 노트, 그리고 "항상 X를 수행할 것"과 같은 규칙을 담은 CLAUDE.md 파일을 만드세요. Claude는 매 세션 시작 시 이 파일을 자동으로 읽기 때문에, 당신이 Swift 6 동시성(concurrency)을 사용한다거나 테스트가 Tests/ 디렉토리에 있다는 사실을 알아내기 위해 일일이 파헤칠 필요가 없습니다. 매 세션마다 토큰을 다시 낭비하는 대신, 한 번만 저렴하게 컨텍스트(context) 비용을 지불하면 됩니다. 17가지 Claude Code 팁 포스트에서는 그 안에 무엇을 넣는 것이 가치 있는지 자세히 다룹니다.

대규모 검색은 서브에이전트(subagent)에게 맡기기

"legacy auth endpoint를 여전히 호출하는 모든 곳을 찾아줘"와 같은 작업은 메인 컨텍스트(main context)에 포함될 필요가 없는, 노이즈가 많고 파일 집약적인 작업의 전형적인 예입니다. 이러한 작업은 Task 도구를 통해 서브에이전트(subagent)에게 맡기세요. 서브에이전트는 자신만의 일회성 윈도우(throwaway window)에서 grepping 및 읽기 작업을 수행한 뒤, 정답만을 가지고 돌아옵니다. 이를 통해 사용자의 세션은 가볍게 유지됩니다. "모든 에러 핸들링(error handling)을 감사해줘" 또는 "이 지원 중단된(deprecated) 모듈을 임포트하는 모든 컴포넌트를 나열해줘"와 같은 작업에도 동일하게 적용됩니다.

수다스러운 MCP 서버의 볼륨 줄이기

MCP 서버는 훌륭하지만, 너무 장황한(verbose) 서버는 매 호출마다 지불해야 하는 세금과 같습니다. 데이터베이스 서버가 단 3개의 컬럼만 필요했는데 200개의 컬럼을 반환한다면, 쿼리(query)를 수정하세요. 만약 Docs 서버, Jira 서버, Slack 서버, Postgres 서버가 모두 로드되어 있지만 오늘 단 하나만 사용한다면, 이번 세션에서는 나머지를 비활성화하세요. 일부 서버는 결과 크기를 제한(cap)할 수 있게 해주는데, 이를 활용하십시오. 저희의 최고의 MCP 서버 정리에서는 출력 결과에 대해 절제된 동작을 보이는 서버들을 표시하고 있습니다.

로그 전체를 붙여넣지 마세요

600줄짜리 빌드 로그를 붙여넣으면 600줄 전체가 영구적으로 컨텍스트에 포함됩니다. 대신, 로그를 파일로 보내고(npm run build &> build.log) Claude에게 "빌드가 실패했습니다. build.log의 마지막 40줄을 읽어보세요"라고 말하세요. 또는 채팅에 도달하기 전에 미리 필터링할 수도 있습니다: npm test 2>&1 | grep -A5 -i fail. Claude Code는 어차피 터미널 출력을 네이티브로 읽을 수 있으므로, 실패한 명령어를 실행하고 Claude가 그 끝부분(tail)을 가져가도록 하는 것이 전체를 복사해서 붙여넣는 것보다 훨씬 낫습니다.

경고가 갑작스럽게 나타날 때는 /context 사용

예상보다 일찍 경고가 나타난다면, /context를 실행하고(상태 표시줄의 컨텍스트 인디케이터를 주시하세요) 확인하십시오. 이 명령은 시스템 프롬프트(system prompt), CLAUDE.md, MCP 도구 정의(tool definitions), 대화 내용, 파일 읽기 등이 윈도우 내에서 어떻게 나뉘어 있는지 보여줍니다. 대개 원인은 명확합니다. 하나의 거대한 파일 읽기 작업이거나, 사용자가 한 마디도 하기 전에 도구 스키마(tool schemas)만으로 이미 15K 토큰을 잡아먹고 있는 MCP 서버 더미인 경우가 많습니다. /cost 명령어도 살펴볼 가치가 있습니다. 토큰 소모량과 컨텍스트 압박은 서로 비례하는 경향이 있기 때문입니다.

1M 토큰 컨텍스트 윈도우(window) — 존재하지만, 의존하지 마세요

일부 Claude 모델과 플랜은 1M 토큰의 컨텍스트 윈도우(context window)를 제공합니다. 이는 실제로 존재하며 대규모 코드베이스(codebase) 작업에 진정으로 도움이 됩니다. 하지만 토큰당 비용이 더 많이 들고, 모델이 거대한 컨텍스트 중간에서 길을 잃을 수 있으며, 세션이 무분별하게 확장되는 근본적인 습관을 해결해주지는 못합니다. 이를 어려운 문제를 해결하기 위한 여유 공간(headroom)으로 취급해야지, 위의 모든 수칙을 건너뛰어도 된다는 허가증으로 여겨서는 안 됩니다.

/clear vs /compact, 한눈에 비교하기

딱 한 가지만 기억하세요. 작업이 바뀌면 /clear, 같은 작업을 수행 중인데 공간이 부족하면 지침과 함께 /compact를 사용하세요. 그리고 이전의 상세 정보가 반드시 필요할 것 같은 작업을 하기 전이라면, 먼저 어딘가에 기록해 두세요.

자동 압축(auto-compaction)이 문제를 일으킬 때

앞으로 필요한 것이 요점뿐이라면 자동 압축(auto-compaction)은 괜찮습니다. "우리가 작업해 온 기능을 계속 만들어줘" 같은 요청은 문제없이 살아남습니다. 문제가 되는 지점은 이전의 정밀한 상세 정보가 필요할 때입니다. 예를 들어, 2단계에서의 정확한 디프(diff), 접근 방식 A가 막다른 길이었던 이유, 수정하려던 줄 번호(line numbers) 등이 그렇습니다. 요약은 이러한 세부 사항을 덮어버립니다.

따라서 자동 압축이 트리거되기 전에 — 보통 경고가 뜨거나 인디케이터(indicator)가 올라가는 것을 볼 수 있습니다 — 중요한 내용들을 체크포인트(checkpoint)로 만드세요. Claude에게 다음과 같이 요청하세요: "지금까지 변경한 내용을 요약해줘. 수정된 모든 파일에 대해 한 줄 메모를 남기고, 주요 결정 사항을 포함해서 NOTES.md에 작성해줘." 또는 결정 사항을 CLAUDE.md에 직접 적어두세요 ("인증(auth)은 데코레이터(decorators)가 아닌 미들웨어(middleware) 기반임"). 그러면 이제 중요한 기록이 요약기에 휘둘리는 것이 아니라 디스크(disk)에 남아 있으므로, 자유롭게 /clear 하거나 /compact를 사용할 수 있습니다. 컨텍스트 윈도우(context window)를 저장 공간(storage)이 아닌 RAM처럼 취급하세요. 잃어버리기 싫은 것이라면 무엇이든 기록해 두세요.

요약 (TL;DR)

컨텍스트 윈도우 (context window)는 유한합니다. 약 200K 토큰이며, 일부 티어에서는 1M까지 지원됩니다. Claude Code는 컨텍스트가 가득 차면 자동으로 압축 (auto-compacts)을 수행하는데, 이 과정에서 정보 손실 (lossy)이 발생합니다. 작업 내용이 완전히 달라졌다면 /clear를 사용하세요. 동일한 작업을 수행 중인데 공간이 부족하다면 /compact <유지할 내용>을 사용하세요. 컨텍스트 부족 문제를 근본적으로 방지하려면 다음을 실천하세요: 파일 경로를 구체적으로 지정하고, 세션당 하나의 작업만 유지하며, CLAUDE.md 파일을 관리하세요. 대규모 검색 작업은 서브에이전트 (subagents)에게 맡기고, 노이즈가 심한 MCP 서버를 조용히 시키며, grep으로 먼저 확인할 수 있는 로그를 통째로 붙여넣지 마세요. /context를 사용하여 어떤 요소가 토큰을 소비하고 있는지 확인하세요. 그리고 자동 압축이 실행되기 전에 중요한 상태 (state)를 파일로 체크포인트 (checkpoint) 해두세요.

한 가지 주의할 점은, 슬래시 명령어 (slash commands)와 제한 사항은 Claude Code 버전에 따라 변경될 수 있다는 것입니다. 만약 /compact나 /context가 본문의 내용과 다르게 동작한다면, 사용 중인 버전의 현재 명령어 목록을 확인하기 위해 /help를 실행하세요.

다른 도구가 긴 세션을 더 잘 처리하는지 궁금하다면, 저희의 Claude Code vs Cursor vs Copilot 비교에서 각 도구가 컨텍스트를 어떻게 다루는지 자세히 다루고 있습니다.

단순히 "컨텍스트 부족을 막는 것" 이상의 Claude Code 활용법을 원하시나요? 생산성을 10배 높여주는 17가지 Claude Code 팁에서 CLAUDE.md 패턴, 서브에이전트 활용 기술, 커스텀 슬래시 명령어 등을 다룹니다. 이는 애초에 컨텍스트를 가볍게 유지할 수 있는 습관들입니다. 더 많은 내용은 AI 도구 섹션에서 확인하세요.