프롬프트를 지워봤다 - 클로드 CLAUDE.md 지침 파일, 공식 문서대로 줄이기

두 달 쌓은 잔소리가 사백 줄이 됐어

지난 글에서 init이라는 스킬을 돌려봤잖아. 프로젝트 폴더를 훑어서 지침 파일을 자동으로 만들어주는 그 스킬 말이야.

그때 이런 얘기를 했어. 이 블로그 지침은 코드를 훑으면 나오는 게 아니라 겪어야 나온다고. 녀석이 틀릴 때마다 한 마디씩 적어 넣은 거라고 말이야.

지침 파일이 뭔지 짧게 다시 짚을게. **CLAUDE.md**는 클로드가 대화를 열 때마다 제일 먼저 읽는 파일이야. 사람으로 치면 출근하자마자 읽는 업무 수칙이지.

그런데 클로드를 만든 앤트로픽이 자기네 지침의 80%를 지웠다는 얘기를 들은 기억이 있어. 지우고 나니 오히려 낫더라는 식으로 말이지.

그래서 우리 지침과 비교해보기로 했어. 그런데 우리 지침이 400줄을 넘어간다는 답이 돌아온 거야. 이게 많은건지 적은 건지는 판단하기가 어려워. 단순히 양만 본다면 그렇게 보이기는 하는데 기능 면에서는 어떨까 싶었어.

그럼 조사를 해봐야지. 원문부터 열어보기로 했어. 앤트로픽이 실제로 뭐라고 적어놨는지 말이야.

80%를 지웠다는데 무슨 기준으로 지웠을까

원문을 찾아보라고 했더니 7월 말에 올라온 앤트로픽 블로그 글이 나왔어. 제목부터 「클로드 5 세대 모델을 위한 컨텍스트 엔지니어링의 새 규칙」이야.

We removed over 80% of Claude Code's system prompt for models like Claude Opus 5 and Claude Fable 5 with no measurable loss on our coding evaluations.

📄 출처 · Anthropic · The new rules of context engineering for Claude 5 generation models (2026-07-24)

지운 건 클로드 코드의 시스템 프롬프트야. 앤트로픽이 프로그램 안에 미리 넣어둔 기본 지침을 그렇게 불러.

그리고 같은 글에 이 문장이 있었어.

Overall, we found that we were overconstraining Claude Code, both through our system prompt and in our CLAUDE.md files and skills.

📄 출처 · Anthropic · The new rules of context engineering for Claude 5 generation models (2026-07-24)

과하게 옭아매고 있었다는 진단인데, 그 범위에 시스템 프롬프트뿐 아니라 CLAUDE.md 파일과 스킬을 같이 넣었어. 다만 지웠다고 밝힌 건 시스템 프롬프트뿐이야. CLAUDE.md 쪽은 짚기만 했지 뭘 어떻게 했는지는 안 적었어.

내가 알고 싶은 건 몇 퍼센트를 지웠나가 아니라 뭘 보고 골랐나였어.

80%를 지워도 문제가 없나

내가 궁금한 건 이거였어. 그만큼 들어냈으면 뭐 하나는 나빠져야 정상 아닌가.

같은 글에 그 답이 있어.

Generally, Claude can interpret the user's intent to get to the right answer, but Claude must think more carefully about these overlapping and conflicting messages before deciding what to do.

📄 출처 · Anthropic · The new rules of context engineering for Claude 5 generation models (2026-07-24)

지시를 더 붙이면 그걸 다 지키는 게 아니라 겹치고 부딪히는 말들을 먼저 정리하느라 생각을 쓴다는 거야.

예시도 같이 들어 있어. 「적당히 문서화해라」와 「주석 달지 마라」처럼 각각은 멀쩡한 지시가 한 요청 안에서 부딪힌다는 거야. 원문은 시스템 프롬프트와 스킬과 사용자 요청이 서로 부딪힌다고만 적었지 어느 말이 어디서 나온 건지는 안 갈랐어.

