CLAUDE.md와 AGENTS.md에 규칙을 더할수록 명령을 잘 따르지 않는 이유와 해결법

CLAUDE.md나 AGENTS.md에 규칙을 추가할수록 에이전트가 오히려 말을 안 듣는 경험을 해봤을 겁니다. 규칙이 부족해서가 아닙니다. 지침이 많아질수록 모델이 지침을 따르는 능력 자체가 떨어지기 때문입니다. 이 글에서는 그 한계를 정량화한 '지침 예산(instruction budget)' 개념을 소개하고, 예산 안에서 CLAUDE.md·AGENTS.md를 설계하는 방법을 정리합니다.

규칙 파일이 진흙 덩어리가 되는 악순환

지침 파일이 비대해지는 경로는 어느 팀이나 비슷합니다. 에이전트가 마음에 안 드는 행동을 하면 규칙을 하나 추가합니다. 이 과정을 몇 달간 반복하면 파일은 수백 줄짜리 '진흙 덩어리(ball of mud)'가 됩니다.¹ 여러 개발자가 서로 모순되는 의견을 넣고 아무도 전체를 정리하지 않으면, 규칙 파일은 에이전트를 돕는 자산이 아니라 성능을 깎는 부채로 변합니다.

상당수 사람들이 규칙이 많을수록 에이전트가 더 내가 원하는 대로 동작할 것이라 예상합니다. 하지만 그렇지 않습니다. 모델이 따를 수 있는 지침의 총량에 한계가 있기 때문입니다.

모델은 몇 개의 지침까지 따를 수 있는가

2025년 7월 발표된 논문 "How Many Instructions Can LLMs Follow at Once?"는 이 질문을 IFScale이라는 벤치마크로 정량화했습니다.² 보고서를 작성하는 과제를 구성하고, 키워드 포함 지침을 10개에서 500개까지 늘려가며 주요 7개 업체의 모델 20종을 평가했는데, 결과는 명확했습니다. 지침이 500개에 이르면 최상위 프런티어 모델도 정확도가 68%까지 떨어진다는 사실이었습니다.

이 결과를 실무 지침으로 번역한 사람이 HumanLayer의 Kyle입니다. 추론형 프런티어 모델이 합리적인 일관성으로 따를 수 있는 지침은 약 150~200개라는 것입니다.³ 더 작은 모델이나 비추론 모델은 이보다 적습니다.

여기서 중요한 함의가 두 가지 나옵니다.

첫째, 예산은 이미 일부 소진된 상태로 시작합니다. Claude Code의 시스템 프롬프트에는 약 50개의 개별 지침이 들어 있습니다.³ 여기에 도구 정의, MCP 서버 설정, 플러그인이 각자 지침을 보탭니다. CLAUDE.md에 쓸 수 있는 실질 예산은 100~150개 남짓인 셈입니다.

둘째, 예산을 초과하면 특정 규칙만 무시되는 게 아닙니다. 논문이 관찰한 저하 양상은 균등 저하입니다. 지침 수가 늘어나면 모든 지침의 준수 품질이 고르게 떨어집니다. 새로 추가한 200번째 규칙만 무시되는 게 아니라, 잘 지켜지던 10번째 규칙까지 흔들립니다. 규칙을 추가했는데 예전에 없던 실수가 생기는 이유가 여기에 있습니다. 앞쪽에 배치된 지침일수록 잘 지켜지는 편향(primacy bias)도 확인됐으니, 지침을 어디에 넣어야 할지 역시 설계해야 합니다.

예산 안에서 설계하기

루트 파일은 최소한으로

CLAUDE.md·AGENTS.md의 모든 토큰은 관련 여부와 상관없이 매 요청에 로드됩니다. 그래서 루트 파일에 남길 내용의 기준은 '모든 작업에 보편적으로 필요한가'입니다. 이 기준을 통과하는 항목은 생각보다 적습니다.

• 한 문장짜리 프로젝트 설명

• 패키지 매니저(npm이 아닌 경우)

• 빌드·타입체크 명령어(표준이 아닌 경우)

반대로 빼야 할 것은 명확합니다. "깨끗한 코드를 작성하라", "엣지 케이스를 처리하라" 같은 지침은 모델이 이미 아는 내용이라 예산만 낭비합니다. 코드 스타일 세부 규칙이나 특정 작업에만 필요한 지침도 루트 파일에 둘 이유가 없습니다.

