CLAUDE.md 모범 사례: Claude가 당신을 무시하지 못하게 하는 9가지 규칙 (2026)

CLAUDE.md 모범 사례: Claude가 당신을 무시하지 못하게 하는 9가지 규칙 (2026)

대부분의 CLAUDE.md 모범 사례 글은 템플릿 하나를 던져주고 끝내지만, 여러분이 지난주에 작성한 파일은 아마 이미 무시당하고 있을 가능성이 높습니다. 그리고 그 이유조차 모르고 있죠. 해결책은 '규칙을 더 추가하라'인 경우가 거의 없습니다. 보통은 그 반대입니다. 우리는 최근 모든 클라이언트 프로젝트에 Claude Code를 적용해 왔으며, 실제로 효과를 내는 9가지 규칙은 다음과 같습니다. Claude가 파일을 로드하는 방식에 맞는 계층 구조, 절대 깨뜨릴 수 없는 명령어 예산, AGENTS.md에 대한 의사결정, 그리고 Claude가 세션 도중 조용히 파일을 무시하는 6가지 이유입니다.

핵심 요약

• CLAUDE.md는 Claude Code의 컨텍스트에 로드되는 프로젝트 메모리로, 200줄 이내로 유지하지 않으면 규칙이 누락되기 시작합니다.
• 파일은 위에서 아래로 로드됩니다: 전역, 프로젝트 루트, 하위 디렉터리(지연 로드), 그리고 CLAUDE.local.md(개인용, gitignore 처리됨).
• Cursor나 Copilot도 함께 사용한다면 AGENTS.md를 사용하세요. CLAUDE.md를 AGENTS.md로 심볼릭 링크하면 두 도구를 동시에 대상으로 할 수 있습니다.
• Claude가 파일을 무시한다면, 90%는 길이, 모호함, 또는 "이유"의 부재가 원인입니다.

CLAUDE.md가 실제로 하는 일 (그리고 그것이 중요한 이유)

요약: CLAUDE.md는 Claude Code가 모든 세션 시작 시 프로젝트 메모리로 읽는 마크다운 파일입니다. 시스템 프롬프트도, 훅도, 스킬도 아니며, Claude가 팀의 컨벤션을 따르도록 유도하는 조언적 맥락입니다. 문서라기보다는 AI 페어 프로그래머가 실제로 읽는 설정 파일에 가깝다고 생각하세요.

많은 팀이 CLAUDE.md를 README처럼 작성합니다. 그게 첫 번째 실수입니다. README는 훑어보고 건너뛸 수 있는 사람을 대상으로 프로젝트를 설명합니다. CLAUDE.md는 세션 시작 시 Claude Code가 전체를 소비하며, 모든 줄이 토큰과 준수 비용을 발생시킵니다. 문서보다는 설정 파일이나 테스트 픽스처 모음에 훨씬 가깝습니다.

또한 Claude를 조종하는 유일한 방법도 아닙니다. **훅(Hooks)**은 결정적 동작(포맷팅, 커밋 차단)을 실행합니다. **스킬(Skills)**은 재사용 가능한 워크플로를 묶습니다. CLAUDE.md는 그 사이에서 조언적 맥락으로 자리하며, Claude는 이를 평가하고, 때로는 무시하고, 너무 많이 작성하면 분명히 일부를 잊어버립니다. 그 구분이 아래 모든 것의 기초이며, CLAUDE.md가 컨텍스트 엔지니어링이라는 더 넓은 실천의 도구 중 하나일 뿐 만능 해결책이 아닌 이유입니다.

규칙 #1: 문서가 아니라 코드처럼 다루세요. 버전 관리하세요. PR에서 리뷰하세요. 비대해진 모듈을 리팩토링하듯이 다듬으세요. Anthropic의 CLAUDE.md 가이드에 따르면, 이 파일은 모든 시스템 지시와 동일한 우선순위로 로드됩니다. 즉, 6개월 전의 낡은 규칙이 지금도 모든 응답에 능동적으로 영향을 미치고 있다는 뜻입니다.

CLAUDE.md 로드 방식: 4단계 계층 구조