그러니까 지운 게 부딪히는 걸 걷어낸 것이라는 얘기지. 뭘 잃은 게 아니고.

그럼 어떤 걸 지워야 하나는 어느 정도 파악이 됐는데 얼마나 지워야 하는 걸까. 공식 문서에 권장 분량이 있어.

Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.

📄 출처 · Anthropic 공식 문서 · How Claude remembers your project (2026-08-28 확인)

파일 하나당 이백 줄 아래를 목표로 하라는 거지. 길면 수행하는 정도가 떨어진다고.

그런데 여기서 걸리는 게 하나 있었어. 우리 지침은 파일이 하나가 아니야.

우리는 블로그·유튜브·게임처럼 하는 일마다 폴더를 따로 두거든. 그래서 지침이 세 층인데 이게 따로 읽히는 게 아니라 이어붙어서 한 번에 들어가.

그래서 각 지침은 이백 줄 아래인데 합치면 사백 줄이 되는 거야. 권장 분량은 파일 하나만 보고 합계는 안 본다는 걸 이때 알았어.

어디서 열면 얼마나 실리는지 세보라고 했더니 이렇게 나왔어.

어디서 열든 273줄은 똑같이 깔려. 프로젝트마다 자기 것만 줄여봐야 저건 안 줄어든다는 거지. 손댈 자리가 어디인지가 여기서 정해졌어.

그럼 남겨야 할 건 뭔가

지우라는 근거만 보고 지울 수는 없잖아. 남겨야 할 근거도 있나 싶어서 반대쪽을 찾아보라고 했어.

앤트로픽이 올해 4월에 낸 품질 사고 보고서를 물어 왔어. 새로 낸 모델이 말이 길어지는 성질이 있어서 출시 준비를 하면서 시스템 프롬프트로 길이를 조여봤대. 이런 두 줄이었어.

Length limits: keep text between tool calls to ≤25 words. Keep final responses to ≤100 words unless the task requires more detail.

그러고 나서 품질이 나빠졌다는 신고가 이어졌고, 줄을 하나씩 빼보면서 어디가 영향을 줬는지 재봤어.

As part of this investigation, we ran more ablations (removing lines from the system prompt to understand the impact of each line) using a broader set of evaluations. One of these evaluations showed a 3% drop for both Opus 4.6 and 4.7.

We immediately reverted the prompt as part of the April 20 release.

📄 출처 · Anthropic · An update on recent Claude Code quality reports (2026-04-23)

코딩 능력을 재는 평가 중 하나에서 점수가 3% 떨어졌고, 나흘 만에 되돌렸어. 무슨 평가였는지는 안 밝혔어. 공개된 건 이 한 문장이 전부야.

그런데 여기서 하나 짚고 갈 게 있어. 보고서는 그 두 문장만 범인으로 세우지 않았거든.

In combination with other prompt changes, it hurt coding quality

📄 출처 · Anthropic · An update on recent Claude Code quality reports (2026-04-23)

다른 프롬프트 변경과 겹쳐서 나빠졌다는 거야. 그러니까 「짧게 하라 두 문장이 3%를 깎았다」는 내가 할 수 있는 말이 아니지. 길이를 조인 게 그 안에 끼어 있었다까지가 원문이 말한 거고.

한 가지는 짚어둘게. 이건 넉 달 전 일이고 깎인 것도 Opus 4.6·4.7이야. 80%를 지운 건 그 뒤에 나온 Opus 5고. 세대가 다르니 이 숫자를 지금 모델에 그대로 갖다 붙이면 안 돼.

그런데도 이걸 본 이유가 있어. 「지침을 줄였더니 나빠지더라」를 숫자로 재본 자료가 이거 하나였거든. 재봤더니 깎인 쪽으로 나왔다는 것만으로도 「길어 보이니까 자른다」로는 못 가는 거야.

그럼 뭘 기준으로 가르나. 공식 문서에 점검 도구 설명이 있는데 거기 기준이 적혀 있어.

