AI 코딩 어시스턴트가 처음으로 저장소를 연다. 파일 구조, 종속성, 그리고 아마도 README를 스캔한다. 그리고 나서 기존 레이아웃 시스템을 깨뜨리는 라우터 설정을 제안하고, 3개 스프린트 전에 사용 중단한 패키지를 import하고, 지난해 팀이 버린 스타일로 테스트를 작성한다. 어시스턴트가 멍청한 게 아니라 눈이 먼 것이다. Claude Code, Cursor, Copilot, Cody — 모든 AI 쌍 프로그래머가 같은 벽에 부딪힌다: 커밋 히스토리만으로는 팀의 컨텍스트를 읽을 수 없다. 프로젝트 루트에 하나의 CLAUDE.md 파일을 두는 것으로 모든 것이 바뀐다. 이것은 팀의 규칙과 싸우는 어시스턴트와 수 개월 동안 함께 배송한 시니어 개발자처럼 그 규칙을 확장하는 어시스턴트의 차이다. 하지만 대부분의 팀이 작성하는 CLAUDE.md 파일은 AI가 실제로 사용할 수 없다.

Claude Code에 프롬프트를 던지고 있는데 일반적이거나 잘못된 또는 답답한 결과를 받고 있다면 이 가이드는 당신을 위한 것이다. CLAUDE.md를 정확히 어떻게 구성할지, 무엇을 포함할지, 무엇을 빼야 할지, 그리고 Social Animal에서 배송한 프로덕션 프로젝트의 실제 예제를 공유할 것이다.

목차

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는 컨텍스트를 로드하기 위한 특정 계층 구조를 가지고 있다. 이것을 이해하는 것이 중요한 이유는 프로젝트 메모리를 어떻게 구성하는지에 영향을 미치기 때문이다.

컨텍스트 로딩 순서

  1. ~/.claude/CLAUDE.md — 전역 설정 (모든 프로젝트에 적용됨)
  2. ./CLAUDE.md — 저장소 루트의 프로젝트 수준 파일
  3. ./subdirectory/CLAUDE.md — 디렉토리별 재정의
  4. .claude/settings.json — 프로젝트별 도구 권한 및 설정
  5. 세션 컨텍스트 — 현재 대화에서 Claude에게 말하는 내용

프로젝트 수준 CLAUDE.md가 대부분의 시간을 들일 곳이다. 전역 파일은 개인 설정에 좋다("함수형 컴포넌트를 선호한다" 또는 "항상 TypeScript strict 모드를 사용한다"), 하지만 실제 가치는 프로젝트별 컨텍스트에 있다.

중요한 것은 다음과 같다: Claude Code는 매 세션의 시작에 CLAUDE.md를 읽지만, 제한된 컨텍스트 윈도우 공간도 가지고 있다. CLAUDE.md가 5,000 단어의 장황한 문서라면, 실제 코드 추론에 사용될 수 있는 토큰을 낭비하는 것이다. 간결하게. 구체적으로. 모든 줄이 제 몫을 해야 한다.

훌륭한 CLAUDE.md 파일의 구조

Next.js 앱, Astro 사이트, 헤드리스 CMS 통합, API 서비스를 포함한 수십 개의 프로젝트에서 CLAUDE.md 파일을 작성하고 개선한 후, 작동하는 일관된 구조에 도달했다.

이상적인 구조

# 프로젝트 이름

## 개요
이 프로젝트가 무엇을 하고 누가 사용하는지 설명하는 한 단락.

## 기술 스택
정확한 버전과 프레임워크.

## 아키텍처
부분들이 어떻게 함께 맞는지.

## 핵심 규칙
코딩 표준, 명명 패턴, 파일 조직 규칙.

## 일반적인 명령
빌드, 테스트, 배포, 개발 명령.

## 중요한 컨텍스트
코드에서 명확하지 않은 것.

## 알려진 문제 / 함정
AI가 피해야 할 함정들.

## 하지 마
AI가 절대 해서는 안 되는 명시적인 것들.

각 섹션을 자세히 살펴보자.

섹션별 상세 분석

개요

최대 2-3 문장으로 유지하자. Claude는 제품 로드맵이 필요하지 않다 — 컨텍스트에 맞는 결정을 내릴 수 있도록 도메인을 이해할 필요가 있다.