요약: Claude Code는 네 단계에서 CLAUDE.md를 로드합니다. 전역(~/.claude/CLAUDE.md), 프로젝트 루트, 개인용 재정의용 CLAUDE.local.md, 그리고 Claude가 해당 디렉터리 내 파일을 읽을 때만 지연 로드(lazy-load) 되는 하위 디렉터리 파일입니다. 형제 관계의 하위 디렉터리들은 서로의 CLAUDE.md를 절대 보지 못하며, 덕분에 Claude Code 메모리를 좁은 범위로 유지할 수 있습니다.

이 계층 구조는 CLAUDE.md에서 가장 많이 오해받는 부분이며, 상위 5개 SERP 결과 중 어느 것도 깊이 다루지 않는 지점입니다. 내부에서 실제로 일어나는 일은 다음과 같습니다.

확실히 짚고 넘어가야 할 용어가 두 가지 있습니다. 지연 로딩(lazy loading) 과 형제 격리(sibling isolation) 입니다.

지연 로딩이란 하위 디렉터리의 CLAUDE.md가 Claude가 실제로 해당 디렉터리 내 파일을 열기 전까지는 Claude의 콘텍스트에 들어오지 않는다는 뜻입니다. "로그인 버그 고쳐줘"라고 요청했는데 Claude가 backend/만 건드린다면, 당신의 frontend/CLAUDE.md는 절대 로드되지 않습니다. 이는 좋은 일입니다. 콘텍스트 윈도우를 깨끗하게 유지해 주니까요. 하지만 항상 적용되리라 기대하고 하위 디렉터리에 중요한 규칙을 넣어둔 팀이라면 이 부분에서 발목을 잡힙니다.

형제 격리는 그 당연한 귀결입니다. frontend/CLAUDE.md와 backend/CLAUDE.md는 서로를 절대 로드하지 않습니다. 둘이 공유하는 것은 프로젝트 루트에 있는 내용뿐입니다. 그래서 프론트엔드 규칙이 백엔드 규칙과 충돌하더라도 문제없습니다. 둘이 규약을 공유해야 한다면, 루트 파일로 끌어올리세요.

CLAUDE.local.md는 비상 탈출구입니다. 로드되지만 커밋되지 않으며, "나는 pnpm을 선호하지만 팀은 npm을 표준으로 정했다" 같은 재정의에 안성맞춤입니다. 함정은 이것입니다. 자동으로 Gitignore 처리되지 않습니다. 직접 추가해야 합니다. 이걸 잊어버리면 개인 규칙을 팀 리포지토리에 커밋하게 됩니다. 규칙 #4: Claude가 실제로 읽는 위치에 맞춰 지침을 작성하세요. React 컴포넌트의 스타일 규칙은 루트가 아니라 frontend/CLAUDE.md에 작성해야 합니다. 데이터베이스 마이그레이션 규칙은 backend/에 작성해야 합니다. Anthropic Memory 문서(2025년 11월 업데이트)에서도 이를 확인할 수 있으며, 지연 로딩(lazy-load) 동작은 의도된 것으로 핵심적인 역할을 합니다.

CLAUDE.md에 무엇을 넣어야 하는가(그리고 무엇을 빼야 하는가)

요약하자면: CLAUDE.md에는 코드만으로 유추할 수 없는 모든 것을 넣습니다. 빌드 명령어, 네이밍 규칙, 팀이 실제로 겪으며 배운 안티 패턴, 그리고 각 규칙 뒤에 숨은 이유가 여기에 해당합니다. 반대로 README에 이미 있는 내용, package.json에 있는 내용, 그리고 매주 바뀌는 규칙은 빼야 합니다. claude code instructions는 테스트 가능하고 구체적이어야 합니다.

다음은 실제로 제 역할을 하는 최소한의 CLAUDE.md입니다:

# 프로젝트: techsy-app
## 명령어
- 빌드: `pnpm build` (Turbopack — Webpack 플래그는 적용되지 않음)
- 테스트: `pnpm test --run` (Jest가 아닌 Vitest를 사용합니다)
- 린트: `pnpm lint` (오류뿐 아니라 경고에서도 CI가 실패합니다)
## 컨벤션
- 기본적으로 서버 컴포넌트를 사용합니다. `'use client'`는 정말 필요한 경우에만 추가하세요.
  이유: 지난 분기에 클라이언트 컴포넌트를 과도하게 사용했더니 LCP가 8초까지 치솟았습니다.