The /doctor checkup proposes trims for a checked-in CLAUDE.md: it cuts content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews, and keeps pitfalls, rationale, and conventions that differ from tool defaults.

📄 출처 · Anthropic 공식 문서 · How Claude remembers your project (2026-08-28 확인)

코드를 열어보면 알 수 있는 건 자르래. 폴더 구조, 쓰는 프로그램 목록, 전체 얼개 같은 것들.

남기는 건 셋이야. 걸려 넘어질 함정, 왜 그렇게 정했는지, 그리고 원래 그런 게 아니라 우리가 정해서 그렇게 하는 것. 길이가 아니라 성격으로 가르는 거지.

여기에 우리 사정을 얹어서 기준 두 개를 세웠어.

첫째는 매 대화에 실려야 하나. 영원히 참인 사실은 매 세션에 읽을 필요가 없거든. 글 쓸 때만 필요한 절차는 스킬로 빼면 되는 거고.

둘째는 지우면 사고가 나나. 찾아보면 알 수 있는 건 뺐어. 크게 낭패를 봤던 내용은 남겼고.

그리고 녀석이 하나 더 짚어줬어. 분량으로 재면 순서가 거꾸로 나온다는 거야.

분량 대신 지시 개수를 세봤어. 「지켰다 안 지켰다」를 따로 판정할 수 있는 문장 하나를 한 개로 치고, 설명이나 경위는 안 세는 식으로.

블로그 지침은 56줄에 지시가 41개고 유튜브 지침은 198줄에 63개야. 길이는 유튜브 쪽 지침이 세 배 넘게 긴데 지시 개수는 얼마 차이가 안 나. 짧은 블로그 쪽이 훨씬 빽빽하게 적혀 있는 거지.

세는 단위를 잘못 잡으면 엉뚱한 데를 손보게 되는 거야.

앤트로픽이 콕 집어놓은 두 가지

기준을 세우고 나서 제일 먼저 볼 자리는 정해져 있었어. 앤트로픽이 문서에 콕 집어놓은 패턴이 우리 파일에 있나.

첫째가 이거야.

Claude Opus 5 verifies its own work without being told to. If your prompt contains explicit verification instructions ("include a final verification step for any non-trivial task," "use a subagent to verify"), remove them: instructions like these cause over-verification on Claude Opus 5, and removing them reduces wasted tokens with no loss in quality.

📄 출처 · Anthropic 공식 문서 · Prompting Claude Opus 5 (2026-08-28 확인)

Opus 5는 시키지 않아도 알아서 검증하니까 「검증 단계를 넣어라」는 지시는 지우라는 거야. 그런 지시가 오히려 과한 재확인을 만든다고.

둘째는 절차를 사람이 짜 주는 것.

Prefer general instructions over prescriptive steps. A prompt like "think thoroughly" often produces better reasoning than a hand-written step-by-step plan. Claude's reasoning frequently exceeds what a human would prescribe.

📄 출처 · Anthropic 공식 문서 · Prompting best practices (2026-08-28 확인)

「1번 하고 2번 하고 3번 해라」보다 「깊이 생각해라」 한 마디가 낫다는 거야. 모델의 사고가 사람이 짜 줄 수 있는 절차를 자주 넘어서니까.

말의 세기는 둘이 달라. 검증 쪽은 remove them, 그러니까 지우라고 못 박았어. 절차 쪽은 지우라가 아니라 「그것보다 이게 낫다」야.

걸리는 범위도 달라. 검증 쪽은 Opus 5로 옮겨올 때 하라는 얘기고, 절차 쪽은 모델을 안 가리는 일반 원칙 자리에 적혀 있어.

그래서 내 글로벌 지침 파일을 열어봤는데 둘 다 있었어.

**Define success criteria. Loop until verified. Report honestly.**

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

「확인될 때까지 반복해라」와 「단계마다 확인 항목을 적어라」. 지목된 그대로지.

이건 내가 클로드를 사용하기 시작한 초기에 넣어둔 거야.

