CLAUDE.md 작성법을 조사하다가 정반대의 주장에 맞닥뜨렸습니다.

A 「20개 이상의 템플릿을 준비하여 역할, 규약, 테스트 전략, 보안까지 망라해야 한다」 -
B 「8행이면 충분하다. 늘리기보다 줄이는 것이 효과적이다」

둘 다 자신 있게 작성되어 있습니다. 양쪽 모두 시도해 본 뒤 공식 문서를 다시 읽어본 결과, 어느 쪽이 옳은지는 명확하게 결론이 났습니다. 게다가 단순히 "짧게 만들자"로 끝나지 않는 이유가 있었습니다.

이 기사에서는 왜 긴 CLAUDE.md가 효과가 없는지를 구조적으로 설명하고, 실제로 무엇을 써야 하는지까지 정리합니다.

이 기사의 요점

• 공식 입장은 "짧게 유지하라".
• 비대해지면 정말로 지키게 하고 싶은 지시가 무시된다 - 이유는 두 가지.
• 매 요청(Request)마다 컨텍스트(Context)에 포함된다는 점, 그리고 주의력이 희박해진다는 점.
• 현행 모델에서는 쓰면 오히려 역효과가 나는 지시가 있다. "검증하라", "CRITICAL:" 등은 전형적인 예시.

CLAUDE.md는 Claude Code가 세션 시작 시 자동으로 읽어들이는 설정 파일입니다. 매번 같은 서두(예: "일본어로", "불렛 포인트로")를 입력하는 수고를 덜 수 있습니다.

위치는 주로 두 곳이며, 두 곳 모두 읽혀서 합산됩니다.

즉, "자신의 취향"은 공통 측에 한 번 써두면 모든 안건에 적용되고, "해당 안건 고유의 전제"는 프로젝트 측에 쓰는 방식으로 분담할 수 있습니다.

처음부터 쓰는 것이 번거롭다면 /init을 통해 초안이 생성됩니다. /memory로 편집할 수 있습니다.

CLAUDE.md는 강제가 아닌 부탁입니다. 공식 측도 엄격한 준수를 보장하지는 않습니다. 규칙에서 벗어나면 그 자리에서 지적하여 수정한다는 전제로 사용하는 것입니다.

역할, 프로젝트 개요, 코딩 규약, 안티 패턴(Anti-pattern), 기억 파일, 에러 로그, 커밋 규약, 테스트 전략, 보안, 문서, 배포, 퍼포먼스, 로그, 윤리, 도구, 말투, 사고 프로세스……와 같은 식으로, 20개 이상의 섹션을 준비하는 사고방식입니다.

주장의 근거는 "AI에게 주는 정보가 많을수록 문맥을 이해하여 정밀도가 올라간다"는 것입니다. 직관적으로는 일리가 있습니다.

반면, 10행 이내로 압축하는 사고방식입니다.

# 나의 설정
- 답변은 반드시 일본어로.
- 상대는 비엔지니어. 전문 용어를 사용하면 그 자리에서 1행으로 풀어서 설명할 것.
...

판단 기준은 명쾌합니다. "이 행을 지웠을 때 Claude가 실수를 하는가? No라면 지운다"

공식은 명확하게 입장 B입니다.

Anthropic의 베스트 프랙티스(Best Practice)는 CLAUDE.md를 간결하게 유지할 것을 권장하고 있습니다. 그리고 중요한 것은 단순히 "짧은 편이 읽기 좋다"는 이야기가 아니라, 비대해지면 정말로 지키게 하고 싶은 지시가 무시되게 된다고 경고하고 있다는 점입니다.

이는 체감과도 일치합니다. 이것저것 다 적어서 50행이 된 결과, 정작 중요한 "일본어로"가 묻혀서 효과가 없어지는——현상이 발생합니다.

그렇다면 왜 그렇게 되는 걸까요? 이유는 두 가지가 있습니다.

이 부분이 간과되기 쉽습니다. CLAUDE.md는 세션 처음에 한 번 읽히고 끝나는 것이 아닙.

