Claude Code 컨텍스트 윈도우가 가득 찼을 때: 압축, 초기화, 새 세션
Claude Code나 다른 코딩 에이전트의 컨텍스트가 부족해지면 압축, 초기화, 새 세션 중에서 고르고, 결정 사항은 인수인계 메모로 남기세요.
Claude Code의 컨텍스트 윈도우가 거의 가득 차면 Claude Code가 알아서 대응해요. 먼저 오래된 도구 출력을 지우고, 필요하면 대화를 요약해요. 이 과정에서 초반 지시가 사라질 수 있으니 그 전에 직접 고르세요. 같은 작업을 계속한다면 무엇을 남길지 메모를 붙여 /compact를 실행하세요. 관련 없는 작업으로 넘어간다면 /clear를 실행하세요. 에이전트가 결정 사항을 자꾸 잊는다면 짧은 인수인계 메모를 쓰고, 그 메모로 새 세션을 시작하세요.
다른 코딩 에이전트는 명령이 다를 수 있지만 선택지는 같아요. Mono는 에이전트가 알려 주면 컨텍스트가 얼마나 찼는지 보여 줄 수 있지만, 압축과 초기화는 에이전트가 해요.
1. 컨텍스트 윈도우를 채우는 것 알기
컨텍스트에는 에이전트가 작업할 때 참고하는 모든 것이 담겨요. 내 메시지와 에이전트의 답변, 에이전트가 읽은 파일, 명령과 테스트 출력, 연결된 MCP 서버의 도구 목록, 시작할 때 불러온 지시 파일이 모두 여기에 들어가요. 긴 테스트 로그 하나가 직접 입력한 내용 전체보다 클 수도 있어요.
컨텍스트가 차고 있다는 신호는 다음과 같아요.
- 앞서 정해 준 규칙을 에이전트가 어겨요.
- 이미 답한 질문을 다시 해요.
- 컨텍스트가 부족하다는 경고가 나타나요.
Claude Code에서는 /context로 무엇이 공간을 차지하는지 볼 수 있어요. 한도에 가까워지면 어떤 일이 일어나는지는 Claude Code 작동 방식 개요에 설명돼 있어요.
가상의 예를 들어 볼게요. “tidy-recipes”의 파일 30개를 예전 날짜 헬퍼 oldDate()에서 새 formatDate()로 옮기는 작업을 두 시간째 하던 중에, 에이전트가 어떤 라이브러리를 쓸지 다시 물어요. /context를 보니 컨텍스트 윈도우가 거의 가득 찼어요.
2. 압축, 초기화, 새 세션 중에서 고르기
압축은 같은 세션 안에서 대화를 요약으로 바꿔요. 초기화하거나 새 세션을 시작하면 대화가 사라지지만 지시 파일은 다시 불러와요. 어떤 선택이든 무언가를 잃어요.
| 상황 | 할 일 | 잃는 것 |
|---|---|---|
| 같은 작업이 순조롭게 진행 중 | 초점 메모를 붙여 압축 | 요약에서 빠진 세부 사항 |
| 다음은 관련 없는 작업 | 초기화하거나 새 세션 시작 | 대화 전체 |
| 에이전트가 결정 사항을 잊음 | 인수인계 메모를 쓰고 새 세션 시작 | 인수인계 메모에 적지 않은 모든 것 |
초점 메모는 요약에 무엇을 남길지 알려 줘요. 날짜 관련 결정과 실패하는 테스트에 집중하게 하려면 /compact Focus on date decisions and failing tests처럼 써요. Claude Code의 비용 관리 가이드에 이 방법이 나와 있고, 나중에 /resume으로 세션을 다시 열 수 있도록 /clear 전에 /rename을 실행하라고 권해요.
예시에서는 에이전트가 이미 결정 하나를 잊었으니 인수인계 메모를 쓰세요.
3. 초기화하기 전에 인수인계 메모 쓰기
인수인계 메모는 새 세션을 위한 짧은 메모예요. 직접 쓰거나 에이전트가 쓴 초안을 고치세요.
Goal: Replace oldDate() with formatDate() in recipes/ (30 files).
Done: 18 files, on branch tidy-dates.
Decisions: formatDate() uses Intl.DateTimeFormat, so no new library.
Keep oldDate() for importing v1 files, which use the old format.
Open problem: The recipes/print.ts test has failed since the change.
Next step: Fix print.ts, then move the remaining 12 files.결정마다 이유를 적으세요. 그러지 않으면 다음 세션이 그 결정을 뒤집을 수 있어요. 메모는 프로젝트나 개인 노트에 저장하고, 세부 내용이 필요할 때를 대비해 대화를 내보내 두세요.
그런 다음 같은 프로젝트에서 /clear를 실행하거나 새 세션을 시작하고, 대화록이 아니라 인수인계 메모만 붙여 넣으세요.
4. 계속 지켜야 할 규칙은 대화 밖으로 옮기기
어떤 수정 사항은 작업 하나가 끝난 뒤에도 계속 중요해요. “프로젝트의 날짜 헬퍼를 써”나 “프로젝트의 스크립트로 테스트를 실행해”를 계속 반복하고 있다면, 그 규칙을 AGENTS.md나 Claude Code의 CLAUDE.md 같은 프로젝트 지시 파일에 넣으세요. 새 세션은 그 파일을 읽으므로 초기화해도 규칙이 사라지지 않아요.
이 파일은 세션마다 불러오므로 짧게 유지하세요. 비용 관리 가이드는 CLAUDE.md를 200줄 미만으로 유지하라고 권해요. “30개 중 18개 파일 완료” 같은 진행 상황은 인수인계 메모에 남기세요. 무엇을 넣을지는 AGENTS.md 가이드에서 다뤄요.
예시의 v1 규칙도 여기에 넣어요. v1 파일이 남아 있는 동안에는 계속 유효한 규칙이니까요.
5. 턴마다 더해지는 양 줄이기
컨텍스트가 작을수록 더 오래 버텨요. 요청할 때마다 다음을 지키세요.
- “날짜 고쳐 줘”가 아니라 파일과 함수 이름을 지정하세요.
- 로그 전체가 아니라 관련 있는 오류 줄만 붙여 넣으세요.
- 필요한 테스트만 실행하고, 실패한 결과만 보여 주게 하세요.
- 프로젝트에서 쓰지 않는 MCP 서버는 연결을 끊으세요.
- 에이전트가 지원한다면 범위가 넓은 검색은 서브에이전트에게 맡기세요.
- 세션 하나에는 작업 하나만 하세요.
비용 관리 가이드는 테스트 출력을 걸러 내는 훅을 비롯해 이 방법 대부분을 다뤄요.
6. 초기화 후 에이전트 확인하기
새 세션이 무언가를 수정하기 전에 목표, 결정 사항, 다음 단계를 다시 말해 달라고 요청하고, 그 답을 인수인계 메모와 비교하세요. 예시라면 묻지 않아도 v1 규칙을 언급해야 해요. 빠진 것이 있으면 지금 바로잡으세요. 그런 다음 에이전트가 다음으로 넘어가기 전에 첫 diff인 print.ts 수정을 검토하세요. 코드 검토 가이드에 체크리스트가 있어요.
Mono에서는 에이전트가 사용량을 알려 주면 메시지 입력란 위의 작은 링이 사용한 컨텍스트를 보여 줘요. 절반이 차면 초록색에서 주황색으로, 80%가 차면 빨간색으로 바뀌고, 링을 누르면 ‘컨텍스트: 사용량 / 전체’가 표시돼요. “/”를 입력하면 에이전트가 제공하는 슬래시 명령 목록이 나와요. Agent Client Protocol에서는 에이전트가 슬래시 명령 목록을 알려 주는 것이 선택 사항이에요. 새로 시작하려면 ‘대화 내보내기’로 이전 대화를 저장한 다음, 프로젝트 카드에서 ‘새 세션’을 선택하세요(컴퓨터가 연결되어 있으면 휴대폰에서도 할 수 있어요). Mono는 아직 출시 전이지만 대기자 명단에 등록할 수 있어요.
