이 기사의 요점

• CLAUDE.md는 Claude Code가 자동으로 읽어들이는 컨텍스트 (Context) 파일로, 프로젝트 고유의 규칙을 AI에게 지속적으로 전달하는 메커니즘입니다.
• 개인 스크립트부터 엔터프라이즈 (Enterprise)까지, 규모에 따라 최적의 구성은 크게 달라집니다.
• 글로벌 (~/.claude/CLAUDE.md)과 로컬 (프로젝트 루트의 CLAUDE.md)을 조합함으로써 중복 없이 관리할 수 있습니다.

CLAUDE.md 작성 방법을 검색하는 엔지니어 대부분이 직면하는 문제는 "어디까지 써야 하는가"입니다. 팀으로부터 "일단 코딩 규약 (Coding Convention)을 작성해 두세요"라는 말을 듣고 파일을 만들었지만, 수백 줄로 불어나 아무도 읽지 않게 된── 그런 경험을 한 분들이 적지 않을 것입니다.

이 기사에서는 개인 도구부터 엔터프라이즈 (Enterprise)까지, 프로젝트 규모에 따른 7가지 설계 패턴을 구체적인 템플릿과 함께 소개합니다.

CLAUDE.md는 Claude Code가 자동으로 컨텍스트 (Context)로서 읽어들이는 Markdown 파일입니다. 프로젝트 루트 또는 .claude/ 디렉토리에 배치하면, AI 세션을 시작할 때마다 내용이 적용됩니다.

배치 장소의 우선순위는 다음과 같습니다.

여러 파일이 존재하는 경우 모두 병합(Merge)되어 읽힙니다. 또한 @path/to/file 표기법으로 다른 파일을 참조하여 임포트 (Import)할 수 있으므로, 대규모 프로젝트에서는 분할 관리가 유효합니다 (Claude Code 문서 참조).

먼저 선택의 기준을 정리합니다.

검증용 스크립트나 작은 CLI 도구에서는 CLAUDE.md가 무거우면 역효과입니다. 필요 최소한으로 압축합니다.

# Project
개인용 데이터 변환 CLI 도구.
## Stack
...

포인트: 스택 (Stack)과 "해서는 안 되는 일"만 작성한다. 코딩 규약 (Coding Convention)은 글로벌 CLAUDE.md에 맡긴다.

공개 리포지토리 (Repository)에서는 AI에게 컨트리뷰션 가이드 (Contribution Guide)나 README의 문체를 이해시키는 것이 중요합니다.

# my-oss-lib
## Overview
TypeScript 제작 경량 검증 라이브러리.
...

포인트: 문서의 언어 규칙을 여기에 적어두면, AI가 잘못된 언어로 문서를 생성하는 실수를 방지할 수 있습니다.

팀이 늘어나면 "암묵지"가 AI에게 전달되지 않습니다. 결정된 설계 방침을 여기에 기록해 두는 운용이 효과적입니다.

# backend-api
## Architecture
- Clean Architecture. usecase/domain/infra 3계층
...

실제로 이 패턴으로 운용해 보며 느낀 점인데, "왜 그 규칙이 있는지"를 한마디 덧붙이면 AI가 예외 케이스를 판단하는 정밀도가 올라갑니다. 단순한 규칙 나열보다 배경을 쓰는 편이 더 효과적입니다.

여러 팀이 하나의 리포지토리 (Repository)를 다루는 경우에는 섹션을 명확히 구분하여, 자신의 팀과 관계된 것만 읽으면 되는 구성으로 만듭니다.

# monolith-app
## Teams
- Platform: infra/, db/
...

.claude/rules/ 디렉토리 아래에 분할하여 @ 임포트 (Import)로 조립하는 것이 이 규모의 베스트 프랙티스 (Best Practice)입니다. 파일을 나누어 두면 팀별로 독립적으로 규칙을 업데이트할 수 있습니다.

모노레포 (Monorepo)에서는 부모 CLAUDE.md는 그룹 코드적인 역할에 머물게 하고, 실질적인 규칙은 패키지 측의 CLAUDE.md에 맡깁니다.