- 데이터베이스 접근은 반드시 `lib/db/` 헬퍼를 통해서만 합니다. 라우트에서는 절대 raw SQL을 쓰지 마세요.
  이유: 행 수준 보안 정책이 이 헬퍼들에 정의되어 있기 때문입니다.
- 테스트는 검증 대상 파일 옆에 `*.test.ts`로 함께 배치합니다.
## 하지 말아야 할 것
- PR에 먼저 코멘트를 남기지 않고 새 의존성을 추가하지 마세요.
- `any`를 사용하지 마세요 — `unknown`을 사용하고 타입을 좁히세요.
## 어디를 봐야 할까
- 스키마: `db/schema.ts`
- 인증 흐름: `lib/auth/README.md`

Now compare that to the anti-pattern version most teams ship:

# 프로젝트 규칙

- 깔끔하고 유지보수하기 쉬운 코드를 작성하세요.
- 모범 사례를 따르세요.
- TypeScript를 제대로 사용하세요.
- 테스트가 통과하는지 확인하세요.
- 기존 패턴과 일관성을 유지하세요.
- 복잡한 로직은 문서화하세요.

두 번째 파일은 틀린 게 아니다. 그냥 쓸모가 없을 뿐이다. Claude는 이미 깔끔한 코드를 작성하고 싶어 한다. "일관성을 유지하라"는 Claude에게 어떤 패턴과 일관성을 유지해야 하는지 알려주지 않는다. Anthropic 엔지니어 Boris Cherny의 공개 예시들은 첫 번째 스타일, 즉 구체적인 명령, 명시된 도구, 그리고 코드베이스만으로는 분명하지 않은 결정의 이유 쪽으로 강하게 기울어 있다.

규칙 #2: 열망이 아닌 구체성을 담아라. "깔끔한 코드를 작성하라"는 열망이다. "서버 컴포넌트를 기본으로 하라. 'use client'는 정말 필요할 때만 추가하라"는 검증 가능하다. 같은 원칙이 좋은 프롬프트 엔지니어링의 기반이기도 하다. 구체적이고 검증 가능한 지시는 프롬프트에 있든 CLAUDE.md에 있든 모호한 열망을 이긴다.

규칙 #3: 모든 규칙이 왜 중요한지 설명하라. "이유"는 군더더기가 아니라, Claude가 엣지 케이스를 판단하는 방식이다. 이유가 있는 규칙("과도한 클라이언트화로 LCP 8초를 겪었다")은 비슷한 상황으로 일반화된다. 이유 없는 규칙은 맥락이 바뀌는 순간 무시된다. 이 패턴은 Builder.io의 CLAUDE.md 가이드에도 문서화되어 있다.

Claude는 왜 당신의 CLAUDE.md를 무시할까? 지시 예산

요약하자면: Claude는 악의적인 것이 아니라, 주의력(attention)이 바닥나고 있는 중이다. 대략 80줄이 넘어가면 규칙이 누락되는 것이 눈에 띄기 시작하고, 200줄이 넘어가면 큰 덩어리가 통째로 무시되며, 500단어 이상의 빽빽한 규칙이 쌓이면 준수율이 무너진다. 해결책은 **지시 예산(instruction budget)**이다. 모든 줄을 claude code 메모리와 규칙별 준수율에 대한 비용으로 취급하라.

최근 연구는 실전 사용자들이 계속 발견해 온 사실을 확인시켜 준다. 규칙의 개수가 늘어날수록 지시 준수율은 비선형적으로 떨어진다는 것이다. 지시 준수 용량에 관한 arxiv 논문 2507.11538은 규칙을 쌓을수록 규칙당 준수율이 하락함을 보여주며, 실전 환경의 CLAUDE.md에 대한 HumanLayer의 분석도 동일한 결론을 되풀이한다.

