피드로 돌아가기
Your CLAUDE.md is too long — and that's why Claude Code ignores it
Dev.toDev.to
AI/ML

LLM 지시문 예산 최적화를 통한 규칙 준수율 80%에서 100%로 향상

Your CLAUDE.md is too long — and that's why Claude Code ignores it

Penloom Studio2026년 6월 27일6intermediate

Context

CLAUDE.md 파일에 과도한 규칙을 추가함에 따라 모델의 Attention 분산 및 지시 준수율 저하 문제 발생. LLM의 Instruction-following 능력이 한정된 자원(Budget)으로 작동한다는 물리적 제약으로 인한 병목 지점 파악.

Technical Solution

  • Instruction Budget 관점을 도입하여 전체 규칙 수를 150~200개 이내로 제한하는 최적화 수행
  • 단순 가이드라인(Advisory)과 강제 규칙(Deterministic)을 분리하여 접근 방식 차별화
  • 반드시 준수해야 하는 핵심 규칙을 Prose 형태에서 Shell Command 기반의 Hook 구조로 전환하여 실행 보장
  • 규칙 기술 시 단순 명령어가 아닌 근거(Reason)를 포함하여 모델의 추론 및 일반화 성능 강화
  • 빈번하게 사용되지 않는 세부 지침을 별도 파일로 분리하고 경로만 참조하는 Progressive Disclosure 아키텍처 적용
  • PreToolUse Hook을 통한 파일 쓰기 전 유효성 검증 및 Exit Code 2를 활용한 모델 피드백 루프 구축

- CLAUDE.md 내 전체 라인 수가 150행을 초과하는지 확인하고 불필요한 규칙 삭제 - 보안 및 치명적 오류 방지 규칙을 Prose에서 Shell Hook으로 전환 검토 - 모든 규칙에 '왜 이 규칙이 필요한지'에 대한 논리적 근거 추가 - 도메인 특화 세부 지침을 외부 파일로 분리하고 필요한 시점에만 참조하도록 구조 변경

원문 읽기