CLAUDE.md의 절반은 장식일 뿐입니다. AI는 그것을 단 한 번만 읽습니다.

여러분의 CLAUDE.md에 있는 규칙 중 일부는 규칙조차 아니어야 합니다.

그 규칙들이 틀렸기 때문이 아닙니다. 여러분이 잃어서는 안 될 중요한 사항들을 모델이 단 한 번 읽고 나서 서서히 잊어버리는 파일에 적어두었기 때문입니다. 선호도(Preference)는 살아남지만, 제약 사항(Constraint)은 그렇지 못합니다.

한 달 전 저는 열 가지의 CLAUDE.md 규칙을 게시했습니다. 가장 흔한 답변은 "열한 번째 규칙을 추가하세요"가 아니었습니다. 그보다 더 조용한 반응이었습니다. 바로 규칙들이 더 이상 지켜지지 않는다는 것이었습니다. 세션이 4만 토큰(tokens)에 도달하면, 모델은 건드리지 말라고 명령했던 파일을 수정하거나, 절대 해서는 안 된다고 굵은 글씨로 적어두었음에도 불구하고 곧바로 main 브랜치에 커밋(commit)해 버립니다. 어쩌면 제 파일에 들어있는 내용의 절반은 장식일지도 모릅니다. 장식이 아닌 나머지 절반은 저를 두렵게 만드는 부분입니다.

파일은 한 번만 읽힙니다. 하지만 여러분의 세션은 그렇지 않습니다.

Claude Code는 세션이 시작될 때 CLAUDE.md를 단 한 번 읽습니다. 그 후 지침들은 컨텍스트 윈도우(context window)에 머물며 모델의 주의(attention)를 끌기 위해 다른 모든 것들과 경쟁합니다. 세션이 길어질수록 하단에 위치한 규칙들은 가중치를 잃습니다. 모델이 명령을 거부하는 것이 아닙니다. 그 지침이 더 이상 지탱하는 힘(load-bearing)을 갖지 못하게 된 것입니다.

이 부분은 아무도 데모(demo)하지 않는 부분입니다. 토큰 0(token zero) 시점의 깨끗한 CLAUDE.md 스크린샷은, 작업이 어려워질 때 실제로 여러분이 머물게 되는 토큰 9만(ninety thousand) 시점에 대해서는 아무것도 알려주지 않습니다.

첫 번째 본능은 규칙을 더 크게 쓰는 것입니다

그래서 여러분은 제가 했던 것처럼 행동합니다. 모두 대문자로 쓰기. "IMPORTANT(중요)". "You MUST(반드시 해야 함)". 경고 이모지 상자 채우기.

효과는 있습니다. 잠시 동안은요. 큰 소리로 적은 문장은 조용한 문장보다 더 오래 주의를 붙잡아 둡니다. 그러다 세션이 길어지고 바빠지며, 차이(diff)가 커지고, 모델이 리팩터링(refactor)을 위해 세 번의 도구 호출(tool calls)을 거치고 나면, 그 큰 소리의 문장은 이제 모델 자신의 출력물 1만 토큰 아래에 파묻혀 버립니다. 어쨌든 쇠퇴합니다. 여러분은 겨우 한 시간 정도를 벌었을 뿐입니다.

그 본능은 한 가지 측면에서는 맞고 나머지 측면에서는 틀렸습니다. 어떤 규칙들은 실패해서는 안 된다는 점은 맞습니다. 하지만 강조(emphasis)가 그 규칙들이 실패하는 것을 막는 방법이라는 점은 틀렸습니다.

제약 사항을 문장으로 쓰는 것을 멈추세요

그래서 제가 서두에서 언급했던 전략을 구체화하여 말씀드리겠습니다. 여러분의 CLAUDE.md를 열고 모든 줄을 두 개의 더미(pile)로 나누십시오.

첫 번째 더미: 선호 사항(preferences). 명명 규칙(Naming style). 주석 밀도(Comment density). 선호하는 라이브러리. 만약 모델이 90,000번째 토큰(token)에서 이 중 하나를 놓치더라도, 여러분은 어깨를 으쓱하며 수정하면 그만입니다. 이런 것들은 CLAUDE.md에 속합니다. '제안(suggestion)'은 이들에게 정확히 적합한 형태입니다.

