Claude Code 컨텍스트 관리 실전: /context, /compact, /clear 사용법

Claude Code에게 로그인 오류를 맡겼을 때 처음에는 관련 파일도 잘 찾고, “공개 API는 바꾸지 않는다”는 조건도 기억합니다. 그런데 한 시간쯤 지나면 이미 읽은 파일을 다시 열거나, 폐기한 해결책을 제안하거나, 합의한 범위 밖의 인증 코드를 수정하려고 할 수 있습니다. 처음 쓰는 사람에게는 모델 성능이 갑자기 나빠진 것처럼 보입니다.

대부분은 모델 문제가 아니라 작업 중인 컨텍스트가 복잡해진 탓입니다. 대화 기록, 읽은 파일, 명령 출력, 프로젝트 지침, 도구 설명, Claude의 답변이 모두 한정된 컨텍스트 창을 함께 사용합니다. 오래된 조사와 반복 로그가 자리를 차지하면 지금 지켜야 할 목표가 상대적으로 흐려집니다.

따라서 컨텍스트 관리는 토큰을 조금 아끼는 요령이 아닙니다. 지금 작업에 필요한 정보, 계속 남길 프로젝트 규칙, 요약해도 되는 과정, 새 대화로 분리할 시점을 정하는 품질 관리입니다. 아래 순서대로 따라 하면 토큰이나 세션 저장 방식을 잘 몰라도 긴 작업을 안정적으로 운영할 수 있습니다.

먼저 기억할 핵심

• 원인을 추측하기 전에 /context를 실행해 현재 창을 무엇이 차지하는지 확인합니다.
• 목표가 같은데 대화만 길어졌다면 /compact로 요약하고 계속합니다. 뒤에 보존할 항목을 구체적으로 적을 수 있습니다.
• 전혀 다른 작업으로 넘어갈 때는 /clear를 사용합니다. 이전 대화는 삭제되지 않으며 나중에 다시 열 수 있습니다.
• /memory는 지속 지침과 자동 메모리를 확인하고 편집하는 곳입니다. 실제로 어떤 메모리 파일이 현재 로드됐는지는 /context에서 확인합니다.
• /usage는 세션 비용, 요금제 한도, 활동 정보를 보여 줍니다. /cost는 별칭이고, /stats도 별칭이지만 Stats 탭을 엽니다.
• 압축이나 인계 전에 짧은 작업 영수증을 남기고, 반드시 유지할 규칙은 CLAUDE.md나 프로젝트 문서에 기록합니다.

컨텍스트 창을 작업 책상으로 이해하기

컨텍스트 창은 Claude가 현재 답변을 만들 때 참고할 수 있는 정보 범위입니다. 이를 작업 책상이라고 생각하면 쉽습니다. 정리된 책상에는 목표, 관련 파일 두 개, 핵심 오류 한 줄, 완료 조건만 있습니다. 어지러운 책상에는 포기한 접근법, 전체 빌드 로그, 무관한 조사, 서로 충돌하는 예전 지시가 쌓여 있습니다.

화면에 보이는 대화만 공간을 쓰는 것은 아닙니다.

컨텍스트를 쓰는 항목	복잡해지는 이유	운영 방법
대화 기록	옆길로 샌 질문과 폐기된 결정도 남음	관계없는 작업을 분리하고 현재 결정을 기록
파일 읽기	큰 파일이나 생성물을 통째로 불러옴	검색한 뒤 필요한 파일과 범위만 읽기
도구 출력	같은 테스트와 긴 로그가 반복됨	원인 줄과 최종 결과만 남기기
CLAUDE.md와 규칙	넓고 중복되거나 충돌하는 지침이 반복 로드됨	상시 규칙은 짧게, 전용 절차는 범위가 있는 파일로 이동
스킬과 도구 설명	활성화된 기능 자체가 시작 공간을 사용함	현재 작업에 필요한 기능만 유지