파일 경로 대신 도메인 개념을 문서화

디렉터리 구조를 문서화하고 싶은 유혹은 크지만 위험합니다. 문서를 신경 써서 관리하지 않으면 금방 코드 대비 뒤처지기 때문입니다. 낡은 정보는 컨텍스트를 오염시키기만 합니다.¹ 경로가 바뀐 뒤에도 에이전트는 문서를 믿고 엉뚱한 위치를 찾아가기 때문에 차라리 구조 대신 기능을 설명하고, 구체적인 위치는 에이전트가 스스로 탐색하게 두는 편이 안전합니다. 'organization과 workspace의 관계' 같은 도메인 개념은 파일 경로보다 훨씬 안정적이라 문서화 가치가 높습니다. 조직에서 소통을 하다 보면 같은 용어도 해석을 다르게 해서 소통이 잘 안되는 경우가 많습니다. 코드와 에이전트도 마찬가지입니다.

점진적 공개로 예산을 아끼기

루트 파일에서 뺀 내용은 버리는 게 아니라 필요할 때만 로드되도록 옮깁니다. 이 기법을 점진적 공개(progressive disclosure)라 부릅니다. TypeScript 컨벤션 20개를 루트에 두는 대신 docs/TYPESCRIPT.md로 옮기고, 루트에는 참조 한 줄만 남기는 방식으로 점진적 공개 기법을 실현할 수 있습니다.

For TypeScript conventions, see docs/TYPESCRIPT.md

위와 같은 지침을 CLAUDE.md·AGENTS.md에 넣으면 TypeScript 작업을 할 때만 해당 규칙이 로드되고, 다른 작업에서는 지침 예산을 소비하지 않습니다. 참조 구조는 중첩할 수 있고(docs/TYPESCRIPT.md에서 docs/TESTING.md를 가리키는 식), 외부 문서로 연결할 수도 있습니다. 에이전트는 문서 계층을 탐색하는 데 능숙하므로 단서만 남겨두면 필요한 정보를 알아서 찾습니다.

모노레포에서는 범위별로 나누기

AGENTS.md는 루트에만 두는 파일이 아닙니다. 하위 디렉터리에도 배치할 수 있습니다. 여러분의 코딩 에이전트는 작업 위치에 따라 병합된 내용을 봅니다. 루트에는 모노레포의 목적과 공유 도구를, 각 패키지에는 해당 패키지의 목적·기술 스택·규칙을 두면 됩니다. 흩어진 지침도 에이전트는 작업의 종류에 따라 지침을 병합해서 따릅니다. 다만 병합된 파일 전체가 컨텍스트에 들어가므로 예산 관점은 동일합니다. 루트 경로에 있는 지침이든, 하위 경로에 있는 지침이든 비대해지면 안 됩니다.

이미 비대해진 파일 고치기

수백 줄짜리 규칙 파일을 손으로 정리할 필요는 없습니다. 리팩터링 자체를 에이전트에게 맡기면 됩니다. 아래는 aihero.dev의 가이드를 참고해 정리한 프롬프트입니다.¹

CLAUDE.md(또는 AGENTS.md)를 리팩터링해줘.

1. 서로 모순되는 지침을 찾아서 나열해줘. 어느 쪽을 유지할지는 내가 결정할게.
2. 루트 파일에 남을 필수 항목만 추출해줘.
   한 문장 프로젝트 설명, 패키지 매니저, 비표준 빌드·테스트 명령어.
3. 나머지 지침을 논리적 카테고리로 그룹화해줘.
   (예: TypeScript, 테스팅, API 설계, Git 워크플로)
4. 카테고리별로 docs/ 아래 별도 파일을 만들고,
   루트 파일에는 각 파일을 가리키는 참조만 남겨줘.
5. 중복되거나 너무 모호하거나 모델이 이미 아는 뻔한 지침
   ("깨끗한 코드를 작성하라" 같은)은 삭제 대상으로 표시해줘.

영어 프롬프트가 편하면 aihero.dev 가이드에 실린 원문을 그대로 사용해도 됩니다.

I want you to refactor my AGENTS.md file to follow progressive disclosure principles.

Follow these steps:

1. **Find contradictions**: Identify any instructions that conflict with each other. For each contradiction, ask me which version I want to keep.

