CLAUDE.md는 짧을수록 잘 지켜진다 — LLM을 잘 쓰는 법 (2)

규칙을 더 많이 적어 둘수록 에이전트가 더 잘 따를 것 같다. 그래서 CLAUDE.md(또는 시스템 지침)에 "항상 이렇게 해라" 항목을 한 줄씩 쌓는다. 그런데 어느 순간, 정작 제일 중요한 규칙 하나를 에이전트가 무시하기 시작한다. 더 세게 말하려고 "반드시", "중요", "절대"를 여기저기 붙인다. 그래도 안 지켜진다.

이건 에이전트가 반항하는 게 아니다. 지시를 늘릴수록 준수율이 떨어지는 것은 LLM의 구조에서 나오는 역설이다. 1편에서 "컨텍스트는 희소한 예산"이라는 명제를 다뤘는데, CLAUDE.md는 그 예산을 매번 먼저 먹고 들어가는 특수한 입력이다. 그래서 여기엔 반대 방향의 규율이 필요하다 — 더하기가 아니라 빼기.

무슨 일이 벌어지나

CLAUDE.md는 모든 요청 앞에 자동으로 실린다. 처음 몇 줄일 때는 잘 지켜지다가, 수십 줄로 불어나면 희한한 일이 생긴다. 새로 추가한 규칙은 물론, 옛날에 잘 지켜지던 규칙까지 흐려진다. "왜 분명히 적어놨는데 무시하지?" 싶은 상황. 강조 표시를 덧붙여도 나아지지 않고, 때로는 더 나빠진다.

왜 그런가 — LLM의 작동 원리

세 가지가 겹친다.

첫째, CLAUDE.md는 매 세션의 고정비다. 이 파일은 대화마다 프리픽스로 다시 실린다. Anthropic 문서 기준 전형적인 프로젝트 파일이 약 1,800토큰. 길수록 모든 대화가 시작하기도 전에 예산을 그만큼 까먹고 들어간다. 그리고 1편에서 봤듯 예산이 차면 뒤쪽 지시가 밀려난다.

둘째, 어텐션은 제로섬이라 규칙이 희석된다. 트랜스포머는 다음 토큰을 만들 때 모든 토큰을 참조하되 그 총량이 1로 고정돼 있다. 규칙이 10줄일 때와 100줄일 때, 각 규칙이 받는 어텐션 몫은 후자가 훨씬 작다. 더 결정적인 건 강조다. "IMPORTANT"는 상대적 살리언스 신호인데, 여러 줄에 다 붙이면 분포가 다시 균일해져 아무것도 튀지 않는다. 전부 강조하면 강조가 사라진다.

셋째, 긴 문서의 중간은 잘 안 읽힌다. "lost in the middle" — 모델은 컨텍스트의 앞뒤를 강하게 참조하고 중간은 회수 신뢰도가 떨어진다. CLAUDE.md가 길어지면 중간에 묻힌 규칙은 물리적으로 존재해도 실질적으로 약하다.

Anthropic도 자사 문서에서 못박는다 — "비대한 CLAUDE.md는 실제 지시를 무시하게 만든다." 즉 규칙을 더 넣는 것이 더 강한 준수를 보장하지 않는다. 오히려 그 반대다.

그래서 어떻게 써야 하나 — 코드처럼 가지치기하라

CLAUDE.md는 쌓는 문서가 아니라 가지치는 문서다. 코드 리뷰하듯 줄마다 존재 이유를 묻는다.

• 각 줄에 "이걸 지우면 에이전트가 실수하나?"를 묻는다. 아니면 지운다. 이 질문 하나가 대부분의 줄을 걸러낸다.
• 추측 불가능한 것만 남긴다. 비표준 빌드 명령, 기본값과 다른 컨벤션, 반복해서 밟는 함정. 반대로 코드를 읽으면 알 수 있는 것(모델 필드, API 경로, 쓰는 라이브러리)은 넣지 마라 — 에이전트가 스스로 유도한다.
• 200줄을 상한으로 둔다. 넘어가면 가지치기 신호다.
• 강조는 계속 무시되는 규칙 딱 하나에만. 두 개 이상 강조하는 순간 효과가 꺾인다.
• 가끔만 필요한 지식은 상시 로드하지 마라. 특정 상황에서만 쓰는 규칙은 그 상황에서만 불러오는 게 맞다(경로 스코프·온디맨드).

RoutineCode도 같은 원리 위에 있다

마지막 항목 — "가끔 필요한 지식은 상시 로드하지 마라" — 이 바로 RoutineCode가 순정 Claude Code 위에 한 겹 더하는 지점이다.

순정 환경에서 프로젝트 지식을 에이전트에 주는 통로는 사실상 CLAUDE.md 하나다. 그러다 보니 "이 테넌트는 동시접속 제한이 있다", "이 외부 API는 초과 호출 시 차단된다" 같은 맥락별 지식까지 전부 그 한 파일에 쌓이고, 파일은 비대해지며, 정작 그 지식이 필요 없는 99%의 작업에서도 매번 실려 예산과 살리언스를 깎아먹는다.

RoutineCode는 이런 지식을 상시 로드로 밀어넣는 대신 지속 메모리에 저장하고, 관련 파일을 건드릴 때만 컨텍스트로 소환한다. "항상 싣기"가 아니라 "필요할 때만 싣기"다. 결과적으로 상시 지침(CLAUDE.md)은 짧고 가볍게 유지되면서, 맥락별 지식은 정작 그 맥락이 활성화된 순간에만 등장해 그 순간의 살리언스가 높다. 당신이 CLAUDE.md를 가지치는 것과 RoutineCode가 지식을 온디맨드로 미루는 것은 같은 목적 — 상시 프리픽스를 가볍게 유지하는 것 — 을 위한 두 방향의 노력이다.

기대효과와 결과

• 핵심 규칙 준수율이 오른다. 희석과 중간 소실이 줄어 중요한 규칙이 실제로 작동한다.
• 매 세션 고정비가 준다. 프리픽스가 가벼워져 실제 작업에 쓸 예산이 늘어난다.
• "강조 남발 → 무시"의 악순환에서 벗어난다. 단 하나의 강조가 다시 힘을 가진다.

규칙을 더 적는 것은 직관적이지만 틀린 본능이다. 상시 로드되는 지침일수록, 잘 지켜지게 만드는 길은 짧게 유지하는 것이다.

---

이 글은 "LLM을 잘 쓰는 법" 시리즈의 2편이다. 다음 편에서는 넓은 탐색의 비용을 메인 대화가 아니라 별도의 창으로 밀어내는 법 — 리서치를 격리해 결론만 받는 패턴 — 을 다룬다.

참고 자료

• Best practices for Claude Code — Anthropic
• Explore the context window — Anthropic