AI가 실제로 규칙을 따르게 만드는 5가지 CLAUDE.md 패턴

CLAUDE.md 파일을 설정하고 200줄에 달하는 규칙을 집어넣었는데, AI가 결국 그중 절반을 완전히 무시하는 것을 본 적이 있나요?

당신만 그런 것이 아닙니다. AI 코딩 어시스턴트(AI coding assistants)를 위한 지침을 작성할 때 발생하는 아이러니는 바로 당신에게도 동일한 생산성 함정이 적용된다는 것입니다. 즉, 규칙이 많다고 해서 결과가 더 좋아지는 것은 아닙니다.

수십 개의 프로젝트 스타터(project starters)에서 실제 운영 중인 CLAUDE.md 설정을 관리하며 배운, 실제로 효과가 있는 다섯 가지 패턴을 소개합니다.

1. 800-토큰 규칙 (The 800-token rule)

가장 큰 CLAUDE.md 실수는 이를 문서(documentation)처럼 취급하는 것입니다. 이것은 문서가 아닙니다. 이것은 **시스템 프롬프트 접두사 (system prompt prefix)**이며, 시스템 프롬프트에는 작동 메모리 예산(working memory budget)이 있습니다.

대략적인 휴리스틱(heuristic): 기본 CLAUDE.md를 800 토큰(~600 단어) 미만으로 유지하세요. 그 이상이 되면, 긴 파일이 열려 있을 때 컨텍스트 압축(context compression)으로 인해 오래된 규칙들이 밀려나게 됩니다.

삭제해야 할 것:

근거 단락 ("우리가 이것을 하는 이유는...")
역사적 맥락 ("예전에는 X를 사용했지만 지금은...")
코드베이스 자체에서 명확히 알 수 있는 모든 것

규칙은 CLAUDE.md에 넣으세요. 근거는 관련 파일의 주석에 넣거나, 아예 넣지 마세요.

2. 하나의 거대한 파일이 아닌, glob 범위 지정 규칙을 사용하세요

Claude Code는 범위가 지정된(scoped) CLAUDE.md 파일을 지원합니다. 즉, src/api/CLAUDE.md에 있는 규칙은 src/api/ 하위의 파일이 열려 있을 때만 적용됩니다. 이를 활용하세요.

"인라인 스타일을 절대 사용하지 마라"는 프론트엔드 규칙은 AI가 Express 라우트(routes)에서 작업할 때 로드될 필요가 없습니다. "항상 매개변수화된 쿼리(parameterized queries)를 사용하라"는 백엔드 규칙은 CSS 애니메이션을 수정할 때 컨텍스트에 있을 필요가 없습니다.

실제적인 레이아웃:

CLAUDE.md              # 프로젝트 전역: 스택, 배포 프로세스, 핵심 불변량 (critical invariants)
src/api/CLAUDE.md      # API 전용: 인증 패턴, 에러 형식, 속도 제한 (rate limiting)
src/web/CLAUDE.md      # 프론트엔드 전용: 컴포넌트 컨벤션, 상태 패턴
...

각 파일은 300 토큰 미만으로 유지합니다. 한 번에 로드되는 총량은 약 600 토큰입니다. 여전히 예산 범위 내에 있습니다.

3. 규칙 하나당 하나의 관심사만 (One concern per rule)

복합 규칙은 조용히 실패합니다. 다음과 같이 작성할 때:

"함수는 작고, 순수하며, 이름이 잘 지어져야 하고, 명시적인 반환 타입(return types)을 가져야 하며, 서비스 파일에 있는 경우가 아니면 부작용(side effects)이 없어야 한다."

...AI는 자신이 동의하는 부분만 선택하고 나머지는 무시합니다. 이것은 모델 품질의 문제가 아니라 파싱(parsing)의 문제입니다. 복합 문장은 어떤 절이 제약 사항(constraint)이고 어떤 절이 제안(suggestion)인지에 대한 모호함을 생성합니다.

