`CLAUDE.md`는 Claude Code가 특정 프로젝트에서 효과적으로 작동하도록 돕는 중요한 파일입니다. 그러나 CLAUDE.md 작성 시 불필요하거나 과도한 정보를 포함하면 오히려 Claude의 성능을 저하시키고 개발 과정을 방해할 수 있습니다. 이 글에서는 `CLAUDE.md`에 포함하면 역효과를 내는 요소들을 구체적으로 설명합니다.
200줄을 초과하는 장황한 규칙
`CLAUDE.md` 파일이 과도하게 길어지면 Claude가 핵심 지시를 파악하는 데 어려움을 겪을 수 있습니다. Anthropic은 `CLAUDE.md`를 200줄 이하로 유지할 것을 권장하며, 300줄을 초과하는 경우 단순화가 필요하다는 신호로 간주됩니다. 긴 설명문은 컨텍스트 비대화를 유발하여 중요한 지침이 희석될 수 있습니다.
컨텍스트 비대화와 정보 과부하
긴 설명문은 Claude가 한 번에 처리할 수 있는 토큰 예산을 불필요하게 소모합니다. 이는 Claude가 실제 작업에 필요한 정보를 파악하는 시간을 늘리고, 지시 준수율을 떨어뜨리는 결과를 초래할 수 있습니다. 핵심 지침은 짧고 명확하게 작성해야 합니다.
린트, 포맷, 임포트 순서 등 스타일 관련 규칙
코드 스타일, 포맷팅, 임포트 순서와 같은 규칙은 `CLAUDE.md`에 포함하지 않는 것이 좋습니다. 이러한 lint leakage는 전용 도구(예: Prettier, ESLint)로 처리해야 토큰과 지시 예산을 낭비하지 않습니다. Claude에게 이러한 작업을 지시하는 것은 비효율적이며, 실제 코드 로직에 집중해야 할 자원을 분산시킵니다.
도구와 역할 분리
개발 과정에서 스타일 및 포맷팅은 자동화된 도구의 역할입니다. `CLAUDE.md`는 Claude Code의 사고방식, 작업 범위, 검증 기준 등 핵심적인 개발 지침을 전달하는 데 집중해야 합니다. 각 역할에 맞는 도구를 사용하는 것이 전체 워크플로우의 효율성을 높입니다.
중복되거나 상충하는 지침
`CLAUDE.md` 내에 중복되거나 서로 상충하는 지침이 포함되면 Claude는 어떤 규칙을 우선시해야 할지 혼란을 겪을 수 있습니다. 연구 결과에 따르면 `conflicting instructions`는 Claude의 오작동을 유발하는 주요 원인 중 하나로 지적됩니다. 명확하고 일관된 지침만이 Claude의 정확한 작업을 보장합니다.
일관성 유지의 중요성
지침 간의 일관성을 유지하는 것은 Claude가 예측 가능한 방식으로 작업을 수행하도록 돕습니다. 여러 사람이 `CLAUDE.md`를 작성하거나 수정할 경우, 충돌하는 지침이 발생하기 쉬우므로 정기적인 검토와 조정을 통해 이를 방지해야 합니다.
자주 변경되는 절차나 임시 규칙
자주 바뀌는 절차나 특정 시점에만 유효한 임시 규칙을 `CLAUDE.md`에 고정 지침처럼 포함하는 것은 비효율적입니다. 이러한 항목은 `CLAUDE.md`를 불필요하게 복잡하게 만들고, 업데이트가 빈번하여 관리가 어렵습니다. 이번 달 자료에서는 이런 항목을 hooks나 전용 검증 도구로 옮길 것을 권장합니다.
유연한 관리 방안 모색
변동성이 높은 정보는 별도의 문서나 프로젝트 관리 시스템에서 관리하는 것이 효과적입니다. `CLAUDE.md`는 프로젝트의 핵심적인 개발 원칙과 불변적인 지침에 집중하여 안정성을 유지해야 합니다.
특정 작업에만 필요한 세부 규칙
특정 작업 흐름이나 기능 개발에만 필요한 세부 규칙을 `CLAUDE.md` 전체에 적용하는 것은 비효율적입니다. 이러한 지침은 `CLAUDE.md`보다 별도 파일이나 조건부 규칙으로 분리하는 것이 권장됩니다. 모든 상황에 적용되지 않는 상세 규칙은 Claude의 일반적인 작업 흐름을 방해할 수 있습니다.
필요에 따른 정보 분할
프로젝트의 규모가 커지거나 다양한 유형의 작업이 포함될 경우, 모든 규칙을 하나의 `CLAUDE.md` 파일에 담기보다 역할이나 작업 유형에 따라 정보를 분할하는 것이 효율적입니다. 예를 들어, 특정 기능 개발 지침은 해당 기능의 README 파일에 포함할 수 있습니다.
빌드, 테스트, 코딩 규약의 과도한 상세 설명
빌드 과정, 테스트 방법론, 특정 코딩 규약에 대한 과도하게 상세한 설명은 `CLAUDE.md`에 포함하지 않는 것이 좋습니다. 이러한 역량 누출(skill leakage)은 Claude가 실제 코딩 로직과 문제 해결에 집중해야 할 에너지를 분산시킵니다. 필요한 경우 설명적인 이름의 별도 마크다운 파일로 나누는 것이 바람직합니다.
LLM의 지시 준수 한계 고려
Claude와 같은 LLM은 지시가 많아질수록 지시 준수 한계에 도달할 수 있습니다. 너무 많은 세부 규칙은 실제로 읽히지 않거나, Claude가 중요도를 판단하는 데 혼란을 줄 수 있습니다. 핵심은 “많이 쓰는 것”이 아니라 “생각 방식, 작업 범위, 검증 기준”을 짧고 명확하게 적는 것입니다.
CLAUDE.md 작성 시 피해야 할 항목 요약
`CLAUDE.md`를 효과적으로 활용하기 위해서는 다음과 같은 항목들을 피해야 합니다. 이 지침들은 Claude가 불필요한 작업에 에너지를 낭비하지 않고 핵심 업무에 집중하도록 돕습니다.
`CLAUDE.md`는 항상 강제되는 시스템 프롬프트가 아니라 사용자 메시지처럼 전달됩니다. 따라서 Claude는 현재 작업과 관련 없다고 판단되는 일부 지시를 건너뛸 수 있습니다. 따라서 CLAUDE.md 작성 시 핵심적인 지침에 집중하는 것이 중요합니다.
자주 묻는 질문
`CLAUDE.md`와 `AGENTS.md`는 어떤 차이가 있습니까?
`CLAUDE.md`는 프로젝트 전체의 일반적인 개발 지침을 담는 반면, `AGENTS.md`는 특정 에이전트의 역할과 행동 방식을 정의하는 데 사용됩니다.
`CLAUDE.md`가 너무 길면 어떤 문제가 발생합니까?
`CLAUDE.md`가 200줄을 초과하여 길어지면 Claude가 핵심 지시를 파악하는 데 어려움을 겪고, 컨텍스트 비대화로 인해 성능이 저하될 수 있습니다.
`CLAUDE.md`에 어떤 규칙을 넣어야 가장 효과적입니까?
Claude의 “생각 방식, 작업 범위, 검증 기준”을 짧고 명확하게 정의하는 규칙이 가장 효과적입니다.