CLAUDE.md 가이드: AI에 프로젝트의 전체 맥락 제공하기
2025년 초부터 Claude Code를 매일 사용해온 저는 유용한 결과물을 얻기 위한 가장 큰 요소가 프롬프트 엔지니어링이나 영리한 트릭이 아니라 맥락이라는 것을 확실히 말할 수 있습니다. 구체적으로는 프로젝트 루트에 있는 잘 작성된 CLAUDE.md 파일입니다. 이 하나의 파일이 AI 어시스턴트가 코드베이스와 싸우는 것과 몇 개월 동안 팀에 있던 시니어 개발자처럼 느껴지는 것의 차이를 만듭니다.
Claude Code에 프롬프트를 던졌는데 일반적이고, 잘못되었거나 답답한 결과를 받아온 적이 있다면, 이 가이드는 당신을 위한 것입니다. CLAUDE.md를 정확히 어떻게 구조화하는지, 무엇을 포함하고 무엇을 제외할지, 그리고 Social Animal에서 출시한 프로덕션 프로젝트의 실제 예시를 공유하겠습니다.
목차
- CLAUDE.md란 무엇이고 왜 중요한가
- Claude Code가 프로젝트 맥락을 읽는 방식
- 훌륭한 CLAUDE.md 파일의 구조
- 섹션별 상세 분석
- 실제 CLAUDE.md 예시
- AI 맥락을 망치는 일반적인 실수
- CLAUDE.md와 다른 AI 맥락 파일들
- 대규모 프로젝트를 위한 고급 패턴
- 영향 측정하기
- 자주 묻는 질문
CLAUDE.md란 무엇이고 왜 중요한가
CLAUDE.md는 Claude Code가 매 세션마다 자동으로 읽는 저장소 루트에 놓는 마크다운 파일입니다. 이것을 AI 페어 프로그래머를 위한 온보딩 문서로 생각하세요. 새로운 개발자가 팀에 합류할 때, 당신은 단순히 노트북을 건네주고 "알아서 해"라고 말하지 않습니다. 당신은 아키텍처를 설명하고, 이상한 부분들을 설명하고, 지뢰를 지적합니다. CLAUDE.md는 Claude에게 동일한 역할을 합니다.
CLAUDE.md 없으면 Claude Code는 파일 구조, package.json, 그리고 우연히 읽은 모든 파일들로부터 모든 것을 추론해야 합니다. 이것은 새로운 직원에게 무작위로 선택된 소스 파일들을 읽게 함으로써 전체 시스템을 이해하도록 요청하는 것과 같습니다. 일부는 맞게 이해하겠지만, 모두의 시간을 낭비하는 잘못된 가정도 만들 것입니다.
견고한 CLAUDE.md를 가지면, 첫 시도에서의 작업 완료 정확도가 약 60%에서 90% 이상으로 뛰어오르는 것을 봤습니다. 이것은 작은 개선이 아닙니다 — AI 보조 개발이 생산성 승수인지 답답한 시간 낭비인지의 차이입니다.
Claude Code가 프로젝트 맥락을 읽는 방식
Claude Code는 맥락을 로드하는 특정한 계층 구조를 가지고 있습니다. 이를 이해하는 것은 프로젝트 메모리를 어떻게 구성할지에 영향을 미치기 때문에 중요합니다.
맥락 로딩 순서
- ~/.claude/CLAUDE.md — 글로벌 환경설정 (모든 프로젝트에 적용)
- ./CLAUDE.md — 저장소 루트의 프로젝트 레벨 파일
- ./subdirectory/CLAUDE.md — 디렉토리별 재정의
- .claude/settings.json — 프로젝트별 도구 권한 및 설정
- 세션 맥락 — 현재 대화에서 Claude에게 알려주는 것
프로젝트 레벨 CLAUDE.md가 대부분의 시간을 보낼 곳입니다. 글로벌 파일은 개인 환경설정("나는 함수형 컴포넌트를 선호한다" 또는 "항상 TypeScript strict 모드를 사용한다")에 좋지만, 진정한 가치는 프로젝트별 맥락에 있습니다.
여기서 중요한 것: Claude Code는 매 세션의 시작에 CLAUDE.md를 읽지만, 제한된 맥락 윈도우 공간도 있습니다. CLAUDE.md가 5,000단어의 산만한 문서라면, 실제 코드 추론에 사용될 수 있는 토큰을 낭비하고 있는 것입니다. 간결하세요. 구체적이세요. 모든 줄이 그 자리에 있을 가치가 있어야 합니다.
훌륭한 CLAUDE.md 파일의 구조
여러 프로젝트에서 CLAUDE.md 파일을 작성하고 다듬은 후 — Next.js 앱, Astro 사이트, 헤드리스 CMS 통합, API 서비스 — 효과가 있는 일관된 구조에 도달했습니다.
이상적인 구조
# 프로젝트 이름
## 개요
이 프로젝트가 무엇을 하고 누구를 위한 것인지 설명하는 한 단락.
## 기술 스택
정확한 버전 및 프레임워크.
## 아키텍처
각 부분이 어떻게 맞춰지는지.
## 주요 규칙
코딩 표준, 명명 패턴, 파일 구조 규칙.
## 자주 사용하는 명령어
빌드, 테스트, 배포 및 개발 명령어.
## 중요한 맥락
코드에서 명백하지 않은 것들.
## 알려진 문제 / 함정
피해야 할 지뢰들.
## 하지 마세요
AI가 절대 해서는 안 될 명시적인 것들.
각 섹션을 자세히 살펴봅시다.
섹션별 상세 분석
개요
최대 2-3문장으로 유지하세요. Claude는 당신의 제품 로드맵이 필요하지 않습니다 — AI가 맥락에 맞는 결정을 할 수 있도록 도메인을 이해해야 합니다.
## 개요
이것은 공급망 관리를 위한 B2B SaaS 플랫폼인 Acme Corp의 마케팅 사이트입니다. 사이트는 Next.js를 사용하여 정적으로 생성되며, 동적 API 라우트는 폼 처리 및 리드 수집용입니다. 콘텐츠는 마케팅 팀에 의해 Sanity CMS를 통해 관리됩니다.
기술 스택
정확하세요. 단순히 "React"라고만 말하지 마세요 — 버전, 프레임워크, 렌더링 전략을 지정하세요. 이것은 React 18에서는 작동하지만 React 19에서 깨지는 패턴을 제안하거나 App Router를 사용 중인데 Pages Router를 권장하는 것을 방지합니다.
## 기술 스택
- **프레임워크**: Next.js 15.1 (App Router, RSC 기본값)
- **언어**: TypeScript 5.7 (strict 모드)
- **스타일링**: Tailwind CSS v4 (CSS-first 구성)
- **CMS**: Sanity v3 (라이브 프리뷰 포함)
- **배포**: Vercel (프로덕션 + 프리뷰 환경)
- **패키지 매니저**: pnpm 9.x
- **Node**: v22 LTS
- **테스팅**: Vitest + Playwright
- **상태 관리**: Zustand (최소, 클라이언트 UI 상태만)
아키텍처
대부분의 사람들은 너무 적게 쓰거나 너무 많이 씁니다. 당신은 시스템 설계 문서를 작성하는 것이 아닙니다. 당신은 Claude에게 정신 모델을 주고 있습니다.
## 아키텍처
- `app/` — Next.js App Router 페이지 및 레이아웃
- `app/api/` — API 라우트 (폼 제출, 웹훅)
- `components/` — 공유 UI 컴포넌트 (원자 설계: atoms/, molecules/, organisms/)
- `lib/` — 유틸리티 함수, API 클라이언트, 타입 정의
- `lib/sanity/` — Sanity 클라이언트, 쿼리 (GROQ), 타입 생성
- `content/` — 블로그 포스트 MDX 파일 (프론트매터와 함께 코로케이션)
- `public/` — 정적 자산 (모든 이미지에 next/image 우선)
데이터 흐름: Sanity CMS → lib/sanity/queries.ts의 GROQ 쿼리 → 서버 컴포넌트 → 클라이언트 컴포넌트 (상호작용이 필요할 때만)
모든 페이지는 빌드 시간에 정적으로 생성되며, /blog/[slug]/preview는 draft 모드를 사용합니다.
주요 규칙
이 섹션이 가장 많은 시간을 절약합니다. 이것이 없으면 Claude는 팀의 선택과 충돌할 수 있는 일반적인 모범 사례를 따를 것입니다.
## 주요 규칙
- 컴포넌트는 PascalCase로 명명되고, 파일당 하나의 컴포넌트
- 이름있는 exports 사용, 절대 default exports 없음 (pages/layouts 제외)
- 모든 데이터 가져오기는 서버 컴포넌트에서 발생 — useEffect를 데이터 가져오기에 절대 사용하지 마세요
- API 응답 타입은 lib/types/에 있고, Sanity 스키마에서 자동 생성됨
- 조건부 클래스 병합에는 `cn()` 유틸리티 (lib/utils.ts) 사용, 템플릿 리터럴 아님
- 에러 바운더리는 각 주요 페이지 섹션을 감싸고, 전체 페이지를 감싸지 않음
- 모든 폼 처리는 react-hook-form + zod 검증 스키마 사용
- 커밋 메시지는 Conventional Commits 따름 (feat:, fix:, chore:)
자주 사용하는 명령어
이것은 기본적인 것처럼 보이지만, Claude Code는 실제로 이 명령어들을 실행합니다. Claude가 올바른 것을 모르면 추측할 것이고, 종종 잘못 추측합니다.
## 자주 사용하는 명령어
- `pnpm dev` — 개발 서버 시작 (포트 3000)
- `pnpm build` — 프로덕션 빌드
- `pnpm lint` — ESLint + Prettier 확인
- `pnpm test` — Vitest 단위 테스트 실행
- `pnpm test:e2e` — Playwright E2E 테스트 실행
- `pnpm sanity:typegen` — 스키마 변경 후 Sanity 타입 재생성
- `pnpm db:migrate` — Drizzle ORM 마이그레이션 실행
중요한 맥락
Claude가 코드를 읽음으로써 알아낼 수 없는 것들을 위한 것입니다. 비즈니스 로직, 외부 제약, 인간 리뷰어가 30분을 들여 설명해야 할 것들입니다.
## 중요한 맥락
- 모든 CMS 페이지에는 ISR (revalidate: 3600)을 사용합니다. 절대 필요한 경우가 아니면 절대 `force-dynamic`을 사용하지 마세요.
- /api/revalidate의 Sanity 웹훅이 온디맨드 재검증을 처리합니다 — 수동 재검증 로직을 추가하지 마세요.
- 이미지 최적화는 Sanity의 CDN (cdn.sanity.io)을 통해 진행되며, CMS 콘텐츠에는 next/image를 사용하지 않습니다.
- 인증은 Clerk에 의해 처리됩니다 — 절대 커스텀 인증 흐름을 구축하지 마세요.
- /api/leads 엔드포인트는 Upstash Redis를 통한 속도 제한이 있습니다. 속도 제한 미들웨어를 제거하지 마세요.
알려진 함정
모든 프로젝트에는 이상한 것들이 있습니다. 여기에 넣어서 Claude가 그것에 걸리지 않도록 하세요.
## 알려진 함정
- Sanity의 portable text 렌더러는 v3.2에서 중첩 목록에 버그가 있습니다. components/portable-text/list-fix.tsx에서 커스텀 직렬화기를 사용합니다
- Tailwind v4는 모듈 CSS 파일에서 `@apply` 지시문을 지원하지 않습니다 — 대신 인라인 클래스를 사용하세요
- vercel.json에서 /docs/*에 대한 재작성은 Mintlify docs 사이트로 프록시합니다. 팀과 확인하지 않으면 이것들을 수정하지 마세요.
- NEXT_PUBLIC_ 접두사가 있는 환경 변수만 클라이언트 쪽에서 사용 가능합니다. 절대 API 시크릿을 이런 식으로 노출하지 마세요.
"하지 마세요" 섹션
이것은 아마도 가장 중요한 섹션입니다. 부정적인 지시사항은 AI 모델에서 매우 효과적입니다.
## 하지 마세요
- 먼저 묻지 않고 새로운 의존성을 설치하지 마세요
- `any` 타입을 사용하지 마세요 — 적절한 타입을 찾거나 생성하세요
- 서버 컴포넌트로 할 수 있는 것들을 위해 새로운 API 라우트를 만들지 마세요
- 마이그레이션 계획을 확인하지 않고 Sanity 스키마 파일을 수정하지 마세요
- 컴포넌트가 정말로 브라우저 API나 이벤트 핸들러가 필요하지 않으면 `"use client"`을 사용하지 마세요
- CSS 파일을 작성하지 마세요 — 모든 것이 Tailwind 유틸리티 클래스입니다
- CMS에서 와야 하는 문자열을 하드코딩하지 마세요
실제 CLAUDE.md 예시
예시: Next.js 마케팅 사이트
이것은 클라이언트 프로젝트에서 사용하는 CLAUDE.md의 축약된 버전입니다. 특히 헤드리스 CMS 백엔드를 사용하여 Next.js 사이트를 구축할 때 유용합니다.
# Acme 마케팅 사이트
## 개요
Acme (acme.com)을 위한 마케팅 웹사이트. Next.js 15로 구축, Tailwind v4로 스타일링, Sanity CMS의 콘텐츠. 목표: 모든 페이지에서 LCP를 2초 미만으로.
## 기술 스택
Next.js 15.1 | TypeScript 5.7 strict | Tailwind v4 | Sanity v3 | Vercel | pnpm
## 아키텍처
App Router with RSC. lib/sanity/queries.ts의 GROQ 쿼리를 통한 서버 컴포넌트의 모든 데이터 가져오기. 클라이언트 컴포넌트는 상호작용하는 요소 (모달, 폼, 캐러셀)만.
페이지: / (홈), /about, /pricing, /blog, /blog/[slug], /contact
## 규칙
- 이름있는 exports만 (page.tsx/layout.tsx 제외)
- 컴포넌트: PascalCase, 파일당 하나
- 클래스 병합에는 cn()
- 모든 폼 검증을 위한 Zod 스키마
- 데이터 가져오기에 useEffect를 사용하지 마세요. 절대로.
## 명령어
pnpm dev | pnpm build | pnpm lint | pnpm test
## 하지 마세요
- 정당화 없이 "use client" 추가
- 묻지 않고 패키지 설치
- 컴포넌트에 대해 default exports 사용
- 마이그레이션을 확인하지 않고 sanity/schema/ 파일 수정
- any 타입 사용
예시: Astro 콘텐츠 사이트
Astro 프로젝트의 경우, CLAUDE.md는 약간 다르게 보입니다. 아키텍처 패러다임이 다르기 때문입니다.
# 기술 블로그 — Astro
## 개요
500개 이상의 아티클이 있는 개발자 블로그. 정적-우선, 기본값으로 JS 없음. 커스텀 컴포넌트가 있는 MDX로 콘텐츠 제공.
## 기술 스택
Astro 5.x | MDX | Tailwind v4 | Cloudflare Pages에 배포 | Content Collections v2
## 아키텍처
src/content/ — Zod-검증 프론트매터가 있는 MDX 아티클
src/components/ — Astro 컴포넌트 (JS 없음) 및 React islands (상호작용)
src/layouts/ — 기본 레이아웃
src/pages/ — 파일 기반 라우팅
## 주요 규칙
- 기본값으로 Astro 컴포넌트 (.astro)를 사용하세요. 상호작용이 필요한 islands에만 React 사용하세요.
- 뷰포트 아래 상호작용 컴포넌트에는 client:visible
- 중요하지 않은 상호작용 컴포넌트에는 client:idle
- 절대 필요한 경우가 아니면 절대 client:load를 사용하지 마세요
- 모든 이미지는 적절한 width/height를 사용하여 Astro의 Image 컴포넌트 사용
- RSS 피드는 콘텐츠 컬렉션에서 자동 생성됩니다 — 수동 피드 로직을 구축하지 마세요
## 하지 마세요
- Astro 컴포넌트가 작동할 때 React 컴포넌트 추가
- client:load 지시문 사용
- 이미지 크기 생략 (CLS 유발)
- 기존 프론트매터를 업데이트하지 않고 콘텐츠 컬렉션 스키마 수정
AI 맥락을 망치는 일반적인 실수
이 시점에서 많은 CLAUDE.md 파일을 검토했습니다. 여기 일관되게 나쁜 결과로 이어지는 패턴들이 있습니다.
| 실수 | 해로운 이유 | 해결 방법 |
|---|---|---|
| 너무 김 (2000+ 단어) | 맥락 윈도우 토큰을 낭비, 주요 정보가 손실됨 | 800단어 미만으로 유지. 깊은 내용은 외부 문서로 링크. |
| 너무 모호함 ("React를 사용") | Claude가 가정으로 간격을 채움 | 구체적으로 하세요: 버전, 패턴, 정확한 도구 |
| 부정적 지시사항 없음 | Claude는 규칙을 깨는 "합리적인" 것들을 합니다 | 항상 "하지 마세요" 섹션 포함 |
| README.md 복사-붙여넣기 | README는 인간용이고, AI 맥락이 아님 | CLAUDE.md를 처음부터 작성하세요. AI 특화 프레이밍으로. |
| 민감한 데이터 포함 | 보안 위험 | 절대 CLAUDE.md에 시크릿을 넣지 마세요. .env.example을 참조하세요. |
| 절대 업데이트 안 함 | 프로젝트가 진화, 파일은 아님 | 매 스프린트 또는 주요 리팩토링 시 검토 |
| 모순되는 지시사항 | "서버 컴포넌트 사용" + useEffect 가져오기 예시 | 한 사람이 파일 소유, 일관성 검토 |
CLAUDE.md와 다른 AI 맥락 파일들
Claude Code가 프로젝트 맥락 파일을 읽는 유일한 AI 도구는 아닙니다. 2025년의 경관은 다음과 같습니다:
| 파일 | 도구 | 자동 읽기 | 범위 |
|---|---|---|---|
| CLAUDE.md | Claude Code | 예, 세션 시작 시 | 프로젝트 전체 |
| .cursorrules | Cursor | 예, 파일 열기 시 | 프로젝트 전체 |
| .github/copilot-instructions.md | GitHub Copilot | 예, Copilot Chat에서 | 저장소 전체 |
| .windsurfrules | Windsurf (Codeium) | 예 | 프로젝트 전체 |
| AGENTS.md | OpenAI Codex CLI | 예 | 프로젝트 전체 |
| .ai/context.md | 커스텀 규칙 | 아니오 (수동 참조) | 다양함 |
좋은 뉴스: 콘텐츠의 대부분은 전송 가능합니다. 견고한 CLAUDE.md를 작성했다면 이를 .cursorrules 또는 copilot-instructions.md로 변환하는 데는 약 5분이 걸립니다. 구조와 정보는 동일합니다 — 파일 이름과 사소한 포맷팅만 다릅니다.
팀이 여러 AI 도구를 사용한다면 (2025년에 많은 팀이 그렇습니다), 단일 소스를 유지 관리하고 도구별 파일을 생성하는 것을 고려하세요. 간단한 빌드 스크립트는 마스터 맥락 파일을 모든 올바른 위치로 복사할 수 있습니다.
대규모 프로젝트를 위한 고급 패턴
중첩 CLAUDE.md 파일
monorepos 또는 큰 코드베이스의 경우, 서브디렉토리에 CLAUDE.md 파일을 배치할 수 있습니다. Claude Code는 작업 중인 디렉토리의 가장 특정 파일을 읽습니다.
project/
├── CLAUDE.md # 글로벌 프로젝트 맥락
├── apps/
│ ├── web/
│ │ └── CLAUDE.md # 웹 앱 특화 맥락
│ └── api/
│ └── CLAUDE.md # API 특화 맥락
├── packages/
│ └── ui/
│ └── CLAUDE.md # 디자인 시스템 맥락
루트 CLAUDE.md는 공유 아키텍처 및 규칙을 다룹니다. 각 중첩 파일은 해당 패키지에 대한 세부 사항을 추가합니다.
/compact를 사용한 동적 맥락
Claude Code의 /compact 명령어는 현재 대화를 요약하고 맥락 공간을 확보합니다. 긴 세션의 경우, 효과가 있는 패턴을 찾았습니다:
- CLAUDE.md가 자동으로 로드된 상태로 시작
- 기능 작업
- 맥락이 무거워질 때
/compact실행 - 계속 — Claude는 CLAUDE.md 맥락 + 압축 요약을 유지
팀 공유 vs 개인 맥락
CLAUDE.md를 버전 관리에 보관합니다 (커밋되어야 함). 하지만 개별 개발자들은 개인 환경설정을 위해 ~/.claude/CLAUDE.md도 사용합니다:
# 개인 환경설정
- 나는 약자보다 상세한 변수명을 선호합니다
- 코드를 작성하기 전에 추론을 보여주세요
- 변경을 제안할 때, 전체 파일 diff를 표시하세요
- 나는 Vim 키바인딩이 있는 VS Code를 사용합니다 (IDE 특화 단축키를 제안하지 마세요)
이 분리는 팀 파일을 깨끗하고 프로젝트 사실에 집중되게 유지하면서 개인들이 경험을 커스터마이징할 수 있게 합니다.
영향 측정하기
CLAUDE.md가 작동하는지 어떻게 알 수 있습니까? 여기 내부적으로 추적하는 메트릭들이 있습니다:
- 첫 시도 정확도: Claude의 첫 응답이 수정이 필요 없을 때의 빈도? 좋은 CLAUDE.md는 이것을 80% 이상으로 올립니다.
- 규칙 위반: Claude가 코딩 표준을 얼마나 자주 깹니까? 0으로 추세를 보여야 합니다.
- 맥락 질문: Claude가 "이게 어떤 프레임워크인가요?" 또는 "App Router를 사용해야 할까요?"를 계속 묻는다면, CLAUDE.md에 정보가 부족합니다.
- 실행 취소 빈도: Claude의 변경을 거부하거나 되돌려야 하는 빈도. 낮을수록 좋습니다.
중간 규모 스타트업의 한 팀은 CLAUDE.md에 한 시간을 투자한 후 AI 보조 작업의 평균 시간을 12분에서 4분으로 줄였다고 보고했습니다. 이것은 하나의 파일에서 3배 개선입니다.
자주 묻는 질문
CLAUDE.md란 무엇이고 어디에 있나요? CLAUDE.md는 저장소 루트에 놓는 마크다운 파일입니다. Claude Code는 매 세션의 시작에 자동으로 읽습니다. AI 코딩 어시스턴트를 위해 특별히 작성된 온보딩 문서로 생각하세요.
CLAUDE.md 파일은 얼마나 길어야 할까요? 300-800단어를 목표로 하세요. 더 짧은 파일은 중요한 맥락을 놓치지만, 1,000단어를 넘으면 맥락 윈도우를 먹기 시작합니다 — 실제 코드 추론에 더 잘 사용될 수 있는 공간입니다. 간결하고 구체적이세요. 모든 문장이 가치를 더해야 합니다. 더 깊이 필요하면 외부 문서로 링크하세요.
CLAUDE.md를 버전 관리에 커밋해야 할까요?
절대로. CLAUDE.md는 다른 프로젝트 문서처럼 취급해야 합니다 — 버전 관리, 검토, 최신 상태로 유지. 개인 환경설정은 ~/.claude/CLAUDE.md로 가세요. 이것은 각 개발자 머신에 로컬로 유지됩니다.
CLAUDE.md는 .cursorrules과 어떻게 다른가요? 콘텐츠는 거의 동일합니다 — 둘 다 AI 코딩 도구에 프로젝트 맥락을 제공합니다. 차이는 어떤 도구가 읽는가입니다. CLAUDE.md는 Claude Code (Anthropic의 CLI 도구)용이고, .cursorrules는 Cursor IDE용입니다. 두 도구를 사용한다면, 하나의 소스를 유지 관리하고 도구별 포맷팅 조정으로 두 파일에 복사하세요.
CLAUDE.md의 가장 중요한 섹션은 무엇인가요?
"하지 마세요" 섹션입니다. 부정적 지시사항은 AI 모델에서 불균형하게 효과적입니다. Claude에게 무엇을 피할지 알려주기 — any 타입을 사용하지 마세요, 불필요하게 "use client"를 추가하지 마세요, 묻지 않고 새 패키지를 설치하지 마세요 — 가장 흔하고 답답한 실수를 방지합니다. 좋은 금지 목록은 긍정적 지시사항의 페이지보다 더 많은 시간을 절약합니다.
CLAUDE.md를 비코드 프로젝트에 사용할 수 있을까요? 예. CLAUDE.md는 Claude Code와 상호작용하는 모든 프로젝트에 작동합니다. 나는 문서 저장소, infrastructure-as-code 프로젝트, 심지어 데이터 분석 파이프라인용으로도 효과적인 것들을 봤습니다. 원칙은 동일합니다: Claude가 프로젝트에 대해 좋은 결정을 내릴 수 있도록 맥락을 제공하세요.
CLAUDE.md를 얼마나 자주 업데이트해야 할까요? 모든 주요 리팩토링 시, 최소 스프린트마다 한 번씩 검토하세요. 프레임워크 버전을 업그레이드하거나, 주요 의존성을 변경하거나, 새로운 규칙을 채택하면, 파일을 즉시 업데이트하세요. 구식 맥락은 없는 것보다 나쁩니다. AI를 적극적으로 오도하기 때문입니다. 일부 팀은 인프라 변경사항에 대해 PR 체크리스트에 CLAUDE.md 검토를 추가합니다.
CLAUDE.md는 웹에서 Claude (claude.ai)와 작동할까요? 아니요. CLAUDE.md는 구체적으로 Claude Code (CLI 기반 코딩 도구)에서 읽습니다. 웹 인터페이스나 API를 통해 Claude를 사용한다면, 맥락을 수동으로 붙여넣거나 Projects 기능을 사용하여 지식 파일로 첨부해야 합니다. Claude Code의 자동 로딩이 파일을 매우 강력하게 만드는 것입니다 — 마찰 없음, 매 세션.