/CLAUDE.md ← 리포지토리 (Repository) 전체 방침 (30행 정도)
/apps/web/CLAUDE.md ← Next.js 고유 규칙
/apps/api/CLAUDE.md ← Hono/Cloudflare Workers 고유 규칙
...

부모의 CLAUDE.md에 쓰는 내용:

monorepo

Structure

• pnpm workspaces
  ...

리포지토리가 나누어져 있는 경우, 공통 규칙의 복사본이 급증하기 쉽습니다. 이를 방지하려면 '사내 템플릿 리포지토리(Internal Template Repository)'에 마스터 CLAUDE.md를 두고, 각 서비스의 설정 스크립트(Setup Script)를 통해 배포하는 방법이 유효합니다.

# 각 리포지토리의 초기화 스크립트에서 실행
curl -s https://raw.githubusercontent.com/your-org/templates/main/CLAUDE.md \
> .claude/base.md

각 서비스의 CLAUDE.md:

# payment-service
@.claude/base.md
## Service-specific
...

포인트: 공통 규칙과의 차이점만 작성합니다. 베이스 파일의 내용을 각 리포지토리에 중복해서 작성하지 마세요.

금융·의료·관공서용 시스템에서는 AI가 절대로 넘어서는 안 될 금지 사항을 서두에 집약하는 구성이 안전합니다.

# enterprise-system
## !! BLOCKING REQUIREMENTS !!
이하는 절대로 실행하지 마십시오:
...

서두의 !! BLOCKING REQUIREMENTS !! 섹션은 AI가 어떤 작업 지시를 받더라도 가장 먼저 컨텍스트(Context)로 읽기 때문에, 금지 사항을 확실하게 인식시키는 효과가 있습니다.

~/.claude/CLAUDE.md (글로벌)와 프로젝트의 CLAUDE.md를 구분하여 사용하는 기준은 다음과 같습니다.

CLAUDE.md가 너무 길어져서 관리가 어렵습니다. 어떻게 해야 하나요?

@ 임포트(Import) 구문을 사용하여 파일을 분할하는 것이 유효합니다. 주제별로 .claude/rules/testing.md, .claude/rules/security.md와 같이 나누어 메인 CLAUDE.md에서 임포트하면, 변경 사항이 국소화되어 리뷰하기 쉬워집니다. 또한 행수보다는 'AI가 혼란스러울 때 참조해야 할 정보'에 집중하여 작성하는 것이 중요하며, 코드에서 읽을 수 있는 정보(파일 구성, 의존 관계)는 작성하지 않는 것이 기술량을 줄이는 방법입니다.

팀원들이 CLAUDE.md를 업데이트하지 않습니다. 어떻게 운영해야 할까요?

'결정이 내려지면 즉시 작성한다'는 습관을 팀에 정착시키는 것이 본질적인 해결책이지만, 그것이 어렵다면 PR(Pull Request) 템플릿에 'CLAUDE.md 업데이트가 필요한가?'라는 체크박스를 추가하는 방법이 현실적입니다. 아키텍처 결정 기록(ADR, Architecture Decision Record)을 CLAUDE.md에 작성하는 방식으로 운영하면, 문서와 AI 컨텍스트를 일원화하여 관리할 수 있습니다.

CLAUDE.md에 작성한 내용은 Claude Code 이외의 AI 도구에서도 사용할 수 있나요?

현재로서는 CLAUDE.md는 Claude Code 고유의 메커니즘입니다. 다만 Markdown 형식으로 작성되어 있기 때문에, GitHub Copilot의 .github/copilot-instructions.md나 Cursor의 .cursorrules에 내용을 유용하는 것은 가능합니다. 여러 도구를 사용하는 팀은 마스터가 되는 docs/ai-context.md를 마련하여 각 도구용 파일로 복사하는 운영 방식을 검토할 수 있습니다 (GitHub Copilot 커스텀 인스트럭션 참조).