클로드코드 컨텍스트 관리법, compact 타이밍과 auto memory

컬코단에서 최근 나온 질문은 단순했다. 대규모 솔루션을 바이브 코딩으로 짜던 한 참가자는 세션이 길어질수록 앞서 정한 아키텍처 결정과 CLAUDE.md 내용이 흐려지는 경험을 전했다. 마스터맵 문서를 만들어 매번 참고시키는 방법도 컨텍스트 윈도우를 더 빨리 소모시킨다는 문제로 이어졌다. compact와 clear가 실제로 무엇을 남기고 무엇을 버리는지, 그리고 "기능 하나는 한 세션에 끝내야 한다"는 전제를 얼마나 지켜야 하는지가 이 기사가 답하려는 질문이다.

compact를 늦게 누를수록 요약이 아니라 손실이 된다

컨텍스트가 길어질수록 모델 성능이 떨어지는 현상을 벡터DB 업체 Chroma는 "context rot"이라 부르며 실측했다. 입력 토큰이 늘어날수록 추론 정확도는 떨어진다. 복잡한 작업일수록 더 적은 토큰에서부터 성능이 무너지기 시작한다는 결과다. Claude Code의 compact 명령은 이 문제를 겨냥해 만들어졌지만, 커뮤니티에서 자주 나오는 지적은 타이밍이다.

컨텍스트가 거의 꽉 찬 뒤에야 compact를 누르면, 요약이 아니라 필요한 정보까지 함께 잘려나간다.

올해 들어 Sonnet 5와 Opus 4.8 계열은 컨텍스트 창을 최대 100만 토큰까지 표준 요금으로 쓸 수 있게 됐지만, 창이 커졌다고 로트 문제가 사라지지는 않는다. 모델마다 그 큰 창을 실제로 얼마나 잘 활용하는지는 편차가 크다는 벤치마크 결과도 있다. 창 크기만 믿고 관리를 늦추는 것은 위험하다는 지적이 나온다.

실제로 써본 사람들 사이에서는 방금 내린 아키텍처 결정을 compact 직후 CLAUDE.md에 옮겨 적어두지 않으면 요약 과정에서 빠져버린다는 경험담이 자주 나온다. 기능 단위로 작업을 끊고 구현이 끝날 때마다 compact를 걸어 품질을 유지한다는 패턴도 공유된다. 방에서 나온 "컨텍스트 50%마다 compact하는 방식은 좋은 해결책이 아니다"라는 문제의식도 이 지점과 맞닿아 있다. 시점을 얼마나 앞당기느냐보다, 압축될 때 무엇이 버려지는지를 더 신경 써야 한다는 뜻이다.

임계치 설정과 자동 메모리는 이미 있는 기능이다

Claude Code는 compact가 자동으로 걸리는 시점을 환경변수로 조정할 수 있게 해준다. 기본값은 컨텍스트의 약 95% 지점이다. 설정 파일에 값을 낮게 넣으면 그보다 훨씬 일찍 압축이 시작된다. 커뮤니티에서는 60~75% 구간을 절충점으로 많이 권한다. 방에서 나온 "90%를 상한으로 두고 85%에서 세션 정리를 강제한다"는 제안은 이보다 늦게 걸리지만, 방향 자체는 같다.

메모리를 강제로 기록해두자는 아이디어에 해당하는 기능도 이미 존재한다. Claude Code는 기본적으로 auto memory를 켜둔 상태로 동작한다. 작업 중에는 스스로 판단해 빌드 명령이나 디버깅 요령, 코드 스타일 같은 것을 프로젝트별 메모리 폴더에 적어둔다. 다만 이 기록은 방에서 제안한 것처럼 토큰 사용률 몇 퍼센트를 기준으로 강제되지 않는다. Claude가 유용하다고 판단할 때, 또는 세션이 잠시 멈춘 시점에 알아서 쓰는 방식이라 사용자가 시점을 통제하기는 어렵다.

