AI Agent(Claude API)와 Claude Code를 오래/깊게 쓰다 보면, "컨텍스트는 누적되고 성능/비용은 악화"됩니다. 이 문서는 Anthropic의 공식 문서를 기반으로, 컨텍스트/토큰을 실전에서 관리하는 방법을 한 곳에 정리합니다.
CLAUDE.md, /clear, Subagents, 비용/권한/설정으로 "세션 컨텍스트"를 통제Claude Code는 여러 종류의 "메모리"를 읽어 세션 시작 컨텍스트를 구성합니다.
./CLAUDE.md 또는 ./.claude/CLAUDE.md./.claude/rules/*.md (YAML frontmatter로 경로 조건부 적용 가능)./CLAUDE.local.md (gitignore 자동)~/.claude/projects/<project>/memory/ (엔트리 MEMORY.md는 첫 200줄만 자동 로드)실전 팁:
CLAUDE.md를 "짧게" 유지하고, 상세 규칙은 .claude/rules/로 분리한다.CLAUDE.md에서 @path/to/import로 파일을 가져오되, import 체인을 과도하게 길게 만들지 않는다./clear: 이전 작업의 로그/디버깅 맥락이 다음 작업을 오염시키는 것을 막는다./compact(요약) 또는 checkpoint/rewind 계열 기능으로 정리한다.권장 운영 루틴:
/rename로 세션 이름 -> /clear -> "기능 B" 시작Subagent는 별도의 컨텍스트 윈도우에서 동작하므로, 아래 작업을 분리하면 본 세션 컨텍스트를 덜 오염시킵니다.
대량 데이터를 그대로 대화로 흘리지 말고:
NOTES.md, DECISIONS.md, MIGRATION_PLAN.md)로 남기고@파일로 로드하거나POST /v1/messages/count_tokens는 무료이며, 전송 전에 입력 토큰을 추정할 수 있습니다.
반복되는 컨텍스트(툴 정의, 시스템 프롬프트, 긴 문서)를 cache_control로 prefix 캐시로 만들 수 있습니다.
핵심 포인트:
tools -> system -> messagesusage에서 cache_creation_input_tokens, cache_read_input_tokens로 히트율을 추적input_tokens는 마지막 cache breakpoint 이후 토큰만 의미실전 선택 기준:
# Project Context
- 목적: (한 줄)
- 핵심 제약: (예: type safety, 테스트 필수)
## Working Agreement
- 변경은 최소 단위로
- 검증: (예: lint/test/build)
## Project Map
- src/: ...
- tests/: ...
## Commands
- test: ...
- lint: ...
- build: ...
{
"model": "claude-sonnet-4-5",
"max_tokens": 1024,
"system": [
{"type": "text", "text": "Your stable system prompt..."},
{"type": "text", "text": "<LONG_REFERENCE_DOC>", "cache_control": {"type": "ephemeral"}}
],
"messages": [
{"role": "user", "content": "이번 요청의 질문/작업(짧게)"}
]
}
{
"betas": ["context-management-2025-06-27"],
"context_management": {
"edits": [
{"type": "clear_thinking_20251015", "keep": {"type": "thinking_turns", "value": 2}},
{"type": "clear_tool_uses_20250919", "trigger": {"type": "input_tokens", "value": 30000}, "keep": {"type": "tool_uses", "value": 3}}
]
}
}
/rename 후 /clear