이 지침은 Context Mode 프로젝트와 커뮤니티 논의에서 검증된 패턴을 정리한 것입니다.

___________

AI 코딩 에이전트가 도구를 호출할 때마다 원시 데이터가 컨텍스트 윈도우에 쌓입니다. Playwright 스냅샷 56KB, GitHub 이슈 20건 59KB, 액세스 로그 45KB. 이런 식으로 30분이면 200K 토큰의 40%가 사라집니다. 도구를 5~6개만 설치해도 80개 이상의 정의가 로드됩니다. 첫 메시지 전에 이미 72%가 소비되기도 하죠.

출력 격리: 샌드박스 실행 원칙

도구 호출의 원시 출력을 컨텍스트에 그대로 넣지 않아야 합니다. 각 실행을 격리된 서브프로세스로 돌리고, stdout만 컨텍스트에 포함합니다. 로그, API 응답 원문, DOM 스냅샷 같은 부산물은 샌드박스 내부에 격리합니다.

도구 출력이 1KB를 초과하면 샌드박스 경유를 기본으로 합니다. 단, `curl api.example.com/health`처럼 200바이트 수준의 단순 호출까지 샌드박스로 돌리는 건 과잉입니다. 출력 크기에 따라 바이패스 경로를 열어두되, "기본은 격리, 예외적으로 직통"이 원칙입니다. 임계값은 프로젝트 특성에 맞게 조정하면 됩니다.

지식베이스 검색: 하이브리드 전략

순수 키워드 검색만으로는 부족합니다. 도구 출력은 JSON, 테이블 같은 구조화 데이터와 오류 메시지, 주석 같은 자연어가 뒤섞여 있기 때문입니다.

키워드 검색은 SQLite FTS5 + BM25 랭킹 + Porter stemming을 씁니다. 정확한 식별자, 함수명, 에러 코드 매칭에 강점이 있습니다. 의미 검색은 Model2Vec 또는 경량 임베딩 모델 + sqlite-vec를 활용합니다. "이 에러와 비슷한 맥락" 같은 유사도 기반 탐색에 활용하죠. 결과 병합은 Reciprocal Rank Fusion으로 두 결과를 합칩니다. 각각의 장점을 살리면서 한쪽의 맹점을 보완하는 방식입니다.

인덱싱 원칙도 중요합니다. 마크다운은 헤딩 단위로 분할하고, 코드 블록은 깨지 않게 그대로 유지합니다. `--incremental` 방식으로 변경된 청크만 재인덱싱하면 전체 15,800개 파일 재인덱싱에 4분, 일상적 증분 갱신에 10초 미만이 기준치입니다.

서브에이전트 분리 패턴

컨텍스트 절약의 가장 근본적인 접근은 데이터 압축이 아니라 작업 자체의 분리입니다.

문제가 생기면 서브에이전트를 포크해서 해결하고, 부모 컨텍스트에는 결과만 올립니다. 각 서브에이전트 호출은 별도 프로세스로 실행되어 부모의 메모리를 오염시키지 않습니다.

서브에이전트가 부모에게 전달하는 구조화된 보고 형식입니다:


1. 결과성공/실패 여부와 최종 산출물 확인
2. 과정 요약목표 달성까지의 주요 경로와 방법론
3. 실패한 시도효과가 없었던 접근법과 원인 분석
4. 배운 점향후 재활용 가능한 인사이트와 노하우

프로젝트 회고 4단계


도구 출력은 파일로 저장하고, LLM은 필요한 부분만 읽습니다. `"Success!"`로 끝나면 마지막 줄만 확인하고, 실패 시에는 에러 메시지만 추출하는 방식이죠.

컨텍스트 위생: 백트래킹과 자동 정리

디버깅 중 쌓인 로그와 실패 기록은 버그를 고친 후에 컨텍스트에서 제거할 수 있어야 합니다.

재시도 패턴 자동 감지에서는 동일 작업을 여러 번 시도한 흔적이 있으면 마지막 성공 버전만 남깁니다. 일정 횟수 후 자동 정리에서는 로그성 데이터를 N회 참조 후 또는 관련 작업 완료 후 컨텍스트에서 퇴출시킵니다. 컨텍스트는 스택이 아니라 자유롭게 편집 가능한 작업 공간으로 취급해야 합니다. 단순히 쌓이기만 하는 구조에서 벗어나야 하죠.