창이 한계에 가까워지면 Claude Code가 자동으로 압축할 수 있습니다. 세션이 바로 멈추는 상황은 피할 수 있지만, 자동 요약도 무엇이 중요한지 선택해야 합니다. 조사에서 구현으로 넘어가는 것처럼 단계가 크게 바뀌는 시점에는 사람이 보존 항목을 지정해 먼저 압축하는 편이 안정적입니다.

명령마다 해결하는 문제가 다릅니다

다섯 가지 명령은 모양은 비슷하지만 목적이 다릅니다. 대화형 Claude Code에서 메시지 맨 앞에 입력합니다.

/context: 현재 창부터 진단하기

/context는 현재 컨텍스트 사용량을 색상 격자로 보여 주고, 무거운 도구, 메모리 비대, 용량 경고에 대한 최적화 제안을 표시합니다. 항목별 상세 내역이 필요하면 /context all을 사용합니다.

/context
/context all

긴 작업을 시작할 때 기준값을 보고, 큰 조사가 끝난 뒤 무엇이 늘었는지 확인하며, /compact 직전에는 요약에서 강조할 대상을 고르는 데 씁니다. 진단 명령일 뿐이라서 화면을 열었다고 내용이 정리되지는 않습니다.

/compact [지침]: 같은 작업을 요약해서 계속하기

/compact는 대화 기록을 구조화된 요약으로 바꾸고 같은 대화를 이어 갈 공간을 만듭니다. 명령 뒤의 문장은 요약기가 우선해서 보존할 내용을 알려 줍니다.

/compact 합의한 API 계약, 변경 파일, 실패한 테스트, 실행한 명령, 다음 작업을 보존해 줘

목표는 그대로인데 조사 과정만 길어진 경우에 적합합니다. 예를 들어 같은 인증 버그를 계속 고치지만 탐색 로그가 너무 많아졌을 때 사용합니다. 모든 문장이 그대로 남는 기능은 아닙니다. 매번 지켜야 하는 규칙은 미리 CLAUDE.md, 명세 또는 인계 문서에 기록해야 합니다.

/clear [이름]: 다른 작업을 새 대화에서 시작하기

/clear는 대화 기록이 비어 있는 새 대화를 시작합니다. 선택적으로 이전 대화의 이름도 지정할 수 있습니다. 프로젝트 메모리는 유지되고 다시 로드되며, 앞선 대화는 저장된 상태로 남습니다.

/clear auth-fix-complete

다음 요청의 목표, 대상 파일, 판단 과정이 이전 작업과 다르면 새로 시작하는 편이 낫습니다. 앞선 작업은 삭제되지 않습니다. 대화형 세션은 계속 저장되므로 /resume, claude --resume, 같은 디렉터리의 최근 세션을 여는 claude --continue로 돌아갈 수 있습니다.

/memory: 오래 남길 정보를 관리하기

/memory는 CLAUDE.md와 CLAUDE.local.md 위치를 나열하고 해당 파일을 열거나 만들 수 있게 합니다. 자동 메모리 항목을 보고 기능을 켜고 끄는 작업도 여기서 합니다. 즉 “이 정보를 다시 쓸 수 있도록 어디에 둘까?”라는 질문에 답하는 명령입니다.

/memory

다만 목록에 보이는 모든 파일이 지금 컨텍스트에 활성화됐다는 뜻은 아닙니다. 실제로 로드된 메모리 파일은 /context의 Memory files 영역에서 확인해야 합니다. 프로젝트 CLAUDE.md는 커밋해 팀과 공유할 수 있습니다. 자동 메모리는 로컬에 저장되며 같은 저장소의 worktree끼리는 공유되지만, 다른 컴퓨터로 자동 동기화되지는 않습니다.

/usage, /cost, /stats: 컨텍스트가 아니라 사용량 보기