## 개요
Acme Corp(공급망 관리를 위한 B2B SaaS 플랫폼)의 마케팅 사이트이다. 동적 API 라우트를 가진 정적으로 생성된 사이트로 양식 처리 및 리드 캡처를 위해 사용한다. 콘텐츠는 마케팅 팀에 의해 Sanity CMS를 통해 관리된다.

기술 스택

정확히 하자. "React"라고만 말하지 말고, 버전, 프레임워크, 렌더링 전략을 지정하자. 이는 Claude가 React 18에서는 작동하지만 React 19에서는 깨지는 패턴을 제안하거나, Pages Router를 사용 중일 때 App 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로 명명되며, 파일당 하나의 컴포넌트
- 명명된 내보내기를 사용하고, 기본 내보내기는 하지 않음 (페이지/레이아웃 제외)
- 모든 데이터 페칭은 서버 컴포넌트에서 발생 — useEffect로 데이터 페칭을 절대 하지 말 것
- API 응답 타입은 lib/types/에 존재하고 Sanity 스키마에서 자동 생성됨
- 조건부 클래스 병합을 위해 `cn()` 유틸리티(lib/utils.ts) 사용, 템플릿 리터럴 아님
- 에러 경계는 각 주요 페이지 섹션을 감싼다, 전체 페이지 아님
- 모든 양식 처리는 react-hook-form + zod 검증 스키마 사용
- 커밋 메시지는 Conventional Commits를 따름 (feat:, fix:, chore:)

일반적인 명령

이것은 기본적으로 보이지만, Claude Code는 실제로 이 명령들을 실행한다. 올바른 명령을 모르면 추측할 것이고, 자주 틀릴 것이다.