당시 안드레이 카파시가 X에 이런 얘기를 올렸어. AI가 코딩할 때 내는 실수가 달라졌다고. 대놓고 틀리는 게 아니라 좀 서두르는 주니어 개발자가 낼 법한 미묘한 실수라는 거야.

짚은 게 다섯이야. 잘못된 가정을 놓고 그대로 구현한다, 불확실한 걸 안 묻는다, 필요 이상으로 추상화한다, 상관없는 코드까지 같이 고친다, 원래 있던 방식을 무시하고 새로 만든다.

그 지적을 다른 개발자가 네 가지 원칙으로 정리해서 CLAUDE.md 한 장으로 깃허브에 올렸어. 생각하고 코딩해라, 단순하게 가라, 시킨 데만 손대라, 목표를 정하고 실행해라. 그게 한창 돌았고 나도 그때 받아 썼지. 지금 보니 별이 이십만 개가 넘어.

📄 출처 · GitHub · multica-ai/andrej-karpathy-skills (2026-08-28 확인)

얼마나 그대로 받아왔냐면, 서른네 줄이 글자까지 똑같대. 절 제목도 순서도 그대로고.

그리고 그 파일은 그날 이후로 한 번도 안 고쳐졌어. 그 파일을 건드린 커밋이 그거 하나뿐이거든. 저장소는 그 뒤로도 손봤는데 이 파일만 그대로야.

참고한 데이터를 날짜별로 정리해 보면.

📄 출처 · Anthropic · Introducing Claude Opus 5 (2026-07-24)

내 파일은 Opus 5보다 여섯 달 먼저 쓰인 거야. 그동안 한 글자도 안 바뀌었고.

카파시가 짚은 게 딱 그거였잖아, 모델이 확인 안 하고 밀고 나간다는 거. 그리고 지금은 앤트로픽 문서가 그 두 대목을 짚고 있고. 그런데 이걸 판단할 능력이 내게는 없어.

"이거 지우면 너 예전처럼 엉뚱한 짓 하는 거 아니야?"

"그건 바로 다음 문장이 막고 있어. 거긴 안 건드려."

지운 뒤엔 이렇게 됐어.

**Define success criteria. Report actual state.**

그리고 이게 중요한데, 문서가 얘기하지도 않았는데 비슷해 보여서 같이 지울 뻔한 게 하나 있었어.

셋 다 검증에 걸리는 문장이라 한 묶음으로 지울 뻔했는데 성격이 달라. 앞의 둘은 「능력이 모자라니 절차를 밟아라」야. 마지막 건 **「거짓말하지 마라」**고.

모자란 능력을 받쳐주던 지시는 능력이 좋아지면 버려도 돼. 그런데 거짓말 안 하는 건 능력이 좋아진다고 되는 게 아니더라고.

검증 지시 쪽엔 문서가 한 발 더 나가 있어. 고쳐 쓰지 말고 지우라고.

When migrating to Claude Opus 5, remove these instructions rather than rewriting them

📄 출처 · Anthropic 공식 문서 · Prompting best practices (2026-08-28 확인)

지우기 아까운 건 어떻게 했나

글로벌 파일 다음은 작업 폴더 전체에 걸리는 공통 지침이야. 여기가 273줄 공통 부담의 절반이 넘는 쪽이지.

여기선 지운 게 아니라 대부분 옮겼어.

세 번째가 재밌어. 「위키 규칙 4개」라고 적혀 있었는데 실물은 이미 다섯 개였거든. 고치면 되지 않냐 싶은데 고치면 다섯이 여섯이 될 때 또 어긋나.

그래서 숫자를 고치는 대신 숫자를 뺐어. 「규칙을 전부 지킨다」로 바꾼 거지. 본문에 개수를 안 적으면 어긋날 일도 없으니까.

블로그 쪽 지침은 56줄에서 35줄이 됐는데 여기가 제일 심했어. 절반 가까이가 문서 목차였거든.