/usage는 세션 비용, 요금제 사용 한도, 활동 통계를 보여 줍니다. 지원되는 구독 환경에서는 스킬, 서브에이전트, 플러그인, MCP 서버별 사용 내역도 볼 수 있습니다. /cost는 /usage의 별칭입니다. /stats도 같은 별칭이며 Stats 탭을 엽니다.

/usage
/cost
/stats

이 명령은 /context와 다른 질문에 답합니다. 사용량은 이미 얼마나 소비했는지 보여 주고, 컨텍스트는 현재 작업 창에 무엇이 들어 있는지 보여 줍니다. 대화를 압축하거나 초기화해도 이미 발생한 사용량이 되돌아가지는 않습니다.

판단이 헷갈릴 때는 다음 흐름만 기억하면 됩니다.

flowchart TD
    A["/context 실행"] --> B{"같은 작업을 계속하나요?"}
    B -->|예| C["보존할 내용을 적고 /compact 실행"]
    B -->|아니요| D["결과를 기록하고 /clear 실행"]
    C --> E["현재 작업 계속"]
    D --> F["새 작업 설명으로 시작"]

시작 전에 컨텍스트 예산 정하기

“저장소를 전부 읽고 고쳐 줘”라는 요청으로 시작하지 마세요. 목표, 범위, 제외 범위, 완료 조건, 검증 명령, 사람의 승인이 필요한 결정을 짧게 적으면 첫 파일 읽기부터 방향이 생깁니다. 나중에 압축할 때도 이 구조가 요약의 기준이 됩니다.

## 작업 설명
- 목표: 만료 세션에서 발생하는 반복 리디렉션 수정
- 범위: src/auth/, tests/auth/session.test.ts
- 제외: UI 재설계, 인증 공급자 이전
- 완료 조건: 만료 세션이 /login으로 한 번만 이동하고 회귀 테스트 통과
- 검증: npm test -- tests/auth/session.test.ts
- 사람 승인 필요: 쿠키 수명 또는 공개 API 동작 변경

파일을 읽기 전에 검색으로 범위를 줄입니다. 아래 명령은 저장소에 맞게 키워드와 경로만 바꿔 복사해 쓸 수 있습니다.

rg -n "expired session|redirect loop|set-cookie" src tests
git diff --stat
git status --short
npm test -- tests/auth/session.test.ts

순서에도 이유가 있습니다. rg로 후보 파일을 찾고, git diff --stat과 git status로 덮어쓰면 안 되는 기존 변경을 확인한 다음, 범위가 좁은 테스트로 완료 기준을 만듭니다. Claude에게 저장소 전체 대신 다음 판단에 필요한 자료만 주는 방식입니다.

압축 전에 인계 영수증 남기기

/compact, /clear, 다른 세션으로의 인계 전에 짧은 영수증을 작성합니다. 전체 대화를 다시 옮기는 문서가 아니라, 다른 사람이나 에이전트가 조사를 반복하지 않고 이어 가는 데 필요한 최소 상태입니다.

## 인계 영수증
- 현재 목표:
- 확인한 원인:
- 합의한 결정:
- 변경 파일:
- 실행한 명령과 결과:
- 보존해야 할 미커밋 변경:
- 남은 위험:
- 다음 작업:

팀과 공유할 내용이면 프로젝트 문서에 저장하고, 이번 압축에만 필요하면 작성한 내용을 /compact의 초점 지침에 포함합니다. 원본 출력보다 결과를 기록하세요. “session.test.ts 84행에서 리디렉션이 두 번 발생”은 유용하지만, 같은 스택 추적 200줄은 다음 판단에 도움을 주지 않습니다.

압축 후에도 남는 것과 다시 읽어야 하는 것

/compact 이후 정보가 유지되는 방식은 출처에 따라 다릅니다.