다시 말해, 규칙을 하나 추가할 때마다 다른 모든 규칙이 지켜질 확률이 조금씩 낮아진다. 따라서 400줄짜리 CLAUDE.md는 100줄짜리보다 4배 효과적인 것이 아니다. 오히려 덜 효과적인 경우가 많은데, 정작 당신이 중요하게 여기는 규칙들이 석 달 전 금요일에 적어 두고 한 번도 지우지 않은 규칙들에 의해 희석되기 때문이다.

우리의 CLAUDE.md 파일에서는 150줄을 넘어가는 부분부터 준수율이 눈에 띄게 떨어지기 시작한다. 250줄쯤 되면 Claude가 섹션 전체를 건너뛰는 것을 목격했다. 그래서 우리는 상한을 둔다.

wc -l CLAUDE.md

이것이 도구의 전부다. 실행해 보라. 200줄을 넘겼다면, 예산을 초과한 것이다. 우리가 고객에게 전달하는 확고한 규칙은 이것이다:

CLAUDE.md를 200줄 예산처럼 취급하라. 모든 줄은 준수율을 소모한다. 중요한 곳에 써라.

규칙 #1을 다시 강조한다: 짧게 유지하라. 200줄 미만으로. 빽빽한 규칙은 500단어 미만으로. 자동화 규칙("편집 후 항상 prettier를 실행해")을 추가하고 싶어지는 순간이 온다면, 그런 것들은 아마 Claude Code hooks에 넣는 편이 낫다. hooks는 결정론적이며 지시 예산 토큰을 소모하지 않기 때문이다.

CLAUDE.md, AGENTS.md, .cursorrules, copilot-instructions 중 무엇을 사용해야 할까?

요약: Claude Code만 사용한다면 CLAUDE.md로 충분하다. 하지만 2개 이상의 에이전트 CLI(Codex, Cursor, Copilot, Sourcegraph)를 사용한다면 AGENTS.md로 전환하고 CLAUDE.md를 AGENTS.md로 심볼릭 링크하자. AGENTS.md는 2025년 말 도구 간 표준으로 등장했으며, 대부분의 최신 에이전트가 이를 폴백으로 지원하므로 단일 파일로 모든 생태계를 커버할 수 있다.

이것은 상위 5개 검색 결과가 실제로 답하는 0번 질문이다. 매트릭스는 다음과 같다:

듀얼 타겟 트릭은 단 한 줄이다:

ln -s AGENTS.md CLAUDE.md

이게 전부다. 이제 Claude Code, Codex, 그리고 AGENTS.md를 인식하는 모든 도구가 같은 파일을 읽는다. 한 번만 업데이트하면 모든 에이전트가 이를 반영한다. AGENTS.md 명세는 공개되어 있고 의도적으로 최소한이며, 관례적인 섹션으로 구성된 마크다운일 뿐이다.

실무에서는 두 가지 걸림돌이 있다. 첫째: 팀에 Cursor 헤비 유저가 있다면, Cursor의 .cursorrules는 다른 접근 방식을 취한다. 단일 파일, 계층 구조 없음, 더 엄격한 형식이다. 일부 팀은 둘 다 유지한다. 공유 규칙은 AGENTS.md로, Cursor 전용 특이사항은 .cursorrules로 관리하는 식이다. 둘째: Copilot의 .github/copilot-instructions.md는 AGENTS.md로 폴백하지 않으므로, Copilot을 주로 쓰는 팀은 별도의 파일이 필요하다.

에이전트 스택을 처음부터 고르는 중이라면, 우리의 Claude Code vs Cursor vs Copilot 비교 글에서 사용 수준별 트레이드오프를 다룬다. 요약하자면: Claude Code의 계층 구조는 모노레포에 가장 강력하고, Cursor의 UX는 개인 작업에서 우위이며, Copilot의 IDE 통합은 점진적 도입 측면에서 여전히 가장 매끄럽다.

규칙 #9: 2개 이상의 에이전트 CLI를 사용한다면 AGENTS.md를 써라. 같은 내용을 담은 파일 두 개를 유지하지 말자. 스택의 대부분이 읽는 파일을 하나 고르고, 나머지는 심볼릭 링크로 연결하라.

CLAUDE.md vs Hooks vs Skills: 의사결정 삼각형