모든 복합 규칙을 원자적 문장(atomic statements)으로 분리하세요:

## Functions
- 최대 30줄. 초과할 경우 헬퍼(helpers) 함수로 추출할 것.
- 모든 내보내기(exported) 함수에 명시적인 반환 타입(return types)을 지정할 것.
...

세 줄의 문장, 세 개의 강제 가능한 제약 사항, 모호함 제로.

4. 부정적 규칙(Negative rules)이 긍정적 규칙(Positive rules)보다 효과적이다

"모든 스키마 검증에 Zod를 사용하세요"는 긍정적 규칙입니다. 이는 AI에게 무엇을 해야 할지는 알려주지만, 당신이 얼마나 강력하게 의도하는지는 알려주지 않습니다.

"any 타입을 절대 사용하지 마세요. Zod 스키마 없이 타입이 지정되지 않은 JSON.parse()를 절대 사용하지 마세요." — 이것들은 부정적 규칙입니다. 이들은 명확한 선을 긋습니다.

실제로 AI 어시스턴트는 권장 사항보다 금지 사항에 더 큰 가중치를 둡니다. 이는 금지 사항이 유효한 솔루션 공간을 줄여주어 강제하기가 더 쉬운 반면, 권장 사항은 단순히 선호도를 추가하는 것에 불과하여 다른 압박 속에서 우선순위가 밀리기 쉽기 때문입니다.

가능한 경우 긍정적 규칙을 부정적 규칙으로 재구성하세요:

긍정적 (Positive)	부정적 (Negative)
모든 설정에 환경 변수(environment variables)를 사용하세요	URL이나 자격 증명(credentials)을 절대 하드코딩하지 마세요
...

부정적인 프레임워크를 사용하면 위반 사항을 grep으로 찾기도 훨씬 쉽습니다.

5. CLAUDE.md를 프로덕션 환경이 구성된 스타터(starter)와 결합하세요

최고의 CLAUDE.md는 이미 자체 규칙을 따르고 있는 코드베이스를 설명하는 것입니다. 스타터 프로젝트에 ESLint가 구성되어 있고, TypeScript 엄격 모드(strict mode)가 켜져 있으며, 폴더 구조가 이미 잡혀 있다면 — CLAUDE.md의 규칙은 코드 자체에 의해 강화됩니다.

이것이 프로젝트 스타터에 시간을 투자할 가치가 있는 이유입니다. 만약 당신의 스타터 곳곳에 any 타입이 깔려 있고 린팅(linting)도 되어 있지 않다면, any를 금지하는 당신의 CLAUDE.md 규칙은 기존 코드베이스와 정렬되는 대신 기존 코드베이스와 싸우게 될 것입니다.

저희는 바로 이 문제를 해결하기 위해 Vibe Coder Kit를 특별히 제작했습니다. CLAUDE.md 규칙이 기존 코드의 동작 방식과 일치하도록 구성된 12가지 프로덕션 설정 스타터(Next.js SaaS, Express + JWT, Node CLI, Chrome Extension, Discord Bot, FastAPI 등)를 제공합니다. 별도의 설정 없이 즉각적인 AI 정렬 (AI alignment)이 가능합니다.

핵심 요약 (The one-line takeaway)

CLAUDE.md 파일은 대부분의 문서가 실패하는 것과 동일한 방식으로 실패합니다. 짧고, 최신 상태를 유지하며, 주관이 뚜렷해야 할 시점에 너무 길어지고, 오래되고, 포괄적으로 변해버립니다.

짧게. 범위를 좁게. 원자적으로 (Atomic). 가능한 한 부정적인 제약 사항 위주로. 그리고 이미 규칙을 따르고 있는 코드베이스를 기반으로.

이것이 바로 바이브 코딩 (vibe coding)을 실제로 작동하게 만드는 설정입니다.

BLN Craft는 AI 네이티브 워크플로우를 위한 개발자 도구를 만듭니다. 더 많은 정보를 원하시면 blncraft.com에서 저희를 팔로우하세요.