정보 출처	/compact 이후 동작
시스템 프롬프트와 출력 스타일	대화 기록이 아니므로 그대로 유지
프로젝트 루트 CLAUDE.md와 범위 제한 없는 규칙	디스크에서 다시 주입
자동 메모리	디스크에서 다시 주입
paths: frontmatter가 있는 규칙	일치하는 파일을 다시 읽어야 나타남
하위 디렉터리의 CLAUDE.md	해당 디렉터리 파일을 읽어야 나타남
호출한 스킬 본문	문서화된 스킬별·전체 한도 안에서 다시 주입
Hooks	대화가 아니라 코드로 계속 실행

가장 취약한 것은 채팅에서만 한 번 말한 세부 조건입니다. 요약에 뜻이 남을 수는 있지만 작은 제약까지 항상 보존된다고 기대하면 안 됩니다. 매번 적용할 규칙은 프로젝트 루트 CLAUDE.md에 둡니다. 특정 경로에만 필요한 규칙은 범위를 유지하되, 압축 뒤 일치 파일을 읽어야 다시 들어온다는 점을 기억하세요.

CLAUDE.md에 압축용 지침을 짧게 두는 방법도 있습니다.

# CLAUDE.md

## Compact instructions
- 현재 목표, 합의한 결정, 제외 범위를 보존한다.
- 변경 파일, 검증 명령, 테스트 결과, 장애물을 보존한다.
- 원인을 설명하는 줄을 제외한 원시 로그는 제거한다.
- 사용자의 미커밋 변경과 다음 안전한 작업을 보존한다.

이 부분을 프로젝트 전체 매뉴얼처럼 길게 만들지는 마세요. CLAUDE.md도 매 대화 시작 시 컨텍스트를 사용하므로, 지나치게 긴 상시 지침은 해결하려던 문제를 다시 만듭니다.

에이전트가 맡을 일과 사람이 승인할 일

좋은 컨텍스트 관리는 책임 분담까지 포함합니다. Claude는 검색, 요약, 테스트, 대안 제시에 강합니다. 저장소만 보고 결과를 안전하게 판단할 수 없는 결정은 사람이 소유해야 합니다.

Claude Code가 맡을 수 있는 일	사람이 승인해야 하는 일
관련 파일 탐색과 긴 로그의 원인 요약	사업 목표와 허용 가능한 절충 결정
컨텍스트 압박 보고와 압축 시점 제안	두 작업이 정말 같은 범위인지 판단
관찰한 작업을 기반으로 인계 영수증 작성	삭제 작업, 자격 증명 사용, 운영 환경 변경 승인
합의한 검증 명령 실행	보안 정책, 공개 동작, 데이터 보존 변경 수용
명시적 승인 후 문서화된 규칙 갱신	이해관계자의 상충 요구 해결

에이전트에게 “절대 잊으면 안 되는 것”까지 혼자 결정하게 한 뒤 그 결론을 같은 복잡한 대화에만 남겨 두면 안 됩니다. 사람이 지속 제약을 정하고, 에이전트가 합의한 위치에 기록한 다음 실제 로드 여부를 확인하는 구조가 필요합니다.

네 가지 구체적인 사용 사례

사례 1: 여러 파일에 걸친 인증 리팩터링

상황: 미들웨어, 쿠키 유틸리티, 통합 테스트, 배포 설정을 조사합니다. 모든 파일과 실패 로그를 한 대화에 넣으면 구현 단계에서 핵심 계약이 묻힙니다.

에이전트 범위: 검색으로 인증 흐름을 찾고, 넓은 문서 조사는 별도 에이전트에 맡깁니다. 메인 컨텍스트에는 선택한 계약, 대상 파일, 집중 테스트 결과만 돌려놓습니다.

사람 확인: 쿠키 유효 기간, 로그아웃 동작, 호환성 보장 변경은 제품과 보안 결정이므로 승인이 필요합니다.

진행 순서: 작업 설명을 작성하고, 조사 뒤 /context를 실행하고, 승인된 설계를 영수증에 기록한 다음 /compact 승인한 인증 계약과 회귀 테스트를 보존해 줘를 실행합니다.