요약하자면: CLAUDE.md = 권고적 컨텍스트. Hooks = 결정론적 동작. Skills = 번들로 제공되는 기능. 잘못 선택하면 hook이 처리해야 할 일에 인스트럭션 예산을 낭비하거나, skill로만 제공할 수 있는 것에 CLAUDE.md 규칙을 작성하게 됩니다. 이 삼각형은 CLAUDE.md를 간결하게 유지하는 가장 저렴한 방법입니다.

세 가지 도구, 세 가지 역할. 우리가 가장 자주 보는 실수: "편집 후 항상 prettier 실행"을 CLAUDE.md에 넣는 것입니다. Claude는 그것을 읽습니다. Claude는 가끔 prettier를 실행합니다. 당신은 좌절합니다. 해결책은 그 줄을 CLAUDE.md에서 꺼내 hook으로 옮기는 것입니다. hook은 권고적 재량의 여지 없이 매번 결정론적으로 실행되기 때문입니다.

규칙이 항상 실행되어야 한다면 hook에 속합니다. Claude가 컨텍스트에 비추어 평가할 수 있는 스타일 선호라면 CLAUDE.md에 속합니다. 번들로 제공되는 애셋(템플릿, 스크립트, 프롬프트)을 수반하는 다단계 워크플로라면 skill에 속합니다.

규칙 #8: CLAUDE.md vs hooks vs skills를 올바르게 선택하라. hook을 CLAUDE.md에 넣는 것이 가장 흔한 인스트럭션 예산 낭비다. 결정론적 동작은 Claude Code hooks로 구성하고, 재사용 가능한 워크플로는 Claude skills로 패키징하세요. CLAUDE.md는 더 짧아지고, 가드레일은 더 견고해지며, Claude는 중요한 규칙을 "잊어버리는" 일을 멈춥니다.

모노레포 패턴: 중첩 CLAUDE.md, @import, 그리고 .claude/rules/