2. **Identify the essentials**: Extract only what belongs in the root AGENTS.md:
   - One-sentence project description
   - Package manager (if not npm)
   - Non-standard build/typecheck commands
   - Anything truly relevant to every single task

3. **Group the rest**: Organize remaining instructions into logical categories (e.g., TypeScript conventions, testing patterns, API design, Git workflow). For each group, create a separate markdown file.

4. **Create the file structure**: Output:
   - A minimal root AGENTS.md with markdown links to the separate files
   - Each separate file with its relevant instructions
   - A suggested docs/ folder structure

5. **Flag for deletion**: Identify any instructions that are:
   - Redundant (the agent already knows this)
   - Too vague to be actionable
   - Overly obvious (like "write clean code")

한 가지 덧붙이면, 초기화 명령어(/init)나 스크립트로 CLAUDE.md·AGENTS.md를 자동 생성하는 방식은 피하는 편이 좋습니다. 자동 생성은 절제보다 포괄성을 우선하기 때문에 시작부터 예산을 초과한 파일을 만들어냅니다.

이 정리가 규모 있는 제품에서 어떤 성과로 이어지는지는 러버블 사례가 잘 보여줍니다. 비대해진 시스템 프롬프트를 전면 재정비해 응답 속도와 비용을 동시에 개선한 과정을 별도 글에서 다룹니다.

100% 지켜야 하는 규칙은 hook으로 강제하기

지침 예산을 지키면 준수 품질이 올라갑니다. 하지만 100%가 되지는 않습니다. Claude Code 공식 문서도 이 한계를 직접 인정합니다. CLAUDE.md는 모델이 참고하는 컨텍스트일 뿐 강제되는 설정이 아니며, 지침의 '엄격한 준수는 보장되지 않는다(there's no guarantee of strict compliance)'고 명시합니다.⁴ 아무리 잘 다듬은 규칙이라도 따를지 말지는 결국 모델이 판단합니다.

그래서 공식 문서는 반드시 지켜져야 하는 규칙을 지침이 아니라 hook으로 옮기라고 권합니다. hook은 커밋 직전이나 파일 수정 직후처럼 정해진 시점에 실행되는 셸 명령어입니다.⁵ 지침은 모델이 따를지 선택하지만 hook은 모델의 판단과 무관하게 항상 실행됩니다. 커밋 전 테스트 실행, 저장 후 포맷팅, 위험한 명령어 차단 같은 규칙이 여기에 해당합니다. hook으로 옮기면 지침 예산을 아끼면서 준수율은 100%로 만들 수 있습니다.

결국 규칙 파일을 줄이는 작업의 다음 단계는 hook 학습입니다. hook의 개념부터 정의하고 구현하는 방법, 실전에서 유용한 hook 모음까지 이 사이트의 Claude Code 튜토리얼 Hooks 장에서 단계별로 다룹니다.

정리

지침 예산은 취향의 문제가 아니라 측정된 한계입니다. 프런티어 모델 기준 150~200개, 시스템 프롬프트가 선점하는 몫을 빼면 실질적으로 100~150개입니다. 이 예산을 넘기는 순간 전체 지침의 준수 품질이 고르게 떨어지므로, 규칙을 추가해서 문제를 고치려는 시도가 오히려 새 문제를 만듭니다.

이상적인 규칙 파일은 작고, 집중되어 있고, 다른 곳을 가리킵니다. 에이전트가 작업을 시작하는 데 필요한 만큼만 담고, 세부 규칙은 점진적 공개에 맡기세요. 절대 어겨서는 안 되는 규칙은 지침이 아니라 hook으로 강제하세요. 규칙 파일을 줄이는 일은 에이전트 성능을 포기하는 게 아니라 회복하는 일입니다.

1. Matt Pocock, A Complete Guide To AGENTS.md, AI Hero.

   ↩

2. Daniel Jaroslawicz et al., How Many Instructions Can LLMs Follow at Once?, arXiv:2507.11538, 2025.

   ↩

3. Kyle (@0xblacklight), Writing a good CLAUDE.md, HumanLayer Blog, 2025.

   ↩

4. Anthropic, How Claude remembers your project, Claude Code Docs.

   ↩

5. Anthropic, Automate actions with hooks, Claude Code Docs.

   ↩