사례 2: 실패한 배포 분석

상황: 여러 번 재시도하면서 거의 같은 로그가 쌓이고, 실제 원인 한 줄이 설치 출력과 경고 사이에 묻힙니다.

에이전트 범위: 시도별 차이를 비교하고 첫 번째 원인 오류를 찾습니다. 환경과 정확한 실패 명령을 기록하고 중복 로그는 작업 요약에서 제외합니다.

사람 확인: 자격 증명, 클라우드 공급자 설정, 롤백은 승인이 필요합니다. 진단을 이유로 접근 권한을 조용히 넓혀서는 안 됩니다.

진행 순서: 실패 명령과 원인 줄을 영수증에 남깁니다. 같은 장애를 계속 다룰 때는 압축하고, 배포 확인이 끝났거나 무관한 기능으로 이동할 때만 초기화합니다.

사례 3: 기술 글 작성과 검수

상황: 출처 조사, 편집 규칙, 코드 실행 결과, 번역 메모, 렌더링 확인이 한 대화에 모이면 글쓰기에 쓸 공간이 빠르게 줄어듭니다.

에이전트 범위: 조사 메모는 별도 파일, 지속 편집 규칙은 CLAUDE.md, 최종 원고는 MDX에 둡니다. 조사에서는 검증된 사실과 미해결 질문만 반환하고 게시 전에 코드와 링크를 확인합니다.

사람 확인: 독자, 상업적 약속, 하나의 주요 CTA는 사람이 정합니다. 에이전트는 표현을 다듬을 수 있지만 경험, 벤치마크, 고객 결과를 만들어 내면 안 됩니다.

진행 순서: 조사와 작성을 분리하고 승인된 개요를 중심으로 압축합니다. slug, 언어, 변경 파일, 검사 결과, 배포 상태를 영수증에 남깁니다.

사례 4: 버그 수정에서 새 기능으로 전환

상황: 버그는 해결됐지만 같은 터미널에서 다음 요청이 무관한 대시보드 기능을 시작합니다.

에이전트 범위: 최종 diff와 테스트 결과를 보고한 뒤 명확한 작업 경계를 제안합니다.

사람 확인: 버그 작업의 후속 내용 중 새 작업에 꼭 포함할 것이 없는지 확인합니다.

진행 순서: 완료한 세션을 기록하고 /clear bug-fix-complete를 실행한 뒤 새 작업 설명으로 시작합니다. 나중에 세부 정보가 필요하면 옛 대화를 계속 들고 가는 대신 /resume으로 돌아갑니다.

자주 발생하는 함정과 해결법

함정 1: /compact를 무손실 백업으로 생각하기

압축은 선택적 요약입니다. 한 번만 언급한 작은 제약이 빠질 수 있습니다.

해결: 지속 규칙은 CLAUDE.md나 명세에 두고, 합의한 결정은 압축 전에 인계 영수증에 기록합니다.

함정 2: 진행 중인 작업을 /clear로 해결하기

너무 일찍 초기화하면 현재 작업의 대화형 작업 집합이 없어져 같은 진단을 다시 만들게 됩니다.

해결: 목표와 검증 테스트가 같다면 초점 지침을 붙여 압축하고, 실제 작업 경계가 생겼을 때만 초기화합니다.

함정 3: /memory가 로드 상태까지 증명한다고 믿기

/memory는 지속 파일과 자동 메모리를 관리하는 화면입니다. 중첩 파일과 경로 규칙이 현재 활성화됐다는 보장은 없습니다.

해결: /context의 Memory files를 확인하고, 압축 후 범위 규칙이 필요하면 일치하는 파일을 읽습니다.

함정 4: 보안 강제를 CLAUDE.md에만 맡기기

CLAUDE.md는 컨텍스트 지침이지 강제 보안 경계가 아닙니다. 모호하거나 충돌하는 지시는 일관되지 않게 적용될 수 있습니다.