저장된 내용은 `/memory` 명령으로 언제든 열어 직접 고칠 수 있다.

CLAUDE.md는 압축에서 살아남지만 하위 문서는 아니다

공식 문서에 따르면 프로젝트 루트에 있는 CLAUDE.md는 compact가 끝난 뒤 디스크에서 다시 읽혀 세션에 재주입된다. 반면 하위 디렉터리의 CLAUDE.md나 특정 경로에만 걸리는 규칙 파일은 자동으로 다시 불러오지 않는다. Claude가 해당 경로의 파일을 다시 읽을 때에야 그 내용이 컨텍스트로 돌아온다.

이 구조와 맞물리는 게 바로 방에서 겪은 "마스터맵 문서를 참고시켰는데 상시 읽기는 컨텍스트를 크게 소모한다"는 문제다. 마스터맵을 별도 문서로 빼두면 compact 이후 다시 불러오는 비용이 계속 쌓인다. 반대로 핵심 요약을 프로젝트 루트 CLAUDE.md 안에 짧게 박아두면, 그 부분만큼은 자동으로 복원된다.

CLAUDE.md 자체도 200줄을 넘기면 컨텍스트를 더 먹고 지시 이행률도 떨어진다는 것이 공식 가이드의 설명이다. 큰 문서를 그대로 상시 읽기보다는 파일 경로별로만 걸리는 규칙으로 쪼개는 편이 낫다. 필요할 때만 불러오도록 스킬로 옮기라는 조언과도 맞물린다.

기능 하나를 한 세션에 끝내야 한다는 전제, 정말 필요한가

방에서 나온 마지막 질문, 즉 한 기능을 반드시 하나의 세션에서 끝내야 하느냐는 이미 여러 갈래로 답이 나와 있는 문제다. Anthropic은 작업을 단계별로 쪼개고 각 경계마다 git 체크포인트를 남기라고 권한다. 서브에이전트나 별도 git worktree로 작업을 격리해 메인 세션의 컨텍스트를 아끼는 방식도 공식적으로 안내하는 패턴이다.

세션이 끝나기 전에 진행 상황과 다음 할 일을 별도 문서로 남긴다. 다음 세션이 그 문서를 읽고 이어받는 "핸드오프" 방식은 커뮤니티에서 이미 커스텀 명령어와 스킬로 여러 벌 나와 있다. 완료한 일과 다음 할 일, 핵심 결정을 마크다운 파일 한 장으로 정리해 두면 다음 세션을 시작할 때 그 파일부터 읽혀 처음부터 다시 설명할 필요가 없어진다.

이 기능은 Claude Code에 기본 내장돼 있지는 않다. 세션 종료 시 자동으로 인수인계 문서를 쓰고 다음 세션이 그걸 자동으로 읽게 해달라는 기능 요청은 2025년 11월 GitHub 이슈로 올라왔다. 아직 열린 채로 공식 답변 없이 남아 있다. 인접한 기능은 최근 들어왔다. 올해 6월 업데이트부터 `/clear`로 컨텍스트를 지운 뒤에도 `/rewind`를 눌러 지우기 이전 상태로 되돌아갈 수 있게 됐다. 실수로 지운 맥락을 되살릴 여지는 생겼지만, 이것도 세션이 살아있는 동안에만 통하는 임시방편이다.

방에서 나온 "토큰 90% 상한, 85%에서 정리와 기록 강제" 제안은 사실 새 기능이 아니다. 이미 있는 compact 임계치 설정과 auto memory를, 사용자 스스로 더 타이트하게 규율화하려는 시도에 가깝다. 네이티브 핸드오프 기능이 없는 지금은, 작업 단위를 세션 하나에 욱여넣기보다 단계마다 문서를 남기고 다음 세션에 넘기는 습관 쪽이 먼저 검증된 해법으로 남아 있다.