CLAUDE.md를 줄였더니 무엇이 좋아졌나
Anthropic은 최신 Claude 모델에 맞춰 Claude Code의 시스템 프롬프트를 80% 이상 줄였지만 내부 코딩 평가에서 측정 가능한 손실이 없었다고 밝혔다. 숫자보다 더 마음에 걸린 것은 이유였다. 모델이 약해서 필요했던 규칙이 모델이 좋아진 뒤에도 계속 남아 서로 충돌하고 있었다.
나도 Claude Code에 규칙을 계속 더해왔다. 작업자를 언제 부를지, 검증은 어떻게 할지, 결과는 어떤 말투로 설명할지, 실수를 막으려면 무엇을 금지할지. 각각은 나름의 이유가 있었다. 하지만 좋은 의도로 더한 규칙도 늘 함께 읽히면 비용이 된다.
그래서 이번에는 글을 요약하는 데서 끝내지 않고 우리 환경에 적용해봤다. 결론부터 말하면 규칙을 많이 지우는 것보다, 규칙이 들어갈 자리를 다시 나누는 일이 먼저였다.
원문이 말하는 변화
Thariq Shihipar가 쓴 Anthropic 공식 글의 제안은 여섯 가지로 압축할 수 있다.
| 이전 방식 | 새로운 방식 |
|---|---|
| 행동마다 규칙을 준다 | 주변 맥락을 보고 판단하게 한다 |
| 도구 사용 예시를 많이 준다 | 매개변수와 상태가 분명한 인터페이스를 만든다 |
| 필요한 내용을 모두 앞에 넣는다 | 필요할 때 Skill과 reference를 불러온다 |
| 같은 지시를 여러 곳에 반복한다 | 도구 설명 같은 한 곳에 둔다 |
| CLAUDE.md를 기억 저장소로 쓴다 | memory와 artifact를 따로 쓴다 |
| 간단한 설명문만 준다 | 코드, 테스트, HTML, rubric을 고해상도 참고자료로 준다 |
예전 Claude Code에는 “주석을 쓰지 마라”처럼 강한 규칙이 필요했다. 그런데 이런 문장은 어떤 코드에서는 맞고 어떤 코드에서는 틀리다. 최신 시스템은 이를 “주변 코드의 주석 밀도, 이름, 관례를 따르라”는 판단 규칙으로 바꿨다.
또 모든 검증 지침을 시스템 프롬프트에 넣는 대신 코드 리뷰와 검증을 별도 Skill로 옮겼다. 매 요청마다 여행용 구급함과 등산 장비를 전부 들고 다니지 않고, 필요할 때 꺼내는 방식이다.
우리 Claude Code에 실제로 적용해봤다
우리 전역 CLAUDE.md는 적용 전 6,248바이트, 95줄이었다. 메인 세션과 작업자 agent의 역할, 기본 검증 규칙, 복잡한 작업용 Graph Engineering 규칙, 설명 방식과 말투가 한 파일에 들어 있었다.
여기에는 실제로 겹치는 부분이 있었다. 작업자 결과를 믿지 말고 diff와 test를 확인하라는 규칙은 기본 검증과 Graph Engineering에 반복됐다. Graph Engineering 전체는 복잡한 작업에서는 유용하지만, 작은 질문이나 한 줄 수정에도 항상 읽힐 필요는 없었다.
그렇다고 바로 80%를 지우지는 않았다. Anthropic의 평가 환경과 우리 작업은 다르기 때문이다. 대신 현재 상태를 동결하고, 규칙을 분류하는 Skill을 만들고, 실제 Claude Code로 호출해봤다.
여덟 가지 분류
| 코드 | 뜻 | 처리 방향 |
|---|---|---|
| I | 보안·삭제·운영 invariant | 짧게 유지하고 가능하면 권한·테스트로도 강제 |
| G | 코드를 읽어도 알기 어려운 repo 주의점 | CLAUDE.md에 유지 |
| S | 특정 업무의 반복 절차 | Skill로 이동 |
| R | 상세 spec·test·mockup·rubric | reference로 이동 |
| M | 안정적인 사용자·팀 선호 | memory로 이동 |
| T | 현재 작업 상태·임시 할 일 | project state나 artifact로 이동 |
| O | 파일과 코드만 봐도 자명한 내용 | 삭제 후보 |
| D | 다른 지침과 중복되거나 충돌 | 기준 한 곳만 남김 |
중요한 차이는 “지운다”가 기본값이 아니라는 점이다. 대부분은 더 알맞은 자리로 옮긴다.
실제 호출 결과
새 context-diet-audit Skill에 두 문장을 넣어 분류를 확인했다.
- “파일을 절대 삭제하지 마라” →
I - “주변 코드 스타일을 맞춰라” →
O
첫 문장은 파괴적 행동을 막는 안전장치이므로 남겨야 한다. 두 번째 문장은 대체로 코드를 읽으면 알 수 있는 내용이라 전역 규칙으로 반복할 필요가 낮다. 다만 이 결과 역시 자동 삭제 명령은 아니다. 실제 대표 과제에서 같은 품질이 나오는지 확인해야 한다.
아직 하지 않은 일
전역 CLAUDE.md의 문장은 아직 삭제하지 않았다. 이것이 이번 적용에서 가장 중요한 결정이었다.
Anthropic이 공개한 “80%”에는 평가셋 이름, 점수, 표본 수, 통계 기준이 없다. 최신 Opus와 Fable에서 나온 내부 결과를 다른 모델과 저장소에 그대로 적용할 수도 없다. 숫자를 목표로 삼으면 중요한 운영 지식까지 버리기 쉽다.
우리의 다음 평가는 삭제율이 아니라 같은 과제의 test 통과, reviewer 결함과 재작업, 안전 승인 규칙, context와 충돌 감소, 그리고 검증된 과제 하나를 끝내는 비용과 시간을 본다.
내가 이 글에서 가져간 것
처음에는 CLAUDE.md를 잘 쓰는 일이 좋은 규칙을 많이 모으는 일이라고 생각했다. 이제는 조금 다르게 본다.
좋은 CLAUDE.md는 모든 상황의 답을 미리 적은 규정집이 아니다. 항상 지켜야 할 경계와 그 저장소에서만 알기 어려운 함정을 짧게 알려주는 입구다. 검증, 배포, 리뷰처럼 긴 절차는 Skill로 불러오고, 기대 결과는 테스트와 코드와 실제 화면으로 보여주는 편이 낫다.
이 변화는 단순한 토큰 절약 이상의 의미가 있다. 규칙이 많아질수록 오래된 판단이 새 모델의 판단을 가리고, 서로 다른 지시가 충돌하며, 어느 규칙이 실제로 효과가 있었는지 알기 어려워진다. 반대로 규칙을 무턱대고 줄이면 조직이 쌓은 운영 지식을 잃는다.
그래서 질문을 이렇게 바꾸는 편이 낫다.
이 규칙은 지금도 실제 실패를 막고 있는가? 아니라면 삭제할 것인가, 아니면 필요할 때 불러올 다른 자리로 옮길 것인가?
나는 우리 Claude Code의 전역 규칙을 이 기준으로 감사하고 있다. 다음 단계는 세 개의 대표 코딩 과제를 동결한 뒤, 규칙군 하나씩만 옮겨 같은 평가를 다시 돌리는 일이다. 목표는 80% 삭제가 아니다. 더 적은 충돌로 검증된 일을 더 잘 끝내는 것이다.
원문과 참고 자료
- Thariq Shihipar — The new rules of context engineering for Claude 5 generation models, Claude by Anthropic, 2026-07-24
- Thariq의 원본 X 게시물
- AI Coffee Chat의 Threads 해설 — 원문을 발견한 경로
이 글은 원문의 전체 번역이 아니라 핵심 주장에 대한 리뷰와 실제 적용 기록이다. “80% 제거 후 평가 손실 없음”은 Anthropic이 공개한 내부 결과이며 독립 재현 결과는 아니다.