CLAUDE.md의 비대화는, 규칙을 추가할 때 4단계 판단으로 방지하기

서론

CLAUDE.md

은 어느새 부풀어 오릅니다.

규칙 하나를 추가할 때마다 이유나 배경까지 함께 적어 넣기 때문입니다.

그리고 길어진 후에, 무엇을 지울지 고민하게 됩니다.

필자의 프로젝트에서도 CLAUDE.md는 작성하기 시작한 지 약 3.5일 만에, 약 20번의 수정 끝에 글자 수가 처음의 약 17배로 부풀었습니다.

다시 만든 직후에는 약 1,200자로, 부푼 분량의 약 4분의 1이 되었습니다.

'최우선 규칙(最優先の決まり)' 섹션을 추가한 지금도 약 1,900자로, 약 5분의 2에 머물고 있습니다.

최근에는 비대해진 CLAUDE.md를 나중에 검토하여 줄이는 이야기를 자주 볼 수 있습니다.

이 글은 그 반대로, 규칙을 추가하는 시점에 자리를 정하고 애초에 부풀지 않게 작성하는 방법을 소개합니다.

필자는 하나의 프로젝트의 CLAUDE.md를 3번 수정하면서, 규칙을 추가할 때 자리를 결정하는 '4단계 판단'을 만들었습니다.

현재 형태로 만든 지 약 2일 만에 규칙과 지식을 7개 추가했지만, CLAUDE.md가 늘어난 것은 2줄뿐이었고, 작업별로 읽는 파일 목록의 줄은 하나도 늘어나지 않았습니다.

그 판단과 현재 CLAUDE.md의 형태를 가상의 프로젝트에 비유하여 설명하겠습니다.

이 글에서 알 수 있는 것

• 규칙을 추가할 때, 어디에 둘지 결정하는 4단계 판단
• '최우선 규칙', '규칙', '작업별로 읽는 파일 목록'의 세 섹션으로만 구성한 CLAUDE.md 작성법 - '최우선 규칙'이 너무 많아지지 않게 하는 기준
• 작업별로 읽는 파일 목록을 만들 때 주의할 점 (줄 단위, 언급해도 되는 파일, 추적 가능한지 확인)
• 자동 메모(自動メモリ)에 맡기는 것과 맡기지 않는 것
• CLAUDE.md를 분할해도 로드되는 토큰이 줄지 않는 경우

대상 독자

• CLAUDE.md가 길어져서 무엇을 어디에 써야 할지 막막한 사람 - 필자의 환경은 Windows 11 + VSCode 확장, Claude Code 2.1 계열입니다 (2026년 9월 기준)

필자는 CLAUDE.md를 전역(global) 및 여러 프로젝트를 아우르는 관리 폴더, 그리고 프로젝트의 세 가지 계층에 두고 있습니다.

이 글에서는 가장 아래 단계인 프로젝트의 CLAUDE.md만 다루며, 계층별 사용법에는 언급하지 않습니다.

비대화는 나중에 줄이는 것보다, 추가할 때 방지하기

3번 수정하며 알게 된 것

계기는 프로젝트의 CLAUDE.md를 정리하려던 것이었습니다.

1차 때는 분야별로 .claude/rules/ 파일로 분리하고, 자세한 설명은 다른 문서로 옮겼습니다.

하지만 분리된 각 파일 안의 내용은 지켜야 할 것과 그 이유 및 메커니즘에 대한 해설이 함께 공존해 있었습니다.

장소를 옮겼을 뿐, 내용은 그대로였습니다.

2차 때는 규칙만 남기고, 작업별로 읽는 파일을 나열한 표를 만들었습니다.

그래도 표의 줄에는 구성 설명 같은, 작업 이름이 아닌 것이 섞여 있었습니다.

언젠가 정리될 계획인 파일을 가리키는 줄도 있었습니다.

rules/에도 규칙을 너무 많이 적어 넣었습니다.

3차 때는 rules/를 없애고 골격만 남긴 후, '최우선 규칙' 섹션을 추가하여 현재 형태로 만들었습니다.

돌이켜보면 효과적이었던 것은 파일을 나눈 것이 아니라, 한 줄씩

글로벌(global)이나 관리 폴더의 분량까지 합쳐서 시작 시 읽는 지시 파일 전체가 약 1만 자에서 약 9천 자로, 겨우 1할 정도밖에 줄지 않았습니다.

읽어 들여지는 분량은 세션을 시작할 때마다 발생하는 고정 비용입니다.

서브 에이전트를 가동할 때마다 같은 분량이 소요됩니다.