해결: 반드시 차단하거나 검증해야 할 동작은 권한과 Hooks로 구현하고, CLAUDE.md에는 짧은 업무 규칙을 둡니다.

함정 5: 자동 메모리를 팀 문서로 사용하기

자동 메모리는 로컬 정보입니다. 같은 저장소 worktree끼리 공유되지만 동료 컴퓨터나 클라우드 환경으로 자동 이동하지 않습니다.

해결: 팀 규칙은 커밋되는 CLAUDE.md, rules, docs에 두고 자동 메모리는 로컬 선호와 반복 학습에 사용합니다.

함정 6: 사용량과 남은 컨텍스트를 혼동하기

/usage의 비용과 한도, /context의 창 구성은 운영상 연관은 있어도 같은 측정값이 아닙니다.

해결: 범위 축소, 위임, 압축, 초기화 판단에는 /context를 쓰고, 소비량과 요금제 제한은 /usage로 봅니다.

Obsidian과 프로젝트 파일의 역할 나누기

유용한 메모가 모두 Claude의 상시 메모리에 들어갈 필요는 없습니다. Obsidian은 긴 조사, 대안, 회의 기록, 나중에 쓸 자료에 적합합니다. 저장소는 공유 지침, 명세, 인계 기록, 결과물에 적합합니다.

위치	넣기 좋은 정보
프로젝트 CLAUDE.md	대부분의 세션에서 필요한 짧은 규칙
.claude/rules/	특정 파일 형식이나 경로에 적용되는 지침
프로젝트 docs	공유 결정, 명세, 인계 영수증
Obsidian	긴 조사, 가설, 출처 메모, 아이디어 목록
자동 메모리	로컬 선호와 반복해서 발견한 내용

이렇게 나누면 시작 컨텍스트를 작게 유지하면서 지식을 잃지 않습니다. 관련 절차는 CLAUDE.md 작성 가이드, 토큰 최적화 가이드, Claude Code와 Obsidian 연동에서도 이어서 볼 수 있습니다.

매일 적용하는 다섯 단계

다음 순서를 습관으로 만들면 됩니다.

1. 설명: 목표, 범위, 제외 항목, 완료 테스트, 사람 승인 항목을 씁니다.
2. 축소: 먼저 검색하고 다음 판단에 필요한 파일과 출력만 읽습니다.
3. 진단: 큰 조사 뒤 또는 Claude가 같은 작업을 반복할 때 /context를 실행합니다.
4. 기록: 합의한 결정, 변경 파일, 검증 결과, 다음 작업을 남깁니다.
5. 선택: 같은 작업은 /compact, 새 작업은 /clear, 저장된 작업 복귀는 /resume을 사용합니다.

이 운영 방식에 바로 쓸 수 있는 프롬프트와 템플릿이 필요하다면 Claude Code 실전 프롬프트 가이드를 참고할 수 있습니다.

공식 자료

• 컨텍스트 창 이해하기
• 명령어 참고 문서
• Claude가 프로젝트를 기억하는 방식
• 세션 관리

실제로 확인한 결과

이번 개정에서는 공식 명령어 문서를 기준으로 /cost와 /stats가 모두 /usage로 연결되고, /stats는 Stats 탭을 연다는 현재 동작을 확인했습니다. 컨텍스트 창 문서의 표도 대조해 압축 후 다시 주입되는 항목과, 일치 파일을 읽어야 돌아오는 경로 규칙 및 하위 디렉터리 CLAUDE.md를 구분했습니다.

세션 문서를 통해 /clear가 이전 대화를 삭제하지 않고 새 대화를 시작하며, 저장된 작업을 resume 명령으로 다시 열 수 있다는 점도 확인했습니다. 위의 shell 명령, 작업 설명, 인계 영수증은 복사해 쓸 수 있는 템플릿입니다. 실제 저장소에서는 경로, 검색어, 테스트 명령만 현재 프로젝트에 맞게 바꾸면 됩니다.