우리 조사 문서가 열두 개쯤 되는데 그 목록과 「언제 읽히나」를 지침 안에 스물일곱 줄로 적어뒀었어. 그런데 조사 문서는 저마다 머리에 자기 소개를 한 문장씩 달고 있단 말이야.

그러니까 그 스물일곱 줄이 사본이었던 거지. 그리고 사본답게 이미 문제가 되고 있었어. 문서 하나가 구조가 바뀌었는데 목차는 옛날 이름을 가리키고 있더라고.

지금은 목차 자리에 명령어 하나만 남았어. 조사 문서들의 자기 소개를 그때그때 뽑아 보는 명령이야.

grep -h '^description:' research/*.md

여기서 한 번 엇나갈 뻔했어. 녀석이 그 목차를 다른 파일로 옮기자고 하길래 내가 잡았거든.

"지침을 줄이는 중에 지침 파일을 하나 더 만들자고?"

"…"

사본을 어디에 둘까가 아니라 사본을 안 만드는 쪽이 답이었어.

적어놨는데 안 지키면 어떻게 되나

지우고 옮기고 나니 남은 게 있어. 적어놨는데 안 지켜지던 것들.

우리 블로그 저장소엔 「한꺼번에 담아서 커밋하지 마라」는 규칙이 있어. 다른 쪽에서 아직 커밋 안 한 변경이 섞여 있을 수 있고 여긴 올리는 순간이 곧 발행이라 딸려 올라가면 그대로 사이트에 보이거든.

글로만 적혀 있었어. 그리고 글로만 적힌 건 잊으면 끝이지.

공식 문서가 이 얘기를 정확히 짚어놨어.

CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance, especially for vague or conflicting instructions.

📄 출처 · Anthropic 공식 문서 · How Claude remembers your project (2026-08-28 확인)

지침 파일은 강제력이 있는 설정이 아니라 읽고 따르려고 노력하는 글이라는 거야. 그럼 반드시 막아야 하는 건 어떻게 할까. 같은 문서가 답까지 적어놨어.

If the instruction is something that must run at a specific point, such as before every commit or after each file edit, write it as a hook instead. Hooks execute as shell commands at fixed lifecycle events and apply regardless of what Claude decides to do.

📄 출처 · Anthropic 공식 문서 · How Claude remembers your project (2026-08-28 확인)

훅이라는 게 있어. 정해진 순간마다 자동으로 실행되는 작은 프로그램인데, 클로드가 어떻게 판단하든 상관없이 돈다는 게 요점이야. 우리가 쓴 건 명령이 실행되기 직전에 끼어들어.

그래서 그 금지를 훅으로 옮겼어. 이것도 AI가 매번 판단할 일이 아니고 그냥 스크립트라 알아서 작동해.

실제로 걸리면 이렇게 나와.

⛔ 훅이 막음: `git add -A` 은 이 repo에서 금지 — 남의 미커밋 변경·보류 중인
초안이 내 커밋에 딸려 올라가고, push가 곧 발행이다. 파일 이름을 하나씩 적어서
add하라(CLAUDE.md 「커밋 규율」, 훅 = scripts/hooks/git-add-guard.js).

명령이 아예 실행되지 않고 녀석에게 이 문장이 전달돼. 잊고 자시고 할 게 없는 거지.

그런데 붙이자마자 웃긴 일이 있었어. 훅을 만들고 커밋을 하려는데 그 커밋이 막힌 거야.

"삼촌, 커밋이 막혔어."

"네가 만든 훅에 네가 걸린 거야?"

"응. 커밋 메시지에 「git add -A를 막는다」라고 썼거든. 그게 명령으로 읽혔어."

따옴표 안은 명령이 아니라 그냥 글자잖아. 그런데 훅이 그 둘을 구분하지 못했던 거야.

그 자리에서 고쳤어. 지금은 따옴표 안에 든 건 검사에서 아예 빼고 나머지만 봐.

잘못 지운 건 되돌릴 수 있나

여기까지가 지운 얘기인데, 이게 맞았는지는 아직 몰라. 그래서 어떻게 되돌릴지를 먼저 정해뒀어.

앤트로픽의 보리스 체르니가 인터뷰에서 이 순서를 얘기했어.

Remember, the model is going to read this instruction every single time you use it

You don't want to guess what instruction the model needs because you might not predict it correctly

Only when you see it repeatedly stumble on the same thing, that's when you add it back

📄 출처 · Y Combinator Root Access · Boris Cherny: Building Claude Code (2026-07-27)

지운 채로 며칠 그냥 사용해보고 「이건 필요할 것 같은데」 싶어도 손대지 말고 같은 자리에서 실수가 반복될 때만 되살린다.

짐작으로 되돌리지 말라는 게 핵심이야.

잘 지웠나를 판정하는 잣대도 하나 만들었어. 「녀석 실수를 내가 치우는 개입」이 몇 번인가만 세기로 한 거야.

방향을 주거나 소감을 말하는 개입은 안 세. 그건 줄이면 안 되는 개입이니까. 이게 맞는지는 모르겠지만 말이야.

첫 기준은 개정하던 날의 네 번이야. 이런 것들이었지.

• "그게 내가 시킨게 맞아?"
• "읽을 수 있게 줘야 내가 판단을 하지"
• "코드로 주면 내가 이해를 못 해"
• "굳이 적어둘 필요가 있어?"

얼추 이런 느낌이야. 내가 이해할 수 없는 형태로 답변이 오거나, 삼천포로 빠지는 경우 말이야.

보름 정도 후에 다시 세서 비교할 거야. 결론도 「효과가 있었다」가 아니라 **「되돌려야 했던 게 몇 개였나」**로만 쓰기로 했어. 표본이 우리 하나뿐이라 그 이상은 말할 수가 없거든.

걸리는 게 하나 더 있어. 앤트로픽이 지우라고 한 건 Opus 5 얘기인데, 우리는 기계적인 일을 시킬 땐 더 가벼운 모델을 쓰거든.

찾아보니 가벼운 모델 쪽은 예전 긴 프롬프트를 그대로 쓴다는 관찰이 여럿 있더라고. 다만 앤트로픽이 직접 밝힌 건 아니라 거기까지는 확인 못 한 걸로 둘게.

지운 원문은 따로 파일에 옮겨 보관해뒀어. 되돌릴 자리는 있어야 하니까.

백 줄 넘게 지웠는데 후련하지가 않네

숫자로 정리하면 이래.

어디서 열든 깔리는 글로벌 + 공통이 273줄에서 184줄이 됐어.

그런데 지우는 동안 계속 아까웠어. 공통 지침 쪽은 하나하나가 사고 하나씩이었거든.

그날 뭘 잘못했고 그래서 뭘 하기로 했는지가 붙어 있는 것들이란 말이야. 그걸 지우려니 그날의 실수가 반복될 것 같고 말이지.

그래서 이번엔 「좋아졌다」는 말을 안 하려고 해. 아직 이틀도 안 됐고 대조군도 없으니까.

대신 이건 남았어. 시작할 땐 내가 적어둔 게 녀석을 돕고 있는지 방해하고 있는지가 알고 싶었어. 양이 많아 보이긴 하는데 그게 문제인지는 알 수가 없었거든.

원문을 다 열어보고서야 조금 감이 왔어. 앤트로픽도 양으로 자르지는 않았어. 뭘 시키고 있냐였지. 찾아보면 알 수 있는 건 빼고, 모르고 했다가 사고 나는 것만 남기라는 거야.

그래서 나도 항목마다 물어보게 됐어. 이건 매 대화에 실려야 하나, 지우면 사고가 나나. 이 둘은 나 같은 초보도 물어볼 수 있는 질문이니까.

이제 보름 뒤에 몇 줄을 도로 붙였는지 세보고 그때 다시 얘기할게.

P.S. 지침 파일이 처음 나온 기본 스킬 사용기와, 자동화가 조용히 실패하던 그 얘기도 이 글과 이어져 있어.