요약: 모노레포에서는 루트 CLAUDE.md를 최소한으로 유지하고, 포인터와 공통 컨벤션만 담으세요. 구체적인 내용은 apps/*/CLAUDE.md로 옮겨 각 서브트리가 자체 범위의 규칙을 갖도록 하세요. @import를 활용해 .claude/rules/로 모듈화된 규칙 파일을 공유하세요. 이것이 바로 점진적 공개입니다. Claude는 관련 있는 부분만 그때그때 가져옵니다.

전형적인 모노레포 CLAUDE.md 트리:

.
├── CLAUDE.md                        # 30 lines — points to subdirs and shared rules
├── .claude/
│   └── rules/
│       ├── style.md
│       ├── testing.md
│       └── security.md
├── apps/
│   ├── web/
│   │   └── CLAUDE.md                # Next.js-specific rules
│   └── api/
│       └── CLAUDE.md                # Fastify-specific rules
└── packages/
    └── shared/
        └── CLAUDE.md                # Library author rules

@import 구문을 사용하면 루트 파일에서 공유 규칙 조각을 반복해서 작성하지 않고도 가져올 수 있습니다:

# 루트 CLAUDE.md

이 프로젝트는 Turborepo입니다. 앱별 규칙은 하위 디렉터리의 CLAUDE.md를 참조하세요.

@import .claude/rules/style.md
@import .claude/rules/testing.md
@import .claude/rules/security.md
## 최상위 명령어
- `pnpm dev`는 모든 앱을 병렬로 실행합니다
- `pnpm test`는 모든 워크스페이스의 테스트 스크립트를 실행합니다

이것은 실제로 적용된 점진적 공개입니다. 루트 파일은 30줄짜리 포인터입니다. 각 하위 디렉터리의 CLAUDE.md는 50~80줄의 집중된 규칙을 추가합니다. .claude/rules/ 파일에는 여러 하위 디렉터리가 가져다 쓸 수 있는 규약 덩어리가 담겨 있습니다. 중복되는 것도 없고, 누락되는 것도 없으며, 어떤 파일도 지시 예산을 초과하지 않습니다.

앞서 나온 지연 로딩 규칙은 여기서 더욱 중요합니다. Claude가 apps/web/Button.tsx에서 작업할 때, 루트 파일과 apps/web/CLAUDE.md, 그리고 @import로 가져온 규칙 파일만 봅니다. apps/api/CLAUDE.md는 보지 않습니다. 이것이 바로 핵심입니다. 백엔드 규약이 프론트엔드 컨텍스트를 오염시키지 않아 컨텍스트 윈도우를 유용하게 유지할 수 있습니다.

규칙 #6: @import를 사용해 루트 파일을 200줄 이하로 유지하세요. Claude Code를 위한 Anthropic 모범 사례 가이드는 이를 표준 모노레포 패턴으로 다룹니다. 서브에이전트도 상위 CLAUDE.md 컨텍스트를 상속하는데, 워크플로를 중첩하고 있다면 알아둘 가치가 있습니다. 이것이 서브에이전트 설계와 어떻게 상호작용하는지는 컨텍스트 엔지니어링을 참고하세요.

Claude가 파일을 무시하는 6가지 이유 (각각의 해결책 포함)

요약: Claude가 CLAUDE.md를 무시할 때, 거의 항상 여섯 가지 원인 중 하나입니다: 파일이 너무 길거나, 표현이 모호하거나, "이유"가 빠져 있거나, 컨텍스트 압축이 발생했거나, 상위 파일과 충돌하거나, 파일명이 잘못된 경우. 각각은 60초면 해결할 수 있습니다. 변경할 때마다 새 세션에서 테스트하세요. 이것이 규칙 #7입니다.

1. 파일이 너무 긴 경우 (>200줄 / >500단어)

wc -l CLAUDE.md를 실행하세요. 200줄을 넘는다면 과감하게 줄이세요. 자동화 규칙은 hooks로 옮기세요. 워크플로는 skills로 옮기세요. 공유되는 청크는 .claude/rules/로 분리한 뒤 @import로 가져오세요. Claude가 규칙을 "따르지 않게 된" 가장 흔한 이유는, 시간이 지나며 파일이 너무 길어져 규칙 준수가 조용히 무너졌기 때문입니다.

2. 모호한 표현 ("clean code를 작성하라")

모든 지향점 수준의 규칙을 구체적이고 검증 가능한 규칙으로 바꾸세요. "일관성을 유지하라"는 Claude에게 보이지 않는 것과 마찬가지입니다. "기본적으로 서버 컴포넌트를 사용하고, 폼이나 인터랙티브 UI에만 'use client'를 추가하라"처럼 말해야 Claude가 실제로 적용할 수 있습니다.

3. "이유"의 부재

이유가 없는 규칙은 일반화되지 않습니다. Claude는 그 규칙이 무엇을 방지하기 위한 것인지 알지 못하기 때문에, 언제 규칙을 유연하게 적용해야 할지 추론할 수 없습니다. 자명하지 않은 모든 규칙에는 한 줄짜리 설명이 붙습니다. "우리가 any가 아니라 unknown을 쓰는 이유는, 지난 분기에 any로 타입이 지정된 API 응답 때문에 런타임 크래시가 세 번이나 발생했기 때문이다."

4. 컨텍스트 압축으로 인해 사라진 경우

세션이 길어지면 압축(compaction)이 발생하여 Claude가 컨텍스트 윈도우에 맞추기 위해 이전 내용을 요약하는데, 이 과정에서 CLAUDE.md의 내용이 통째로 사라져 버리는 경우가 있습니다. 해결책: 컨텍스트를 대량으로 소모한 작업 이후에는 /clear를 실행하거나, 세션을 완전히 다시 시작하세요. 이는 정확히 GitHub 이슈 #17530에서 지속적으로 제기되고 있는 문제입니다.

5. 상충하는 상위 CLAUDE.md

글로벌에는 "4칸을 사용하라"고 되어 있고, 프로젝트 루트에는 "2칸을 사용하라"고 되어 있으며, 하위 디렉터리에는 아무런 명시도 없다. Claude는 이 중 하나를 선택하는데, 때로는 잘못된 것을 고른다. ~/.claude/CLAUDE.md와 프로젝트 루트를 점검해 모순되는 부분이 없는지 확인하라. 더 구체적인 쪽이 우선해야 하지만, 이는 그것을 명시적으로 지정했을 때에만 그렇다.

6. 잘못된 파일 위치 또는 파일명 대소문자

Claude.md와 CLAUDE.md는 Linux와 macOS에서 서로 다른 파일입니다. claude.md와 CLAUDE.md도 마찬가지입니다. 경로가 정확히 ./CLAUDE.md(모두 대문자)인지 확인하고, Claude Code가 해당 파일이 포함된 디렉터리에서 실행되었는지 확인하세요. GitHub 이슈 #668에는 파일은 존재하지만 경로 문제로 Claude가 이를 인식하지 못한 사례가 가득합니다.

규칙 #7: 새 세션에서 테스트하세요. CLAUDE.md를 수정한 후에는 새 세션을 열고 Claude에게 "CLAUDE.md의 규칙을 요약해 줘"라고 요청하세요. 요약에 빠진 내용이 있다면, 파일이 제 역할을 하지 못하고 있는 것입니다.

10분 만에 첫 CLAUDE.md 만들기: 5단계 스타터

요약: /init를 실행해 초안을 만들고, 이유를 포함한 실질적인 규칙 6~10개로 다듬고, Claude가 알아야 할 명령어 3개를 추가하고, 팀에서 실제로 겪은 안티패턴 2개를 추가한 뒤, 새 세션에서 Claude에게 파일 요약을 요청해 테스트하세요. 총 소요 시간: 약 10분. 이 5단계 레시피는 모든 새 레포의 첫날에 저희가 사용하는 방식입니다.

1. /init를 실행해 초안을 만듭니다. Claude Code의 /init 명령어는 레포를 스캔해 CLAUDE.md 초안을 작성합니다. 생성된 내용을 그대로 배포하지 마세요. /init 출력물은 완성본이 아닌 시작점이며, 솔직히 생성된 내용의 대부분은 지워도 됩니다.

2. 이유가 포함된 실질적인 규칙 6~10줄로 다듬습니다. 일반적인 내용은 삭제하세요. README에 이미 있는 내용도 삭제하세요. 코드 자체에서 Claude가 추론할 수 없는 규칙만 남기세요.

3. Claude가 알아야 할 명령어 3개를 추가합니다. 빌드, 테스트, 린트. 정확한 명령어와 자명하지 않은 플래그를 포함하세요. Jest가 아니라 Vitest를 사용한다면, 그렇게 명시하세요.

4. 이 팀에서 실제로 겪은 안티패턴 2개를 추가합니다. 진짜 겪은 것들로요. "런타임 크래시가 세 번이나 났으므로 any를 사용하지 말 것"이 "TypeScript를 제대로 사용하세요"보다 항상 낫습니다.

5. 새 세션을 열고 검증합니다. Claude에게 "CLAUDE.md의 규칙을 요약해 줘"라고 요청하세요. 무언가 빠뜨린다면, 파일이 너무 길거나, 너무 모호하거나, "왜"가 빠져 있는 것입니다. 수정하고 반복하세요.

규칙 #5: /init만으로 자동 생성하지 마세요. /init는 완성본이 아닌 시작점입니다. 다듬는 데 쓰는 8분이야말로 가치가 있는 부분입니다.

자주 묻는 질문

CLAUDE.md 파일이란?

CLAUDE.md 파일은 Claude Code가 모든 세션 시작 시 프로젝트 메모리로 읽어들이는 마크다운 파일입니다. 이 파일은 여러분의 컨벤션, 명령어, 안티패턴을 Claude에게 알려주어 매번 추측하지 않아도 되게 합니다. 네 가지 수준에서 작동합니다: 전역, 프로젝트 루트, 하위 디렉터리(지연 로드), 그리고 gitignore에 넣어 관리하는 개인용 CLAUDE.local.md입니다.

CLAUDE.md 파일은 얼마나 길어야 할까?

200줄 미만, 밀도 높은 규칙 기준으로 500단어 미만으로 유지하세요. 이 기준을 넘어서면 Claude의 지시 이행 능력이 저하되며, 규칙을 하나 추가할 때마다 다른 모든 규칙이 지켜질 확률이 조금씩 낮아집니다. 고정된 예산으로 생각하세요. 더 많은 내용이 필요하다면 하위 디렉터리의 CLAUDE.md 파일로 나누고, 공통 부분은 @import로 가져다 쓰세요.

CLAUDE.md는 어디에 두어야 하나요?

메인 파일은 프로젝트 루트(./CLAUDE.md)에 두고 커밋합니다. 모노레포에서는 앱별 규칙을 위해 하위 디렉토리에 CLAUDE.md 파일을 추가하세요. 프로젝트 간 공통 설정은 ~/.claude/CLAUDE.md에 넣습니다. 커밋하고 싶지 않은 개인용 재정의는 CLAUDE.local.md를 사용하되, gitignore에 수동으로 추가해야 한다는 점을 기억하세요.

Claude가 내 CLAUDE.md를 무시하는 이유는?

90%의 경우 다음 세 가지 중 하나입니다. 파일이 너무 길거나(200줄 초과), 규칙이 모호하거나("깨끗한 코드 작성" 등), 또는 Claude가 규칙을 적용하는 데 활용할 수 있는 "이유"가 빠져 있는 경우입니다. wc -l CLAUDE.md를 실행한 다음, 구체성을 점검하세요. 새 세션에서 Claude에게 해당 파일을 요약해 달라고 요청하여 변경 사항을 테스트하세요.

CLAUDE.md를 사용해야 할까요, 아니면 AGENTS.md를 사용해야 할까요?

팀에서 Claude Code만 사용한다면 CLAUDE.md를 그대로 사용하세요. 두 개 이상의 에이전트 CLI(Codex, Cursor, Sourcegraph)를 사용한다면 AGENTS.md로 전환하고 CLAUDE.md를 해당 파일에 심볼릭 링크로 연결하세요: ln -s AGENTS.md CLAUDE.md. 최신 에이전트 CLI 대부분은 AGENTS.md로 폴백되므로, 파일 하나로 모든 도구에 대응할 수 있습니다.

/init를 실행해서 CLAUDE.md를 생성해야 하나요?

초안으로서는 예, 완성본으로서는 아니오입니다. /init는 저장소를 스캔해 시작용 파일을 만들어 주지만, 내용이 장황하고 일반적입니다. Anthropic과 HumanLayer 모두 /init 실행 후 과감하게 덜어 내라고 권합니다. 내용을 줄이고 "이유"를 설명하는 줄을 추가하는 데 쓰는 8분이야말로 이 파일이 실제로 쓸모 있어지는 순간입니다.

모노레포에서 CLAUDE.md 파일은 어떻게 작동하나요?

루트 CLAUDE.md는 최소한으로 유지하고, 포인터와 공유 규칙만 담습니다. 각 앱은 apps/*/CLAUDE.md를 통해 해당 범위만의 규칙을 가집니다. 하위 디렉터리 파일은 Claude가 해당 서브트리 내부의 파일을 읽을 때만 지연 로드되므로, 형제 디렉터리들은 서로 격리된 상태를 유지합니다. @import .claude/rules/style.md를 사용하면 모듈화된 규칙 조각들을 앱 전반에 중복 없이 공유할 수 있습니다.

CLAUDE.md, 훅, 스킬의 차이점은 무엇인가요?

CLAUDE.md는 참고용 컨텍스트로, Claude가 이를 읽고 대개는 따릅니다. 훅은 항상 실행되는 결정론적 동작입니다(포맷팅, 커밋 차단 등). 스킬은 에셋을 갖춘 재사용 가능한 워크플로를 위한 번들 기능입니다. 스타일 가이드에는 CLAUDE.md를, 엄격한 규칙에는 훅을, 프로젝트 전반에 걸쳐 반복할 다단계 작업에는 스킬을 사용하세요.

Techsy의 접근 방식

Techsy에서는 출시하는 모든 Claude Code 프로젝트에 150줄 이하의 CLAUDE.md와 AGENTS.md 심볼릭 링크를 포함합니다. 이 파일을 코드처럼 취급하여 버전 관리를 하고, PR에서 변경 사항을 검토하며, 병합 전 새 세션에서 다시 테스트합니다. 개발 워크플로우에 AI 에이전트를 통합하는 데 도움이 필요하신가요? 무료 상담 받기.