줄이려면 내용을 '필요할 때 링크로 여는 문서'로 옮기거나, paths:를 붙인 rules/ 폴더로 만드는 수밖에 없습니다.

서브 에이전트의 첫 입력에 대한 이야기는 다른 글에 썼습니다.

현재 CLAUDE.md는 단지 세 개의 절만 있음

현재 프로젝트의 CLAUDE.md는 한 줄 설명과 다음 세 개의 절로 이루어져 있습니다.

그것은 지키게 할 규칙이 아니라 조사할 지식이기 때문에 표의 다음 문서에 작성합니다.

가상의 가계부 웹 앱으로 치환하면 다음과 같습니다.

# kakeibo-web
가계부 웹 앱 (Next.js).
## 최우선 규칙 (다른 절이나 docs/의 문서보다 먼저 지켜야 함)
...

마지막 줄이 4단계 판단을 작성한 문서입니다.

CLAUDE.md를 수정하는 작업을 하기 전에 이것을 읽고, 추가할 때마다 판단 과정을 거칩니다.

앞으로는 다음 세 가지에 답하겠습니다.

• 규칙을 하나 추가하고 싶을 때, 4단계 판단으로 어디에 배치할지
• 두 번째 형태로 표가 무너진 두 가지 원인(작업 이름이 아닌 줄과 계획 파일을 가리킨 줄)을 어떻게 수정했는지
• '최우선 규칙'에 무엇을 올리고 무엇을 올리지 않을지

예시의 CLAUDE.md를 들자면, '비밀'은 첫 번째에 해당하고, '본편(本番)'과 '릴리스(リリース)'는 두 번째에 해당합니다.

세 번째는 필자의 환경에서의 예시이므로, 독자는 자신의 환경에서 전체가 멈추게 되는 구조로 대체해야 합니다.

반대로, 다음과 같은 것은 중요하지만 올리지 않았습니다.

어떤 경우든 깨져도 나중에 고칠 수 있기 때문입니다.

• 대화의 언어
• 작업 기록 작성 방식
• 유료 서비스를 사용하기 전 확인 사항
• Claude가 새로운 스킬을 만들 때의 절차

올린 규칙은 '규칙(ルール)'이나 각 문서에서 지우고, CLAUDE.md의 맨 앞 한 곳에만 둡니다.

같은 규칙이 '최우선'과 '규칙' 양쪽에 있으면, 어느 정도의 강도로 지켜야 할지 혼란스러울 수 있습니다.

이런 형태로 만든 후, '최우선 규칙'에 예외를 만들어야 할 상황이 한 번 있었습니다.

그때는 계획 단계에서 '이 절차만은 이 규칙의 예외'라고 적고, 필자의 허가를 받은 후에 진행합니다.

작업별로 읽을 파일 표 작성법

4단계 판단으로 3단계에 해당할 때마다 표가 한 줄씩 늘어납니다.

한 줄씩이라 길게 만들기 어렵지만, 만드는 방식을 잘못하면 읽어야 할 파일을 찾지 못하게 됩니다.

세 번의 수정과 그 이후의 다듬기를 거쳐 결정된 내용은 다음과 같습니다.

행의 단위는 '앞으로 할 작업'

행은 Claude가 앞으로 수행할 작업, 예를 들어 '커밋하기', '릴리스하기'와 같은 것으로 합니다.

'폴더 구성', '용어집'처럼 작업 이름이 아닌 것은 행으로 삼지 않습니다.

그것이 필요한 경우는 '파일 위치를 결정한다'와 같은 작업일 때이므로, 그러한 작업의 행을 만들고 읽을 파일 안에 작성합니다.

작업별로 나누면 Claude가 요청받았을 때 '지금부터 할 것은 이 행이다'라고 적용하기 쉽습니다.

지시하는 것은 오래 남는 파일만

표에서는 docs/ 문서나 해당 폴더의 README만 지시합니다.

계획 파일처럼 끝나면 다른 곳으로 이동하는 것은 지시하지 않습니다.

두 번째 형태에서는 계획을 지시하고 있었고, 계획이 완료될 때마다 표 링크를 수정하는 규칙까지 추가했습니다.

지시하지 않기로 하자 그 규칙도 필요 없어졌습니다.

행에서 추적 가능한지 확인하기

표를 만들었다면, 하나의 행에서 읽을 파일을 열어 작업에 필요한 위치나 절차까지 실제로 따라가 볼 수 있는지 추적해 봅니다.

필자의 표에서도 어떤 작업의 행에서 그 작업 결과물을 놓을 폴더에 도착하지 못하는 경우가 있었습니다.

