AI & Tools

[AI 컨텍스트 #4] CLAUDE.md는 왜 짧아야 할까, AI 에이전트 상시 로드 컨텍스트 설계법

3편에서 /clear로 대화 이력을 비우는 법을 봤습니다. 그런데 /clear 직후 컨텍스트 잔량을 확인해 보면 100%가 아닙니다. Claude Code에서 /context 명령을 쳐보면 이유가 보여요. 시스템 프롬프트, 도구 정의, CLAUDE.md, MCP 서버가 등록한…

이석우iOS Developer7분 읽기
[AI 컨텍스트 #4] CLAUDE.md는 왜 짧아야 할까, AI 에이전트 상시 로드 컨텍스트 설계법 대표 이미지

3편에서 /clear로 대화 이력을 비우는 법을 봤습니다. 그런데 /clear 직후 컨텍스트 잔량을 확인해 보면 100%가 아닙니다. Claude Code에서 /context 명령을 쳐보면 이유가 보여요. 시스템 프롬프트, 도구 정의, CLAUDE.md, MCP 서버가 등록한 도구들이 이미 수만 토큰을 차지하고 있습니다. 대화를 시작하기도 전에요.

이번 편은 이 “상시 로드 컨텍스트”를 다룹니다. 대화 이력이 변동비라면 이쪽은 고정비입니다. 매 턴 빠짐없이 실려 가고, /clear로도 사라지지 않으며, 세션 내내 모델의 주의력 일부를 점유합니다. 고정비 설계가 부실하면 어떤 세션이든 시작부터 손해를 안고 출발하는 셈이라 대화 관리보다 먼저 손봐야 할 곳이기도 합니다.

매 턴 짊어지고 가는 고정비, 배낭이 무거우면 어떤 세션도 손해로 출발합니다
매 턴 짊어지고 가는 고정비, 배낭이 무거우면 어떤 세션도 손해로 출발합니다

세션 시작 전에 이미 실려 있는 것들

에이전트의 컨텍스트 윈도우는 빈 종이로 시작하지 않습니다. 첫 사용자 입력이 도착하기 전에 이미 몇 개 층이 깔려 있어요.

맨 아래는 시스템 프롬프트입니다. 에이전트 하네스(Claude Code 같은 실행 환경)가 심는 기본 지침으로, 도구 사용 규칙이나 응답 형식 같은 내용이 수천 토큰 규모로 들어갑니다. 사용자가 건드릴 수 없는 영역이죠.

그 위에 도구 정의가 올라갑니다. 모델이 도구를 쓰려면 각 도구의 이름, 설명, 파라미터 스키마를 알아야 하고, 이게 전부 컨텍스트에 텍스트로 들어갑니다. 기본 도구만 있으면 부담이 크지 않은데, MCP 서버를 연결하기 시작하면 이야기가 달라져요. 서버 하나가 도구 수십 개를 등록하는 경우가 흔하고, 서버 몇 개만 연결해도 도구 정의만으로 수만 토큰이 나갑니다. 한 번도 안 쓸 도구들이 매 턴 왕복합니다.

마지막이 CLAUDE.md 같은 프로젝트 지침 파일입니다. 전역 설정, 프로젝트 설정, 하위 디렉터리 설정까지 자동으로 로드되는데, 이 층이 사용자가 직접 설계할 수 있는 유일한 층입니다.

CLAUDE.md의 원칙, 항상 참인 것만 짧게

CLAUDE.md에 뭘 넣을지의 판단 기준은 하나입니다. 이 내용이 “이 프로젝트의 모든 작업에서 항상 참인가”. 매 턴, 모든 작업에 실려 가는 파일이니 어떤 작업에는 맞고 어떤 작업에는 무관한 내용이라면 자리 값을 못 합니다.

빌드·테스트 명령어, 코드베이스의 큰 구조, 어기면 안 되는 소수의 규칙. 이런 것들이 합격선을 넘습니다. 반대로 특정 기능의 상세 스펙, 라이브러리 사용법 전문, 과거 작업 기록 같은 건 해당 작업을 할 때만 필요한 정보라 탈락이에요.

길이에 대해서는 역설이 하나 있습니다. 지침을 많이 적을수록 잘 지켜질 것 같지만 실제로는 반대에 가깝습니다. 2편에서 본 대로 컨텍스트가 길어지면 개별 항목에 돌아가는 주의가 옅어지고, 수백 줄짜리 지침 파일에서는 정작 중요한 규칙이 lost in the middle로 묻힙니다. 규칙 50개를 적으면 50개가 다 흐릿하게 지켜지고, 10개를 적으면 10개가 또렷하게 지켜지는 쪽에 가까워요. 에이전트가 CLAUDE.md의 규칙을 자꾸 어긴다면, 규칙을 늘리기 전에 파일을 줄이는 게 맞는 순서일 수 있습니다.

상시 로드 3층 중 직접 설계할 수 있는 층은 CLAUDE.md뿐입니다
상시 로드 3층 중 직접 설계할 수 있는 층은 CLAUDE.md뿐입니다

전부 싣지 말고 포인터만 실어라

그럼 합격선에서 탈락한 정보들, 그러니까 가끔 필요한 상세 문서는 어디에 둬야 할까요. 답은 “컨텍스트 밖에 두고, 위치만 알려준다”입니다.

CLAUDE.md에 데이터베이스 마이그레이션 절차 전문을 싣는 대신 “마이그레이션 절차는 docs/migration.md 참고”라고 한 줄만 적는 방식이에요. 에이전트는 마이그레이션 작업을 할 때만 그 파일을 읽습니다. 상세 내용은 필요한 세션의 컨텍스트에만 올라가고, 무관한 세션은 한 줄짜리 포인터 비용만 냅니다.

같은 원리를 체계화한 것이 Claude Code의 스킬(skill)입니다. 스킬은 특정 작업의 절차서인데, 평소에는 이름과 한 줄 설명만 컨텍스트에 올라가 있다가 해당 작업이 시작될 때 본문이 로드됩니다. “배포 절차”를 CLAUDE.md에 상주시키는 대신 스킬로 만들면, 배포하지 않는 99%의 턴에서 그 토큰을 아끼는 거죠.

도구 쪽도 정리 대상입니다. 연결해 두고 안 쓰는 MCP 서버가 있다면 끄는 것만으로 수만 토큰의 고정비가 사라집니다. 도구 정의를 평소에는 이름만 두고 필요할 때 전체 스키마를 로드하는 지연 로딩을 지원하는 하네스도 늘고 있는데, 방향은 같습니다. 모든 것을 항상 싣는 대신, 필요한 것을 필요할 때 싣는 겁니다.

벽에는 항상 참인 규칙 몇 줄만, 상세 매뉴얼은 선반에 두고 필요할 때 꺼냅니다
벽에는 항상 참인 규칙 몇 줄만, 상세 매뉴얼은 선반에 두고 필요할 때 꺼냅니다

고정비 점검 루틴

상시 로드 컨텍스트는 한번 부풀면 눈치채기 어렵습니다. 매 세션 똑같이 나가는 비용이라 비교 대상이 없거든요. 그래서 가끔 의식적으로 점검할 가치가 있습니다.

Claude Code라면 /context로 현재 컨텍스트가 어디에 얼마나 쓰이는지 분해해서 볼 수 있습니다. 시스템 프롬프트, 도구, MCP, 메모리 파일별로 토큰이 표시되니 여기서 도구 정의가 대화보다 큰 기형이 보이면 MCP 서버부터 정리하면 됩니다. CLAUDE.md는 분기마다 한 번쯤 열어서 “지난 달에 이 줄이 실제로 도움이 된 적 있나”를 기준으로 줄을 지웁니다. 지침 파일은 방치하면 자라기만 하는 성질이 있어서 가지치기를 루틴으로 만들어야 짧게 유지됩니다.

정리

  • 시스템 프롬프트, 도구 정의, CLAUDE.md는 매 턴 실려 가는 고정비입니다. /clear로도 사라지지 않으니 대화 관리 이전에 설계해야 합니다.
  • CLAUDE.md의 기준은 “모든 작업에서 항상 참인가”입니다. 길수록 개별 규칙이 흐려지므로, 규칙이 안 지켜지면 파일을 줄이는 게 먼저입니다.
  • 상세 문서는 본문 대신 포인터만 싣고, 반복 절차는 스킬로 분리하고, 안 쓰는 MCP 서버는 끕니다. 필요한 것을 필요할 때만 싣는 게 원칙입니다.

여기까지 하면 세션 하나의 컨텍스트는 꽤 깨끗해집니다. 그런데 아무리 아껴도 큰 작업 하나가 세션 하나에 안 들어가는 순간이 옵니다. 다음 편은 이때 쓰는 구조적 해법, 서브에이전트입니다. 탐색은 다른 컨텍스트에 시키고 결론만 받아오는 격리 패턴이 어떻게 컨텍스트를 지키는지 봅니다.

함께 보면 좋은 글