두 배 더 효율적으로 쓰는 CLAUDE.md 정리법
하루 6시간 만에AI 기초부터 나만의
서비스까지 완성
역할: 이 저장소의 CLAUDE.md를 점검해 지워도 되는 줄을 골라내는 담당 맥락: 규칙을 계속 더했는데 오히려 안 지켜집니다. 파일이 길어지면서 서로 부딪히는 지시가 있는지 저는 확인하지 못한 상태입니다. 작업: 아래 순서대로 진행하고, 각 항목마다 실제 줄을 인용하세요. 1. 이 저장소의 CLAUDE.md 파일을 전부 찾아 각각 몇 줄인지 세어 주세요. 2. 서로 부딪히는 지시를 찾아 주세요. 예: "필요하면 문서를 남겨라" 와 "주석을 달지 마라" 가 같이 있는 경우입니다. 3. 파일 구조나 코드를 보면 알 수 있는 내용을 골라 주세요. 디렉터리 이름, 사용 중인 프레임워크, 빌드 명령처럼 굳이 안 적어도 되는 것입니다. 4. 남길 것을 골라 주세요. 판단 기준은 "코드만 봐서는 알 수 없는 함정"입니다. 예: 특정 파일을 고치면 다른 곳이 깨진다, 이 폴더는 자동 생성이라 손대면 안 된다. 5. 하위 폴더로 내려도 되는 규칙과, 별도 스킬로 빼도 되는 절차를 구분해 주세요. 제약: 지금 당장 아무것도 지우지 마세요. 목록과 근거만 주세요. 추측으로 줄 수를 말하지 말고 실제로 읽은 값만 쓰세요. 비밀키와 자격 증명 파일은 읽지 마세요. 출력: ①파일별 줄 수 ②부딪히는 지시 쌍 ③코드에서 유도 가능해 지워도 되는 줄 ④남겨야 할 함정 ⑤하위로 내리거나 스킬로 뺄 것. 각각 근거를 한 줄씩 붙여 주세요. 검증: ③으로 고른 줄을 실제로 지웠을 때 클로드가 그 정보를 코드에서 찾아낼 수 있어야 합니다. 하나라도 못 찾으면 그 줄은 남기고 이유를 알려 주세요.
이런 분을 위한 글입니다
- CLAUDE.md에 규칙을 계속 더하는데 잘 안 지켜지는 분
- 파일이 길어져서 뭘 지워야 할지 모르는 분
- 스킬과 CLAUDE.md 중 어디에 적어야 할지 헷갈리는 분
읽고 나면 무엇을 남기고 무엇을 지울지 기준 하나를 갖게 됩니다.
만든 쪽이 자기 것부터 덜어냈습니다
앤트로픽에서 클로드 코드를 만드는 사람이 최근에 글을 하나 냈습니다. 요지는 이렇습니다 — 자기들이 클로드 코드를 과하게 제약하고 있었다는 것입니다.
내부에서 실제로 쓴 기록을 열어 보니, 한 요청 안에 서로 부딪히는 지시가 여러 개 들어가 있었습니다. 시스템 프롬프트와 스킬과 사용자 요청이 각자 다른 말을 하고 있었던 것입니다. 이를테면 한쪽에서는 필요하면 문서를 남기라고 하고, 다른 쪽에서는 주석을 달지 말라고 합니다.
클로드는 대개 의도를 알아채서 맞는 답으로 갑니다. 문제는 거기까지 가는 데 생각을 더 써야 한다는 점입니다. 겹치고 부딪히는 메시지를 먼저 정리한 다음에야 무엇을 할지 정합니다.
그래서 그들은 시스템 프롬프트에서 상당 부분을 덜어냈습니다. 규칙이 사라진 자리는 모델의 판단이 채웁니다.
덜어낸 양은 80% 이상입니다. 그런데 코딩 평가에서 측정할 수 있는 성능 저하가 없었습니다. 앤트로픽은 이 작업을 unhobbling 이라고 불렀습니다. 족쇄를 푼다는 뜻입니다.
같은 일이 각자의 파일에서도 일어납니다. 규칙은 한 번 넣으면 잘 안 빠집니다. 클로드가 안 지킬 때 사람이 하는 일은 대체로 문장을 더 세게 고쳐 쓰는 것입니다. 그렇게 쌓인 문장이 지금 답을 깎고 있습니다.
지울 것 셋, 남길 것 넷
| 지울 것 | 어떻게 생겼나 | 왜 해로운가 |
|---|---|---|
| 앞뒤가 안 맞는 규칙 | "문서는 자세히" 와 "설명은 짧게" 가 같이 있다 | 둘 중 하나를 고르느라 매번 다르게 답한다 |
| 늘 읽히는 설명 | 이번 작업과 무관한 절이 파일에 상주한다 | 맥락을 먹고, 정작 필요한 지침이 묻힌다 |
| 절대·반드시로 시작하는 말 | 안 지켜서 계속 세게 고쳐 쓴 문장 | 옛 모델용 가드레일이라 판단을 막는다 |
남기는 자리는 넷입니다. 시스템 프롬프트에는 제품 맥락과 하네스 구성을, CLAUDE.md 에는 이 저장소만의 함정을, Skills 에는 필요할 때 찾아 읽는 안내서를, 참조 자료에는 명세·테스트·평가 기준표를 둡니다.
바뀐 것 여섯 가지
예전에는 맞았지만 지금은 아닌 것들입니다.
| 예전 | 지금 |
|---|---|
| 규칙을 준다 | 판단하게 둔다 |
| 예시를 준다 | 인터페이스를 설계한다 |
| 앞에 다 넣는다 | 필요할 때 꺼내게 한다 |
| 반복해서 적는다 | 도구 설명에 한 번만 적는다 |
| CLAUDE.md에 기억시킨다 | 자동 메모리에 맡긴다 |
| 단순한 명세를 준다 | 실물 참조를 준다 |
세 번째와 다섯 번째가 특히 크게 바뀐 부분입니다.
규칙 → 판단
예전 시스템 프롬프트에는 주석을 쓰지 말라거나 여러 줄 설명 블록을 만들지 말라는 강한 지시가 있었습니다. 오래된 모델은 그런 울타리가 없으면 엉뚱한 주석을 달았기 때문입니다.
지금은 그 자리에 "주변 코드처럼 써라" 는 취지의 한 문장이 들어갑니다. 주석 밀도와 이름 짓는 방식을 옆 코드에 맞추라는 것입니다. 규칙 다섯 줄이 판단 기준 한 줄로 바뀌었습니다.
앞에 다 넣기 → 필요할 때 꺼내기
코드 리뷰와 검증 방법은 늘 필요한 정보가 아닙니다. 필요할 때만 결정적으로 중요합니다. 그래서 그런 내용을 각각 스킬로 빼서 필요할 때만 불러오게 바꿨습니다.
도구도 마찬가지입니다. 일부 도구는 정의를 미리 싣지 않고, 쓸 때가 되면 찾아서 불러오는 방식으로 바뀌었습니다. 그래야 도구를 많이 가지고도 자리를 안 차지합니다.
이 방식을 내 파일에도 그대로 쓸 수 있습니다. CLAUDE.md와 스킬 문서를 "언젠가 쓸지 모르는 모든 관행의 저장소"로 만들 필요가 없습니다. 안 그러면 못 찾을 거라는 생각은 사실이 아닙니다. 필요할 때 열리는 파일 나무로 두는 편이 낫습니다.
내 CLAUDE.md에 적용하기
원문이 제시하는 기준은 간단합니다.
- 저장소가 무엇인지는 짧게 적습니다
- 토큰의 대부분은 코드베이스의 함정에 씁니다. 예를 들어 타입을 한 파일에만 모아 두고 다른 곳에는 두지 않는다는 규칙 같은 것입니다
- 파일 구조나 저장소를 보면 알 수 있는 뻔한 것은 적지 않습니다
- 상세한 내용은 별도 스킬로 빼고 CLAUDE.md에서는 그것을 가리키기만 합니다
마지막 항목이 실무에서 가장 많이 어긋나는 지점입니다. 쓰는 프레임워크 이름, 폴더 구조, 빌드 명령은 클로드가 파일을 열어 보면 알 수 있습니다. 그걸 적어 두면 매 세션 값을 내면서 아무것도 못 얻습니다.
남길 것은 코드만 봐서는 모르는 것입니다. "이 폴더는 자동 생성이라 손대면 안 된다", "여기를 고치면 저기가 깨진다" 같은 것입니다.
자동으로 점검하는 방법이 생겼습니다
직접 고르기 어렵다면 도구가 대신 짚어 줍니다.
/doctor
이 명령에는 저장소에 커밋된 CLAUDE.md에서 클로드가 코드베이스로부터 알아낼 수 있는 내용을 잘라내라고 제안하는 검사가 들어 있습니다. 앞 절의 기준이 그대로 기능이 된 것입니다.
스킬은 쪼갭니다
스킬은 필요할 때 정보를 찾게 해 주는 가벼운 안내서로 봅니다. 과하게 제약하지 않는 편이 좋고, 정말 중요한 영역에서만 강하게 씁니다.
길어진 스킬은 한 파일에 몰아넣지 말고 여러 파일로 나눕니다. 그래야 필요한 부분만 열립니다.
스킬이 가장 값어치 있을 때는 나만의 판단이 담길 때입니다. 우리 팀이 이 문제를 어떻게 보는지, 이 제품에서는 무엇을 좋게 치는지 같은 것입니다. 일반적인 모범 사례는 굳이 적지 않아도 됩니다.
참조는 설명보다 실물로
작업에 필요한 자료는 @ 로 파일을 가리켜 붙일 수 있습니다.
여기서 기준이 하나 있습니다. 설명보다 코드가 낫습니다. 디자인을 말로 적거나 화면을 캡처해서 주는 것보다, 실제로 동작하는 HTML 하나를 주는 편이 결과가 낫습니다. 클로드가 아주 잘 아는 언어로 된 지시이기 때문입니다.
명세도 마찬가지입니다. 문서 대신 테스트를 주거나, 다른 저장소에 있는 함수를 가리켜 이걸 옮기라고 할 수 있습니다.
한계
- 여기서 말하는 "덜어내라"는 최신 모델 기준입니다. 이전 세대에서는 그 울타리가 실제로 필요했습니다
- 원문은 앤트로픽이 자사 제품을 두고 쓴 글입니다. 사내 사정에 맞춘 판단이 섞여 있을 수 있습니다
/doctor의 제안은 후보이지 정답이 아닙니다. 지우기 전에 그 정보를 클로드가 코드에서 찾아낼 수 있는지 한 번 확인하십시오- CLAUDE.md를 줄이는 것은 비용을 줄이는 방법이지 성능을 올리는 방법이 아닙니다
출처
- Thariq(앤트로픽) 원문 X 글 — 클로드 5 세대 모델의 컨텍스트 엔지니어링 (2026-07-25, 조회 470만·북마크 33,000)
- Claude Code 공식 변경 기록 —
/doctor에 커밋된 CLAUDE.md 를 다듬도록 제안하는 검사가 추가된 항목 - 국내 사용기 — 대규모 프로젝트의 루트 CLAUDE.md 가 30줄이었고 파일 23개 중 실제로 매번 읽히는 것은 두 개였다는 실측
명령 이름과 기능은 실제 변경 기록에서 확인한 것만 적었습니다. 확인하지 못한 주장은 넣지 않았습니다.
공식 자료
- Thariq Shihipar(Anthropic), 「The new rules of context engineering for Claude 5 models」, 2026-07-24 — 클로드 블로그에도 게재
- 국내 소개 — GeekNews