행이 지시하는 파일 중 어느 곳에도 그 폴더의 위치가 적혀 있지 않았던 것입니다.

처음에는 표의 행에 괄호로 위치를 추가했지만, 그러면 CLAUDE.md에 지식이 혼재됩니다.

결국, 해당 폴더에 README를 두고 내부 구성이나 규칙을 작성하고, 표의 행에서는 그 README를 가리키는 형태로 수정했습니다.

따라갈 수 없을 때는 표에 주석을 추가하는 것이 아니라, 지시하는 파일에 내용을 추가합니다.

paths가 붙지 않은 rules로 만들지 않은 이유

특정 작업만을 위한 규칙은 paths:가 붙은 rules/로 할 수도 있습니다.

다만, paths:가 붙은 rules는 지정한 경로의 파일을 Claude가 읽었을 때만 로드됩니다.

'push 전에 체크리스트를 통과시키기'처럼 어떤 파일을 열 것인지와 관계없는 규칙은, 읽히지 않은 채 작업이 진행될 수도 있습니다.

그래서 필자는 작업을 기점으로 읽을 파일을 표로 지시하는 형태로 했습니다.

paths:가 적합한 경우는 예를 들어 '이 확장자의 파일을 작성할 때의 코딩 규약'처럼 파일과 연결되는 규칙입니다.

자동 메모와의 사용 구분

Claude Code에는 Claude가 스스로 기억하고 싶어 하는 것을 기록하는 자동 메모 기능도 있습니다.

공식 문서에 따르면, 자동 메모는 단말기별로 저장되며 git에는 포함되지 않습니다(2026년 9월 기준).

무엇을 남길 가치가 있는지는 Claude가 결정합니다.

본인은 내용을 보고 수정할 수 있지만, 다른 사람의 눈으로 검토받지는 못합니다.

필자도 자동 메모를 사용하고 있으며, 현재는 Claude가 남긴 주의사항이 몇 가지 들어 있습니다.

예를 들어 '임시 폴더도 워크스페이스 외부로 취급한다', '절차서에 확인 없이 진행하라고 해도 워크스페이스 외부의 변경은 개별적으로 허가를 받는다'와 같은 것입니다.

후자는 Claude가 절차서 작성 방식을 우선하여 워크스페이스 외부에 작성해 버렸고, 필자가 지적한 후에 남겨진 것입니다.

이런 식으로 작업 과정에서 나온 Claude를 위한 주의사항은 그대로 두고 있습니다.

맡기지 않는 것은 스스로 정한 규칙입니다.

규칙은 추가할 때 4단계 판단으로 위치를 정하고 스스로 작성합니다.

자동 메모리에 쌓인 주의사항을 나중에 검토하여 규칙 파일로 옮기는 정리 작업도 있습니다.

이 글에서 설명하는 방식은 그 단계 이전에 손을 대는 것입니다.

규칙으로 만들고 싶다고 생각한 시점에서, 메모리에 맡기지 않고 위치를 정합니다.

이 형태로 만든 후 약 2일 동안 추가된 항목들

이 형태로 만든 후 약 2일 동안 추가된 규칙 및 지식은 총 7건이었습니다.

세어본 것은 의미가 새로 생긴 변경분이며, 경로(path) 수정 등은 제외했습니다.

그중 CLAUDE.md에 들어간 것은 '규칙' 항목 1건입니다.

그 외에 표 앞에 짧은 주석을 1줄 추가했으므로 늘어난 분량은 2줄입니다.

표의 행은 하나도 늘지 않았습니다.

나머지 6건은 표에서 참조하는 문서와, 거기서 참조하는 새로운 문서에 들어갔습니다.

새로운 문서는 표에 행을 추가하지 않고, 표가 참조하는 문서 중에서 안내했기 때문에 단계 2의 처리 방식입니다.

단계 번호로 다시 말하자면, 단계 1이 1건, 단계 2가 6건이고, 단계 0과 3은 0건이었습니다.

다만 아직 날짜가 짧아 장기간 늘어나지 않았다고는 할 수 없습니다.

맺음말

CLAUDE.md가 늘어난 것은 추가할 때 위치를 정하지 않고 작성했기 때문이었습니다.

필자는 한 줄씩 위치를 다시 정하는 작업을 3번 반복하여, 그 판단을 4단계로 정리해 문서화했습니다.

지금 CLAUDE.md에 있는 것은 '최우선 규칙'과 '규칙', 그리고 작업별로 읽어야 하는 파일의 표뿐입니다.

다음으로 규칙을 추가하고 싶다면, 먼저 '이것이 어떤 작업 시점에 필요한가'를 생각해 보세요.

관련 글

Discussion