CLAUDE.md 규칙이 무시될 때, 줄이는 기준과 훅 설정
CLAUDE.md 규칙이 자꾸 무시된다면 파일을 줄이는 기준부터 보세요. 반드시 지킬 규칙을 훅으로 옮기고, 훅이 실패할 때 통과되지 않게 설정하세요.
이 사례, 나한테 해당될까요?
- 지금 해 보기CLAUDE.md가 200줄을 넘었거나 같은 규칙을 자꾸 다시 말하는 사람v2.1.283 이상에서 /doctor prompt-audit를 돌려 낡은 줄과 충돌하는 줄부터 찾기
- 조건 확인 후.env 읽기·강제 푸시처럼 절대 하면 안 되는 일이 있는 사람그 규칙을 PreToolUse 훅으로 옮기고, v2.1.295 이상인지 본 뒤 onFailure를 block으로 두기
- 기다려도 됨Claude Code를 가끔 짧게 쓰고 지시 파일이 몇 줄뿐인 사람지금 파일을 두고, 같은 지시를 반복하게 될 때 한 줄씩 더하기
공식 문서는 CLAUDE.md 준수를 보장하지 않으며, 훅도 스크립트가 검사하는 범위만 막습니다(2026-11-21 확인).
읽는 대신, 내 AI에게 시켜 보세요
지금 쓰는 지시 파일과 메모를 붙여 넣으면 줄마다 남길지, 옮길지, 자동 검사로 바꿀지, 지울지 분류하고 충돌하는 줄을 찾아 줍니다.
프롬프트 내용 펼쳐 보기프롬프트 내용 접기
당신은 AI 코딩 도구의 지시 파일을 정리하는 검토 담당자입니다. 아래에 붙여 넣은 자료만 근거로, 지시 파일의 줄마다 어디에 둘지 분류해 주세요. 지시 파일 내용: [CLAUDE.md나 AGENTS.md 같은 지시 파일 전문] 인수인계 메모나 결정 기록: [메모 전문, 없으면 없음] 프로젝트에서 실제로 쓰는 명령과 폴더: [확인한 것만, 예: 테스트 명령, 주요 폴더 이름] 분류 기준 - 남김: 거의 모든 작업에 필요하고, 코드나 저장소를 읽어서는 알 수 없는 규칙 - 경로 규칙으로 옮김: 특정 폴더나 파일 종류를 다룰 때만 필요한 규칙 - 별도 문서로 옮김: 가끔만 필요한 절차, 결정의 배경과 버린 대안 - 자동 검사 후보: 지켰는지 기계가 판정할 수 있는 금지·형식 규칙 - 삭제 후보: 코드나 설정에서 바로 알 수 있는 내용, 같은 말의 반복, 다른 줄과 부딪히는 낡은 내용 지킬 것 - 자료에 없는 명령, 폴더, 도구 기능, 버전을 지어내지 마세요. 모르면 "확인 필요"라고 적으세요. - 숫자, 경로, 명령은 자료에 적힌 그대로 쓰세요. 두 줄이 같은 항목에 다른 값을 말하면 하나로 고치지 말고 "충돌"로 표시하세요. - 날짜가 이미 지났거나 임시라고 적힌 내용은 "다시 확인"으로 표시하세요. - "이렇게 하면 반드시 지켜진다" 같은 보장 문구는 결과에 쓰지 말고, 뺀 문구와 이유를 한 줄씩 알려 주세요. - 파일을 직접 고치거나 검사 코드를 쓰지 말고, 분류와 이유만 적으세요. 출력 형식 1. 분류표: 원래 줄(앞 30자) / 분류 / 이유 한 줄 2. 충돌과 다시 확인 목록 3. 원래 줄 수와 정리 뒤 남길 줄 수 4. 자동 검사 후보마다 어느 순간에 무엇을 막을지 한 줄(코드 없이)
API 키·비밀번호·회사 내부 주소가 적힌 줄은 지우거나 가린 뒤 붙여 넣으세요.

