Claude Code가 당신의 CLAUDE.md를 무시하는 이유 (그리고 해결 방법)
Source: Dev.to
Claude Code가 CLAUDE.md에 정성스럽게 작성한 규칙을 무시하는 것을 본 적이 있다면, 그것은 상상이 아닙니다. 저는 설정 파일에 지시문을 추가하는 데 몇 시간을 보냈지만, Claude가 제가 하지 말라고 한 정확한 행동을 계속하는 모습을 지켜볼 수밖에 없었습니다.
1. 파일이 너무 깁니다
Claude Code는 약 80줄 정도부터 선택적으로 내용을 무시하기 시작합니다. 이것은 버그가 아니라 LLM이 지시를 처리하는 방식의 근본적인 제한입니다. 최첨단 모델은 대략 150개의 지시를 안정적으로 따를 수 있습니다. 이를 초과하면 모델은 무엇에 주의를 기울여야 할지 판단을 내리기 시작합니다.
대부분의 CLAUDE.md 파일은 100–200줄 이상입니다. 제 파일은 140줄이었습니다. 이것이 문제라는 사실을 몰랐습니다.
Fix
CLAUDE.md 파일을 80줄 이하로 유지하세요. 모든 줄은 “이 줄을 제거하면 Claude가 실수를 할까요?”라는 질문에 답해야 합니다. 그렇지 않다면 삭제하세요.
2. 모순되는 지시가 있습니다
파일의 한 섹션에서는 “들여쓰기에 탭 사용”이라고 적혀 있고 다른 섹션에서는 “2‑칸 들여쓰기 사용”이라고 적혀 있다면, Claude는 두 가지를 모두 따를 수 없으므로 종종 둘 다 무시합니다. 이러한 모순은 특히 여러 사람이 시간에 걸쳐 편집한 긴 파일에서 수동으로 찾기 어렵습니다.
해결책
파일에 충돌하는 규칙이 있는지 감사하십시오. 코드 스타일, 테스트 요구사항, 워크플로우 지시사항에 특히 주의하십시오.
3. 성격 라인에 토큰을 낭비하고 있습니다
이와 같은 라인은 매우 흔합니다:
You are a senior software engineer.
Be concise, helpful, and professional.
Think step by step carefully.
Always write clean, high-quality code.그들은 거의 아무 효과가 없습니다. Claude Code는 이미 강력한 시스템‑레벨 지시를 내장하고 있습니다. 성격 라인은 행동을 바꾸지 않으면서 토큰을 낭비하고, 더 나아가 실제 중요한 지시를 파일 아래쪽으로 밀어냅니다.
해결 방법
Claude에게 프로젝트에 대한 구체적이고 실행 가능한 정보를 제공하지 않는 모든 라인을 삭제하세요.
4. [@file] 참조를 잘못 사용하고 있습니다
CLAUDE.md에 @docs/architecture.md를 작성하면 해당 파일 전체가 모든 세션에 삽입됩니다. 이렇게 하면 컨텍스트 창이 즉시 부풀어 실제 작업을 위한 공간이 줄어듭니다.
해결 방법
파일을 삽입하는 대신, Claude에게 언제 읽어야 하는지 알려주세요:
For architecture questions, see docs/architecture.md
For API integration issues, see docs/stripe-guide.md당신의 CLAUDE.md는 얼마나 나쁜가요?
나는 이 모든 것을 배운 뒤 내 파일을 평가했다: 34/100 – 등급 F. 내가 괜찮다고 생각한 파일에 오류 4개와 경고 11개가 있었다.
모든 것을 수정한 뒤: 91/100 – 등급 A. Claude의 동작이 눈에 띄게 바뀌었다—테스트 요구사항을 무시하던 것이 멈추고 워크플로우 지시를 일관되게 따르기 시작했다.
이 분석을 자동화하기 위해 CLI 도구를 만들었다:
pip install agentlint-dev
agentlint score CLAUDE.md출력:
Score: 34/100 Grade: F — Critical Issues
Length & Density 0/25
Specificity 19/25
Structure 10/25
Completeness 5/25모순, 토큰 낭비, 중복 규칙, 누락된 명령, @file 남용 등을 잡아낸다. CLAUDE.md, AGENTS.md, 그리고 Cursor 규칙에서도 작동한다.
최소 CLAUDE.md 템플릿
새로 시작하고 싶다면, 가장 높은 점수를 받는 구조는 다음과 같습니다:
# Project
[2‑3 sentences: what this project does]
# Stack
[language, framework, key libraries]
# Commands
- Test: npm test
- Build: npm run build
- Lint: npm run lint
# Rules
- [specific rule 1]
- [specific rule 2]
# Never
- [thing Claude should never do]
# Verify
After changes, run tests and confirm they pass before marking done.- 80줄 이하.
- 성격 지시 없음.
- 구체적인 명령어.
- 명확한 규칙.
이것이 90점 이상 점수가 어떻게 보이는지입니다. 당신의 CLAUDE.md 점수는 얼마인가요? agentlint를 실행하고 댓글로 알려주세요.