Claude API는 스테이트리스(Stateless)이므로, 대화를 이어가려면 매번 모든 이력을 다시 보내야 합니다. CLAUDE.md는 그 앞부분에 위치하기 때문에, 요청(Request) 때마다 매번 전송됩니다.

즉, CLAUDE.md가 길수록 모든 요청의 토큰 비용(Token Cost)이 상승합니다. 100번 대화를 주고받으면 100번 분량입니다. 단 한 번의 초기화 비용이 아닙니다.

나아가 프롬프트 캐시(Prompt Cache) 관점에서도 불리해집니다. 캐시는 접두사(Prefix)의 완전 일치 여부에 따라 작동하므로, CLAUDE.md를 편집하면 그 이후의 캐시를 다시 만들어야 한다고 생각할 수 있습니다 (Claude Code의 내부 구현은 공개되지 않았으므로, 이는 구조적 추측입니다).

자주 바뀌는 정보를 CLAUDE.md에 써서는 안 되는 이유가 바로 이것입니다.

더 본질적인 이유는 다음과 같습니다.

지시 사항이 5개라면 모델은 각각에 주의를 기울일 수 있습니다. 하지만 지시 사항이 50개라면, 개별 지시 사항의 상대적인 가중치가 낮아집니다. "일본어로 작성해 주세요"라는 한 줄이 "배포는 CI/CD로 자동화되어 있습니다"라는 한 줄과 동일한 가중치로 나열되는 셈입니다.

그리고 현행 모델(Claude Opus 4.5 이후)은 지시 사항에 충실합니다. 이는 언뜻 장점처럼 보이지만, 뒤집어 생각하면 불필요한 지시 사항의 해악도 충실하게 반영된다는 뜻입니다.

• 모호한 지시 사항 → 모호하게 해석됨
• 모순된 지시 사항 → 둘 중 하나를 임의로 선택함
• 불필요한 지시 사항 → 성실하게 지키느라 낭비가 발생함

모델이 똑똑해졌기 때문에, 작성할 내용을 선별해야 합니다.

이 부분이 가장 실질적인 피해가 발생하는 지점입니다. 입장 A의 템플릿에는 현행 모델에서는 역효과를 내는 지시 사항이 섞여 있습니다.

포괄적인 템플릿에는 대개 "마지막에 검증 단계를 넣을 것", "다른 에이전트에게 리뷰를 맡길 것"과 같은 항목이 있습니다.

Claude Opus 5는 시키지 않아도 스스로 검증합니다. 그곳에 검증 지시가 남아 있으면, 이중으로 검증하게 되어 시간과 토큰을 소비합니다.

Anthropic의 마이그레이션 가이드(Migration Guide)는 이를 다시 쓰는 것이 아니라 삭제하라고 명시하고 있습니다. 삭제해도 품질은 떨어지지 않습니다.

이는 일반적인 프롬프트(Prompt) 작성 요령과 반대됩니다.

"자기 체크를 시키면 정확도가 올라간다"는 것은 오랫동안 유효했던 기술이었고, 실제로 이전 모델들에서는 그러했습니다. 하지만 Opus 5에서는 역효과를 냅니다. 사내 프롬프트 규약에 "반드시 자기 검증 문구를 넣을 것"이라고 적혀 있다면, 예외를 두어야 합니다.

"반드시 지키게 하고 싶은 행에는 IMPORTANT:를 붙이면 준수율이 올라간다"라는 이야기를 자주 접할 수 있습니다. 이는 다소 오래된 권장 사항입니다.

Opus 4.5 이후의 모델은 지시 사항에 충실해졌기 때문에, CRITICAL, MUST, If in doubt와 같은 강한 표현은 과잉 반응(overtrigger)을 초래한다고 공식적으로 밝히고 있습니다.

도구를 너무 많이 사용하거나 지시 사항을 과도하게 적용하는 증상이 나타날 때, 추가적인 가드레일(Guardrail)을 작성하는 것이 아니라, 먼저 어조를 약화시키는 것이 올바른 대처법입니다.

Opus 5는 원래 응답이 길어지는 경향이 있습니다. 여기에 "단계적으로 사고 과정을 공개하라", "여러 선택지를 비교 검토하라"라고 적으면 응답은 더욱 길어집니다.