두 번째 더미: 단 한 번의 실수만으로도 비용이 크게 발생하는 줄들. '절대 main 브랜치에 커밋하지 마세요'. '완료되었다고 말하기 전에 항상 포매터(formatter)를 실행하세요'. '프로덕션 설정(production config)은 절대 건드리지 마세요'. 이것들은 선호 사항이 아닙니다. 이것들은 제약 사항(constraints)입니다. 그리고 파일 안에 문장으로 작성된 제약 사항은 하나의 '희망'일 뿐입니다.

두 번째 더미를 훅(hooks)으로 옮기십시오.

훅(hook)이란 하네스(harness)가 도구 호출(tool calls)을 실행할 때 그 주변에서 작동하는 코드입니다. 모델이 규칙을 기억하든 못하든 상관없이 실행됩니다. CLAUDE.md의 한 줄로 작성된 "절대 main 브랜치에 커밋하지 마세요"는 작동을 멈출 때까지 버티다 결국 실패합니다. 하지만 프리 커밋 훅(pre-commit hook)으로서의 커밋은, 운이 좋든 나쁘든, 5번째 토큰에서든 200,000번째 토큰에서든 코드에 의해 차단됩니다. 모델에게 묻는 것이 아니었기에, 모델의 성능이 저하되어도 이 규칙은 무너지지 않습니다.

통과해버리는 단 하나

제 파일에 있던 한 줄은 "먼저 확인하지 않고 마이그레이션(migration)을 실행하지 마세요"였습니다. 그 문장은 아무런 저항 없이 몇 주 동안 그 자리에 머물며 제 역할을 수행했습니다. 그러다 도구 호출(tool calls) 체인의 깊은 곳에서 진행된 어느 긴 디버깅 세션 중에, 모델이 그것을 실행해 버렸습니다. 규칙은 여전히 파일 안에 있었습니다. 다만 한 시간 전에 스크롤이 지나가 손이 닿지 않는 곳에 있었을 뿐입니다.

이것이 바로 비용의 형태입니다. 비용이 많이 드는 규칙을 제안(suggestion) 형태로 남겨두면 99번의 세션 동안은 잘 작동합니다. 하지만 100번째 세션이 바로 여러분이 사람들에게 떠들게 될 바로 그 사건이 됩니다. 훅(hook)이었다면 호출을 거부하고 다음으로 넘어갔을 것이고, 저는 사람들에게 할 말이 없었을 것입니다.

제가 실제로 의존하는 규칙들은 이제 짧은 목록이 되었으며, 그중 어느 것도 더 이상 CLAUDE.md에 살고 있지 않습니다. 그것들은 지치지 않는 코드 속에 살고 있습니다.

자신의 파일을 다시 읽어보세요

저는 200,000번째 토큰까지 유지되는 에이전트 설정(agent setups)을 구축합니다. 0번째 토큰에서 깨끗해 보이는 스크린샷은 결코 어려운 부분이 아니었습니다.

그러니 여러분의 파일을 다시 읽어보세요. 각 줄마다 스스로에게 물어보십시오. 만약 모델이 지금으로부터 9만 토큰 뒤에서 이 내용을 무시한다면, 내가 그것을 알아챌 수 있을까? 그리고 그것이 나에게 비용(손실)을 발생시킬까?

그 질문에 대한 답이 '예'인 줄들은 결코 규칙(rules)이 아니었습니다. 그것들은 그저 굵은 글씨(bold text)를 입고 있는 희망 사항이었을 뿐입니다. 여러분이 작성한 것 중 어떤 것이 제안(suggestions)이고, 어떤 것이 실제로 강제(enforced)되는 것입니까?

저는 실제 빌드 과정에서 얻은 현장 노트(field notes)를 작성합니다: AI 통합(AI integration), cron 기반 자동화(cron-driven automation), 그리고 프로덕션(production) 환경에서 고장 나는 부분들에 대한 기록입니다. 2주마다 새로운 포스트가 올라옵니다. 이 글이 유용했다면, human-in-the-loop 승인 플레이북이 함께 내려받을 수 있는 동반 자료입니다.