압축과 정확도 사이의 트레이드오프

153개의 git 커밋을 107바이트로 줄이면 인상적이지만, 모델이 완벽한 추출 스크립트를 작성해야만 필요한 정보에 접근할 수 있습니다. 잘못된 명령 하나면 핵심 데이터가 사라지죠.

압축은 수단이지 목적이 아닙니다. 세션을 3시간으로 늘려도 2시간째의 추론 품질이 유지되지 않으면 의미가 없습니다. 불완전한 데이터나 잘못된 추출 로직으로 인한 환각 위험을 항상 감안해야 합니다. "요약 후 드릴다운" 패턴을 권장합니다. 처음에는 요약만 컨텍스트에 넣고, 모델이 세부 정보가 필요하다고 판단하면 원본에 접근하는 경로를 열어두는 것입니다.

캐시 경제성 고려

프롬프트 캐싱이 잘 작동하면 장황한 컨텍스트도 비용 면에서 거의 무료에 가깝습니다. 그런데 압축이 캐시 연속성을 깨뜨리면 오히려 비용이 늘어납니다.

동일한 쿼리에 대해 압축된 출력이 결정적이어야 합니다. 매번 다른 형태로 압축되면 캐시 히트율이 떨어집니다. 캐시가 무료처럼 보여도 주의력 저하와 처리 속도 저하는 여전히 발생합니다. 긴 프리픽스를 재사용하더라도 계산량 자체는 줄어들지 않으니까요. 캐시 효율과 압축 효율을 동시에 측정하고, 둘 중 하나만 최적화하지 않는 것이 원칙입니다.

도구 로딩 최소화

80개 이상의 도구 정의를 컨텍스트에 한꺼번에 올릴 필요가 있는지 재고합니다.

작업별로 필요한 도구만 동적으로 로드합니다. MCP 서버 대신 CLI 앱으로 대체할 수 있는 경우, CLI가 토큰을 훨씬 적게 씁니다. (예: GitHub CLI vs GitHub MCP) 도구 정의의 과잉은 출력 압축과는 별개의 문제이며, 둘 다 해결해야 하죠.

측정 없이 최적화 없다

컨텍스트 소비를 시각화하고 추적하는 계측 레이어를 반드시 갖춰야 합니다.

추적해야 할 지표는 다음과 같습니다:

세션별 사용량 분석도구별, 프로젝트별 토큰 소비 패턴을 추적하여 효율성 측정
캐시 읽기/생성 비율캐시 재사용률과 새로운 캐시 생성 비율로 최적화 수준 파악
압축 효과 비교압축 전후 토큰 소비량을 비교하여 압축 기술의 효율성 검증
컨텍스트 잔여율 변화시간 경과에 따른 잔여 컨텍스트 비율 추이로 세션 지속성 분석

AI 토큰 사용량 분석 지표

측정 도구 예시로 `~/.claude/projects/*/*.jsonl`을 파싱해서 세션·도구·타임라인별 비용을 분석하는 방식이 있습니다.

요약: 판단 기준 체크리스트

도구 출력이 1KB를 넘으면 샌드박스 격리 후 stdout만 전달합니다. 1KB 미만이면 직접 컨텍스트에 포함하고, 구조화된 데이터와 자연어가 혼합된 검색에서는 하이브리드 검색을 씁니다. 독립적으로 해결 가능한 하위 작업은 서브에이전트로 포크해서 결과만 받습니다.

디버깅 완료 후 남은 로그는 백트래킹으로 컨텍스트에서 제거합니다. 세부 정보가 필요할 수도 있는 대량 데이터는 요약을 먼저 하고 드릴다운 경로를 확보하세요. 도구 수가 80개를 넘으면 동적 로딩이나 CLI 대체를 검토하고, 최적화 효과를 검증할 때는 토큰 사용량·캐시 히트율·추론 품질을 동시에 측정해야 합니다.

이 지침은 Context Mode 프로젝트 분석을 기반으로 작성되었습니다. 2026년 2월 기준입니다.