## 일반적인 명령
- `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 웹훅이 on-demand revalidation을 처리한다 — 수동 revalidation 로직을 추가하지 말 것.
- 이미지 최적화는 Sanity의 CDN (cdn.sanity.io)을 통해 이루어진다, CMS 콘텐츠의 next/image가 아님.
- 인증은 Clerk에 의해 처리된다 — 커스텀 인증 흐름을 구축하지 말 것.
- /api/leads 엔드포인트는 Upstash Redis를 통한 rate limiting이 있다. rate limit 미들웨어를 제거하지 말 것.

알려진 함정

모든 프로젝트에는 이상한 것이 있다. Claude가 그것에 걸려 넘어지지 않도록 여기에 두자.

## 알려진 함정
- Sanity의 portable text 렌더러는 v3.2의 중첩 리스트에 버그가 있다. components/portable-text/list-fix.tsx의 커스텀 직렬화기를 사용한다
- Tailwind v4는 모듈 CSS 파일에서 `@apply` 지시문을 지원하지 않는다 — 인라인 클래스를 대신 사용하자
- vercel.json의 /docs/* 리다이렉트가 Mintlify 문서 사이트로 프록시된다. 팀에 확인 없이 이것들을 수정하지 말 것.
- 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의 콘텐츠로 구축됨. 목표: 모든 페이지에서 2초 미만의 LCP.

## 기술 스택
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

## 규칙
- 명명된 내보내기만 (page.tsx/layout.tsx 제외)
- 컴포넌트: PascalCase, 파일당 하나
- 클래스 병합을 위해 cn() 사용
- 모든 양식 검증에 Zod 스키마
- 데이터 페칭을 위해 useEffect를 사용하지 말 것. 절대.

## 명령
pnpm dev | pnpm build | pnpm lint | pnpm test

## 하지 마
- 정당화 없이 "use client"를 추가하지 말 것
- 물어보지 말고 패키지를 설치하지 말 것
- 컴포넌트에 기본 내보내기를 사용하지 말 것
- sanity/schema/ 파일을 수정하지 말 것. 마이그레이션을 먼저 확인하자
- any 타입을 사용하지 말 것

예제: Astro 콘텐츠 사이트

Astro 프로젝트의 경우, CLAUDE.md가 약간 다르게 보인다. 아키텍처 패러다임이 다르기 때문이다.

# 기술 블로그 — Astro

## 개요
500개 이상의 기사가 있는 개발자 블로그. 정적 우선, 기본값으로 0 JS. MDX for content with custom components.

## 기술 스택
Astro 5.x | MDX | Tailwind v4 | Cloudflare Pages에 배포됨 | Content Collections v2

## 아키텍처
src/content/ — Zod로 검증된 프론트매터를 가진 MDX 기사
src/components/ — Astro 컴포넌트 (0 JS) 및 React 아일랜드 (상호작용)
src/layouts/ — 베이스 레이아웃
src/pages/ — 파일 기반 라우팅

## 핵심 규칙
- Astro 컴포넌트(.astro)가 작동하면 React를 사용하지 말 것. 상호작용이 필요한 경우에만 사용.
- client:visible은 below-fold 상호작용 컴포넌트를 위해
- 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 컨텍스트를 위한 것이 아님 AI 중심 프레이밍으로 처음부터 작성하자
민감한 데이터 포함 API 키, CLAUDE.md의 시크릿 CLAUDE.md에 시크릿을 절대 두지 말 것. 대신 .env.example 참조
절대 업데이트하지 않음 프로젝트가 진화하지만 컨텍스트 파일은 그대로 매 스프린트 또는 주요 리팩터링마다 검토
모순된 지침 "서버 컴포넌트를 사용하라" + useEffect 페칭의 예제 한 사람이 파일을 관리하고 일관성을 검토

CLAUDE.md vs 다른 AI 컨텍스트 파일

Claude Code가 프로젝트 컨텍스트 파일을 읽는 유일한 AI 도구는 아니다. 2026년의 환경은 다음과 같다:

파일 도구 자동 읽기 범위
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 도구를 사용한다면 (그리고 2026년에는 많은 팀이 그렇다), 진실의 단일 소스를 유지하고 도구별 파일을 생성하는 것을 고려하자. 간단한 빌드 스크립트가 마스터 컨텍스트 파일을 모든 올바른 위치에 복사할 수 있다.

대규모 프로젝트를 위한 고급 패턴

중첩된 CLAUDE.md 파일

Monorepo나 대규모 코드베이스의 경우, 하위 디렉토리에 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 명령은 현재 대화를 요약하고 컨텍스트 공간을 확보한다. 긴 세션의 경우, 작동하는 패턴을 찾았다:

  1. CLAUDE.md를 자동으로 로드하여 시작
  2. 기능에서 작업
  3. 컨텍스트가 무거워질 때 /compact 실행
  4. 계속 — Claude는 CLAUDE.md 컨텍스트와 압축된 요약을 유지

팀 공유 vs 개인 컨텍스트

CLAUDE.md를 버전 제어에 유지한다 (커밋해야 함). 하지만 개인 개발자는 개인 선호도를 위해 ~/.claude/CLAUDE.md도 사용한다:

# 개인 선호도
- 약어보다 장황한 변수명을 선호함
- 코드를 작성하기 전에 추론을 보여줌
- 변경을 제안할 때, 전체 파일 diff를 보여줌
- VS Code with Vim keybindings 사용 (IDE별 바로가기 제안하지 말 것)

이 분리는 팀 파일을 깔끔하고 프로젝트 사실에 초점을 맞추면서 개인이 경험을 커스터마이즈할 수 있도록 한다.

영향 측정하기

CLAUDE.md가 작동하는지 어떻게 알 수 있을까? 내부적으로 추적하는 메트릭은 다음과 같다:

  • 첫 시도 정확도: Claude의 첫 응답이 0개의 수정이 필요한 경우가 얼마나 자주일까? 좋은 CLAUDE.md는 이것을 80% 이상으로 올린다.
  • 규칙 위반: Claude가 코딩 표준을 깨뜨리는 횟수. 0을 향해 트렌드해야 한다.
  • 컨텍스트 질문: Claude가 "이것이 무엇 프레임워크일까?" 또는 "App Router를 사용해야 할까?"라고 자주 묻는다면, CLAUDE.md에 정보가 부족하다.
  • 실행 취소 빈도: Claude의 변경을 거부하거나 되돌려야 하는 빈도. 낮을수록 좋다.

중규모 스타트업의 한 팀은 CLAUDE.md에 한 시간을 투자한 후 AI 지원 작업의 평균 시간을 12분에서 4분으로 줄였다고 보고했다. 이것은 하나의 파일에서 나오는 3배 개선다.

프로젝트를 헤드리스 CMS 개발 서비스를 통해 구축한다면, 맞춤형 CLAUDE.md를 모든 프로젝트 인수에 포함한다. 그 정도로 지속적인 개발 속도에 중요하다.

FAQ

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는 specifically Claude Code, CLI 기반 코딩 도구에서 읽힌다. 웹 인터페이스나 API를 통해 Claude를 사용한다면, 컨텍스트를 수동으로 붙여넣거나 Projects 기능을 사용하여 지식 파일로 첨부해야 한다. Claude Code의 자동 로딩이 파일을 강력하게 만드는 것이다 — 0 마찰, 매 세션.