Claude Code를 몇 주 쓰다 보면 CLAUDE.md에 규칙이 계속 쌓입니다. 고객 문구 규칙, 배포 순서, 지난주에 정한 결정까지 적다 보면 수백 줄이 되는데, 정작 Claude는 그중 몇 줄을 건너뜁니다.
이 글은 Claude Code로 사이트·자동화·콘텐츠 작업을 하는 1인 사업자와 실무자를 위한 글입니다. 2026년 11월 20일 레딧 r/ClaudeCode에서 오간 두 토론과 Claude Code 공식 문서를 대조해, 지시 파일에서 무엇을 남기고 뺄지와 꼭 지켜야 할 규칙을 훅으로 옮기는 순서를 정리했습니다. 그로우빗이 직접 실행해 본 설정은 아니며, 공개 자료로 확인한 범위만 적었습니다.
CLAUDE.md 규칙은 왜 안 지켜지나요?
Claude Code 공식 문서(2026년 11월 21일 확인)는 CLAUDE.md를 강제 설정이 아니라 Claude가 읽는 맥락으로 봅니다. 문서 설명으로는 CLAUDE.md 내용이 시스템 프롬프트 안이 아니라 그 뒤의 메시지로 들어가며, 특히 애매하거나 엇갈리는 지시는 지켜진다고 장담할 수 없습니다.
같은 문서는 파일마다 200줄 미만을 목표로 하라고 권합니다. 파일이 길어지면 매번 읽는 분량이 늘고, 규칙이 지켜지는 비율도 낮아진다는 이유입니다. 서로 어긋나는 지시가 있으면 어느 쪽이 적용될지 알 수 없다는 점도 짚습니다.
레딧 첫 토론(2026년 11월 20일 게시)의 작성자도 2,100회 넘게 세션을 돌린 경험이라며 같은 결론을 냈습니다. 대화가 길어지면 문장으로 쓴 규칙이 조용히 밀려난다는 주장이고, 댓글에서도 실패를 만드는 장치가 없으면 규칙은 권고로 취급된다는 의견이 이어졌습니다. 세션 수는 작성자 주장이며 외부에서 측정한 값은 아닙니다.
레딧 토론에서는 무엇을 남기고 뺐나요?
같은 날 올라온 둘째 토론(2026년 11월 21일 오전 한국 시간 관찰 댓글 42개)에서 점수가 가장 높은 댓글은 줄마다 한 가지를 묻자고 제안했습니다. 그 내용을 저장소에서 바로 다시 확인할 수 있는지를 줄마다 따져 보자는 제안이고, 코드로 알 수 있는 내용은 지운다는 비슷한 기준을 말한 댓글도 여럿 있었습니다.
| 판단 | 처리 |
|---|---|
| 저장소에서 다시 알 수 있음 | 지움(폴더 구조, 테스트 실행법, 버전 등, 낡은 사본이 오히려 해롭다는 의견) |
| 알 수 없고 거의 매 세션 필요 | CLAUDE.md에 남김(한 사용자는 약 40줄, 대부분 다른 파일을 가리키는 줄) |
| 알 수 없고 가끔만 필요 | 결정 하나를 파일 하나로(결정, 이유, 버린 대안) 두고 색인만 읽게 함 |
| 기계로 확인할 수 있음 | 테스트나 훅으로 바꿈 |
질문을 올린 작성자는 인수인계 파일을 약 1,170줄에서 240줄로 줄였고, 300줄을 넘으면 실패하는 테스트를 붙였다고 답했습니다. 규칙마다 생긴 이유를 한 줄 붙이면 Claude가 그 규칙을 함부로 정리하지 않는다는 경험담도 나왔습니다. 모두 사용자 보고이고 효과를 잰 수치는 없습니다.
공식 기능으로는 어떻게 나누나요?
공식 문서 기준으로 항상 읽히는 것과 필요할 때만 읽히는 것을 나누는 기능이 이미 있습니다. 줄을 옮길 곳은 아래 표처럼 고릅니다.
| 위치 | 읽히는 때 |
|---|---|
| CLAUDE.md | 매 세션 전부(파일마다 200줄 미만 권장) |
| .claude/rules/ 안 paths 지정 규칙 | 맞는 경로의 파일을 읽거나 고칠 때만 |
| @경로 가져오기 | 가져온 CLAUDE.md와 함께 읽혀 컨텍스트 절약 효과 없음 |
| 자동 메모리 MEMORY.md | 매 세션 앞 200줄 또는 25KB까지(이 컴퓨터에만 저장) |
자동 메모리는 지금 쓰는 컴퓨터 안에만 남습니다. 여러 컴퓨터에서 같은 저장소를 쓴다면 결정 기록은 저장소 안 파일로 두는 편이 맞습니다.
정리할 줄을 찾는 일은 v2.1.283(2026년 9월 25일)에 들어온 /doctor prompt-audit에 맡길 수 있습니다. 공식 문서에 따르면 낡은 모델용 지시, 없는 파일·명령 참조, 서로 부딪히는 파일을 찾아 수정안을 보여 주고, 요청하기 전에는 파일을 바꾸지 않습니다.
꼭 지켜야 할 규칙은 훅으로 어떻게 막나요?
훅은 정해진 순간에 Claude의 판단 없이 실행되는 명령입니다. 공식 문서는 Claude가 무엇을 하든 막아야 하는 일에는 CLAUDE.md 대신 PreToolUse 훅을 쓰라고 안내합니다. PreToolUse는 도구가 실행되기 직전에 도는 훅이고, 스크립트가 종료 코드 2로 끝나면 그 도구 호출이 막힙니다.
레딧 첫 글의 작성자는 비밀 파일 읽기·쓰기와 rm -rf·강제 푸시 같은 위험 명령을 PreToolUse 훅으로 막는다고 소개했습니다. 작성자 스스로 eval이나 base64를 거치는 우회는 못 막는다며 안전벨트 정도로 보라고 적었습니다.
모든 훅이 막을 수 있는 것은 아닙니다. 공식 표에서 PostToolUse는 도구가 이미 실행된 뒤라 막지 못하고, 종료 코드 2일 때 오류 내용을 Claude에게 보여 줄 뿐입니다. 댓글의 한 사용자는 PostToolUse 훅으로 Claude가 쓴 파일의 금지어를 검사하고, 위반 목록을 Claude가 다음 단계에서 고치게 한다고 했습니다.
훅 설정은 프로젝트의 .claude/settings.json(저장소에 올려 공유 가능)이나 ~/.claude/settings.json(내 컴퓨터의 모든 프로젝트)에 넣습니다.
훅이 실패하면 규칙이 그냥 통과되나요?
대부분은 그렇습니다. 공식 문서에 따르면 훅이 시작되지 못하거나 시간 안에 끝나지 않거나 0·2가 아닌 코드로 끝나면, 많은 이벤트에서 원래 동작이 그대로 진행됩니다. 경로를 잘못 적은 보안 훅은 아무것도 막지 못하는 셈입니다.
이를 막는 설정이 v2.1.295(2026년 10월 8일)에 추가된 onFailure입니다. command·http 훅에 "onFailure": "block"을 넣으면 실패했을 때도 종료 코드 2와 같이 막습니다. mcp_tool 훅은 v2.1.328 이상이 필요하고, Stop 훅처럼 Claude를 다시 일하게 만드는 이벤트에는 효과가 없습니다.
레딧 첫 글의 댓글에서 한 사용자가 이 빈틈을 짚었고, 작성자는 보안 훅 두 개에 이 설정을 넣겠다고 답했습니다. 작성자 저장소의 이 파일 변경 기록에는 2026년 11월 20일 실패 시 차단하도록 바꿨다는 커밋이 있고, 11월 21일(한국 시간) 저장한 파일에는 PreToolUse 훅 3개에 onFailure block이 들어 있습니다. 그로우빗은 이 설정을 받아 실행하지 않았으므로 공개 자료로 확인한 수준입니다.
훅 스크립트 경로를 잠시 없는 파일로 바꾸고, 그 훅이 걸리는 무해한 호출을 시켜 보세요(Bash 훅이면 ls, 파일 읽기 훅이면 시험용 파일 읽기). 호출이 막히고 onFailure 안내가 뜨는지 본 뒤 경로를 되돌립니다.
비용과 한국에서 쓸 조건은 무엇인가요?
Claude Code는 Claude 요금 페이지(2026년 11월 21일 확인) 기준 Pro 요금제부터 포함되며, Pro는 연간 결제 시 월 17달러, 월간 결제 시 20달러입니다(세금 별도). 원화 표시 요금은 이 확인 경로에서 보지 못했습니다.
CLAUDE.md, 경로 규칙, 훅, prompt-audit에 대한 별도 요금 안내는 공식 문서에서 찾지 못했습니다. 다만 지시 파일이 길수록 매 세션 컨텍스트를 더 쓰므로 사용 한도에 간접적으로 영향을 줍니다. 공식 문서는 한국어판(code.claude.com/docs/ko)도 있어 설정 이름을 대조하기 쉽습니다.
오늘 무엇부터 하면 되나요?
첫 토론에서 점수가 가장 높은 댓글도 남의 설정을 통째로 쓰지 말고 작게 시작해 직접 키우라는 내용이었습니다. 스킬과 MCP의 차이가 먼저 궁금하다면 Claude Code 스킬과 MCP 비교를, 설치가 처음이라면 Claude Code 무료 입문 강의를 먼저 보세요.
참고 자료
- ▸Claude Code Docs, 「How Claude remembers your project」(2026-11-21 확인) — https://code.claude.com/docs/en/memory
- ▸Claude Code Docs, 「Hooks reference」(2026-11-21 확인) — https://code.claude.com/docs/en/hooks
- ▸Claude Code Docs, 「Claude Code changelog」(2026-11-21 확인) — https://code.claude.com/docs/en/changelog
- ▸Claude, 「Plans & pricing」(2026-11-21 확인) — https://claude.com/pricing
- ▸Reddit r/ClaudeCode, 「Stop expecting CLAUDE.md prose to hold under pressure — here is the .claude/settings.json hook + local MCP architecture I settled on after 2,100+ sessions (MIT)」(2026-11-20) — https://www.reddit.com/r/ClaudeCode/comments/1y0u092/stop_expecting_claudemd_prose_to_hold_under/
- ▸Reddit r/ClaudeCode, 「My CLAUDE.md and handover notes got huge, how do you keep them lean?」(2026-11-20) — https://www.reddit.com/r/ClaudeCode/comments/1y0yaxq/my_claudemd_and_handover_notes_got_huge_how_do/
- ▸GitHub winstonkoh87/Athena-Public, 「.claude/settings.json」(2026-11-21 확인) — https://github.com/winstonkoh87/Athena-Public/blob/main/.claude/settings.json
함께 읽으면 좋은 글
Claude 실무 글을 먼저, 그다음 최신 글을 보여 드려요

클로드 코드 대화 기록에 남은 비밀번호, 지우기 전 할 일
클로드 코드 대화 기록에 비밀번호나 API 키를 붙여 넣었다면 기록부터 지우지 마세요. 교체, 노출 기간 확인, 기록 정리, 재발 방지 순서로 점검하세요.

깃허브 기여자에 Claude가 뜰 때 끄는 설정과 지우는 순서
깃허브 기여자 목록에 Claude가 보이면 커밋 기록 문제인지 화면 갱신 지연인지부터 나누세요. 앞으로 끄는 설정과 이미 남은 기록 처리 순서를 확인하세요.

Claude Code Code Mode, 켜기 전 확인할 조건
Claude Code Code Mode를 켜기 전에 버전·화면·계정 요건과 훅·자동 모드 제한을 확인하고, 같은 작업을 켜고 끄며 사용량을 비교해 보세요.