Claude Code에 코드 스타일 가이드를 자세히 알려줬는데 계속 무시하나요? 프로젝트 구조를 설명했는데 엉뚱한 곳을 뒤지나요? 문제는 AI가 아니라 CLAUDE.md 파일 작성법일 수 있습니다.
AI 개발 도구 HumanLayer가 효과적인 CLAUDE.md 작성법을 분석한 글을 발표했습니다. 핵심은 ‘많이 쓸수록 좋다’는 통념과 정반대입니다. LLM이 따를 수 있는 지시는 150-200개가 한계이며, 지시가 많아질수록 모든 지시의 수행률이 균등하게 떨어진다는 점이 중요합니다.
출처: Writing a good CLAUDE.md – HumanLayer Blog
LLM은 매번 백지상태로 시작한다
Claude나 GPT 같은 LLM은 상태를 저장하지 않습니다. 학습된 가중치는 고정되어 있고, 이전 대화를 기억하지 못하죠. Claude Code 같은 코딩 에이전트도 마찬가지입니다. 매 세션마다 당신의 코드베이스에 대해 아무것도 모르는 상태에서 시작합니다.
그래서 CLAUDE.md 파일이 중요합니다. 이 파일은 모든 대화에 자동으로 포함되는 유일한 파일이거든요. AI에게 코드베이스를 온보딩하는 역할을 합니다. 프로젝트가 무엇인지(WHAT), 왜 만들어졌는지(WHY), 어떻게 작업해야 하는지(HOW)를 알려주는 거죠.
Claude가 CLAUDE.md를 무시하는 진짜 이유
그런데 이상한 점이 있습니다. Claude는 종종 CLAUDE.md의 내용을 무시합니다. 우연이 아니에요. Anthropic이 의도적으로 그렇게 설계했거든요.
Claude Code는 CLAUDE.md 파일과 함께 다음과 같은 시스템 메시지를 AI에게 보냅니다:
“중요: 이 컨텍스트는 당신의 작업과 관련이 있을 수도, 없을 수도 있습니다. 현재 작업과 매우 관련성이 높지 않다면 이 컨텍스트에 응답하지 마세요.”
왜 이런 장치를 넣었을까요? 많은 사용자가 CLAUDE.md를 “AI가 이상하게 행동할 때마다 지시를 추가하는 곳”으로 사용했기 때문입니다. 특정 상황에만 필요한 지시들이 계속 쌓이면서 파일이 비대해졌고, 오히려 성능이 떨어지는 사례가 많았던 거죠. Anthropic은 보편적으로 적용되지 않는 지시는 무시하도록 해서 더 나은 결과를 얻었습니다.
지시의 한계: 150개를 넘기면 무너진다
최근 연구에 따르면 최신 LLM도 약 150-200개의 지시까지만 일관되게 따를 수 있습니다. 작은 모델은 더 적고, 추론 기능이 없는 모델은 훨씬 더 빨리 성능이 떨어집니다.
더 중요한 발견은 지시 개수가 늘어날수록 모든 지시의 수행률이 균등하게 떨어진다는 점입니다. 새로 추가한 지시만 무시되는 게 아니라, 기존 지시들도 함께 무시되기 시작하는 거예요.
Claude Code의 기본 시스템 프롬프트에는 이미 약 50개의 지시가 들어있습니다. 모델이 따를 수 있는 지시의 3분의 1을 이미 쓴 셈이죠. 여기에 플러그인, 스킬, 사용자 메시지까지 더하면 여유 공간은 더 줄어듭니다.
효과적인 CLAUDE.md 작성법
1. 짧게 쓰세요 – 60줄이면 충분합니다
HumanLayer팀의 CLAUDE.md 파일은 60줄이 안 됩니다. 일반적으로 300줄 이하를 권장하지만, 짧을수록 좋습니다. 모든 세션에 포함되는 파일이니까요.
데이터베이스 스키마 작성법 같은 특정 작업에만 필요한 내용은 넣지 마세요. 프론트엔드 작업할 때는 방해만 됩니다.
2. Progressive Disclosure: 필요할 때만 보여주세요
모든 정보를 CLAUDE.md에 넣는 대신, 별도 마크다운 파일로 분리하세요:
agent_docs/
|- building_the_project.md
|- running_tests.md
|- code_conventions.md
|- service_architecture.md그리고 CLAUDE.md에는 이 파일들의 목록과 간단한 설명만 포함하세요. Claude에게 필요한 파일을 스스로 찾아 읽도록 지시하는 겁니다. 필요할 때만 정보를 공개하는 거죠.
코드 스니펫은 넣지 마세요. 금방 낡습니다. 대신 파일명:라인번호 형식으로 참조를 넣으세요.
3. Claude는 린터가 아닙니다
많은 개발자가 CLAUDE.md에 코드 스타일 가이드를 넣습니다. 하지만 LLM을 린터로 쓰는 건 비효율적입니다. 느리고 비싸거든요.
LLM은 컨텍스트 학습자입니다. 코드베이스가 일관된 패턴을 따른다면, 몇 번 검색하는 것만으로도 자연스럽게 그 패턴을 따라합니다. 굳이 명시하지 않아도 되는 거죠.
정말 걱정된다면 Claude Code의 Stop Hook을 설정해서 포맷터와 린터를 자동으로 돌리세요. Claude가 직접 포맷 문제를 찾게 하지 말고요.
4. 자동 생성하지 마세요
CLAUDE.md는 하네스에서 가장 높은 레버리지를 가진 지점입니다. 모든 세션, 모든 작업에 영향을 주니까요. 나쁜 코드 한 줄은 문제 한 줄을 만듭니다. 나쁜 CLAUDE.md 한 줄은 수많은 세션에서 수많은 나쁜 코드를 만들어냅니다.
그래서 Claude Code의 /init 명령으로 자동 생성하지 말고, 한 줄 한 줄 신중하게 작성하는 게 좋습니다.
컨텍스트 관리가 곧 성능이다
AI 코딩 에이전트의 효과는 프롬프트 작성법에 달려있습니다. 그중에서도 CLAUDE.md는 가장 중요한 레버입니다.
핵심은 간결함입니다. 보편적으로 적용되는 최소한의 지시만 넣으세요. 나머지는 필요할 때 찾아볼 수 있게 포인터만 남기면 됩니다. Claude에게 모든 걸 다 알려주려고 하지 마세요. 필요한 정보를 어디서 찾을 수 있는지만 알려주면 충분합니다.
참고자료:
답글 남기기