판단할 수 있는 상황이라면 즉시 착수하게 하는 것이 효율적입니다.

서브 에이전트(Sub-agent)로의 위임에 대해서도 주의가 필요합니다. Opus 4.8은 위임이 부족하여 독려할 필요가 있었지만, Opus 5는 내버려 두어도 스스로 위임합니다. 4.8을 위해 작성한 "더 많이 위임하라"는 내용을 남겨두면, 필요 이상으로 업무를 분담하여 비용과 대기 시간이 증가합니다.

현행 모델에서 효과적인 것은 역방향의 지시입니다.

서브 에이전트의 기동은 최대 3개체까지로 제한합니다.

판단 기준은 입장 B의 것을 그대로 사용할 수 있습니다.

모델이 추측할 수 없는 정보뿐입니다.

마지막 "스코프 규율(Scope Discipline)"은 현행 모델에서 특히 효과적입니다. Opus 5는 요청하지 않은 일까지 알아서 하려는 경향이 있기 때문에, 명시적으로 선을 그으면 멈춥니다.

일반론 — "정중하게 작성해줘", "유지보수성을 중시해줘". 누구나 알고 있는 내용은 칸의 낭비입니다.
모델이 내버려 두어도 할 일 — "검증해줘", "테스트를 작성해줘".
빈번하게 바뀌는 정보 — 진행 중인 작업 상황 등. 캐시(Cache)를 깨뜨릴 뿐만 아니라 정보가 오래됩니다.
가끔만 사용하는 절차 — 매번 읽히면서 칸을 차지하므로, 별도의 메커니즘(스킬 등)으로 넘깁니다.
모호한 표현 — "제대로 해줘", "자연스럽게". 검증할 수 없는 지시는 효과가 없습니다.

내용이 많아지면 CLAUDE.md 안에 @를 사용하여 경로를 작성하면 별도의 파일을 불러올 수 있습니다.

코딩 규약은 @docs/coding-rules.md를 참조.

한 장에 다 몰아넣는 것보다 정리하기가 더 쉬워집니다. 다만 읽히는 총량은 변하지 않으므로, 이는 분량 대책이 아니라 정리를 위한 기능입니다.

처음부터 완벽을 목표로 하지 마세요. 3줄부터 시작해서, "아, 또 똑같은 설명을 했네"라고 생각되면 1줄을 추가합니다. 이 과정을 반복하며 자신만의 사양으로 만들어가는 것입니다.

규약을 지키지 않을 때의 문제 분리 순서는 다음과 같습니다.

/memory를 통해 애초에 읽히고 있는지 확인 (경로가 다르면 읽히지 않습니다) - 읽히고 있다면
너무 길거나, 모호하거나, 모순되는지 의심 - 정기적으로 점검하여
지울 수 있는 행은 지우기

세 번째 방법이 가장 효과적입니다. 늘리는 것보다 줄이는 것이 더 효과적이라는 점은 체감상으로도, 공식 기술(description)과도 일치합니다.

공식 입장은 "짧게 유지하라"입니다. 비대해지면 정말로 지키게 하고 싶은 지시사항이 무시됩니다 - 이유는
매 요청(request)의 컨텍스트(context)에 포함된다는 점과, 지시가 늘어나면 하나당 가중치가 낮아진다는 점 때문입니다 - 현행 모델에는
쓰면 오히려 역효과가 나는 지시가 있습니다. "검증하라"는 삭제하고, "CRITICAL:"은 어조를 완화하며, "더 많이 위임하라"는 상한선 지정으로 대체합니다 - 판단 기준은
**"이 행을 지웠을 때 Claude가 실제로 실수를 하는가"**입니다.

포괄적인 템플릿은 언뜻 친절하고 안심이 됩니다. 하지만 CLAUDE.md는 Claude를 똑똑하게 만드는 마법이 아니라, 매번 반복되는 서문을 생략하기 위한 메모입니다. 따라서 늘릴수록 효과적인 것이 아니라, 목표를 좁힐수록 효과적입니다.

먼저 자신의 CLAUDE.md를 열고, 지울 수 있는 행을 찾아보세요. 아마 찾을 수 있을 것입니다.