CLAUDE.md 작성법 — AI 코딩 200% 끌어올리는 메모리 파일

 

AI에게 코딩 시킬 때마다 "우리 프로젝트는 npm 말고 bun 써", "들여쓰기는 2칸이야" 같은 설명을 매번 반복하고 계신가요? 이걸 한 번에 끝내는 게 CLAUDE.md입니다. AI 코딩의 생산성을 가장 크게 끌어올리는 파일이죠.

📌 이 글에서 얻어갈 것

✓ CLAUDE.md가 뭐고 왜 강력한가
✓ 무엇을 담아야 하는가 (체크리스트)
✓ 잘 쓰는 법 + 흔한 실수(비대해진 파일의 함정)
✓ 모든 AI 도구가 읽는 AGENTS.md 표준

CLAUDE.md가 뭐야?

CLAUDE.md는 저장소(repo)에 두는 특별한 설정 파일로, 매 세션이 시작될 때 AI에게 자동으로 제공되는 프로젝트 컨텍스트입니다. 한 번 써두면 AI가 우리 프로젝트의 규칙·명령·구조를 "이미 아는 상태"로 일을 시작합니다. 매번 설명할 필요가 사라지죠.

"AI에게 주는 프로젝트 사용설명서" 📋
사람 신입에게 온보딩 문서를 주듯, AI에게 CLAUDE.md를 준다

무엇을 담아야 하나

검증된 권장 항목입니다. 이것만 채워도 효과가 큽니다.

⚙️ 빌드·테스트·실행 명령 (예: bun run test, bun run dev)

🎨 코드 스타일 규칙 (예: 2칸 들여쓰기, 네이밍)

🗂️ 프로젝트 구조 (핵심 디렉토리·아키텍처)

🔁 워크플로 관습 (PR 컨벤션, 반복 규칙)

🔒 보안 고려사항 · 개발 환경 설정

✅ 검증 루프를 꼭 넣으세요

"npm test로 검증해라" 같은 테스트 방법을 적어두면, AI가 코드 작동을 추측하지 않고 실제로 돌려봅니다. 품질이 눈에 띄게 올라가는 핵심 항목이에요.

잘 쓰는 법

1

/init 로 초안 자동 생성
Claude Code의 /init 명령이 코드베이스를 분석해 CLAUDE.md 초안을 만들어줍니다. 단, 초안일 뿐 — 반드시 검수·축약하세요.

2

구체적이고 실행 가능하게
"코드를 깔끔하게" (X) → "함수는 20줄 이내, 한 가지 일만" (O). 모호한 지시는 AI에게 쓸모없습니다.

3

중요한 건 IMPORTANT로 강조
꼭 지켜야 할 규칙엔 "IMPORTANT"나 "YOU MUST"를 붙이면 준수율이 올라갑니다.

4

git에 커밋해 팀 자산으로
CLAUDE.md는 개인 파일이 아니라 팀이 함께 키우는 자산입니다. git에 올리고 PR로 리뷰하세요. 개인용 규칙은 CLAUDE.local.md로 분리.

5

린터가 할 일은 린터에게
포매터·린터·TypeScript가 자동으로 강제하는 규칙은 CLAUDE.md에서 빼세요. 도구에 맡기고 파일은 가볍게.

⚠️ 흔한 실수 — "길수록 좋다"는 착각

가장 큰 함정입니다. CLAUDE.md는 길다고 좋은 게 아닙니다 — 오히려 해롭습니다.

💸 모든 토큰이 "작업 전에" 소비된다

CLAUDE.md는 세션 시작 시 통째로 로드되므로, 파일의 모든 글자가 실제 작업 전에 토큰으로 소비됩니다. 파일이 클수록 그만큼 컨텍스트 예산을 미리 까먹는 거죠.

2,000줄짜리 비대한 CLAUDE.md는 이른바 "멍청이 구역(dumb zone)"을 만듭니다 — 노이즈가 너무 많아 AI가 정작 중요한 지시를 무시하게 되죠. 권장은 200~300줄 이내(어떤 팀은 60줄로도 운영). 긴 내용은 별도 파일로 빼고 "그 파일을 봐라"라고 가리키세요.

🤖 자동 생성을 맹신하지 마세요

흥미롭게도 사람이 직접 큐레이션한 컨텍스트가 가장 높은 성공률을 냅니다. AI가 자동 생성한 컨텍스트는 오히려 성공률을 떨어뜨릴 수 있어요. /init 결과를 그대로 두지 말고 직접 다듬으세요.

한 발 더 — AGENTS.md 표준

요즘 뜨는 게 AGENTS.md입니다. OpenAI·Google·Cursor 등 주요 회사들이 2025년 7월에 함께 만든 오픈 표준으로, "AI 에이전트를 위한 README" 같은 거예요.

강점은 호환성입니다 — Codex CLI, Cursor, Copilot, Gemini CLI, Aider, Zed 등 다양한 도구가 AGENTS.md를 읽습니다. 도구마다 다른 설정 파일을 만들 필요 없이 하나로 통일할 수 있죠. (Claude Code에서는 CLAUDE.md에서 @AGENTS.md 구문으로 import해 단일 소스로 관리하는 방법도 있습니다.)

자주 묻는 질문 (FAQ)

Q. 어디에 두나요?

보통 프로젝트 루트에 CLAUDE.md로 둡니다. 하위 디렉토리에 별도로 둬서 그 폴더 전용 규칙을 줄 수도 있어요.

Q. 처음엔 뭘 적죠?

/init로 초안을 만든 뒤, 빌드·테스트 명령과 "AI가 자꾸 틀리는 것"부터 규칙으로 추가하세요. 완벽하게 시작할 필요 없이 쓰면서 키우면 됩니다.

Q. CLAUDE.md vs AGENTS.md, 뭘 쓰죠?

Claude Code만 쓴다면 CLAUDE.md, 여러 AI 도구를 섞어 쓴다면 호환되는 AGENTS.md가 유리합니다. CLAUDE.md에서 AGENTS.md를 import해 둘을 합치는 방법도 있어요.

마치며

CLAUDE.md는 "한 번 쓰고 계속 이득 보는" 파일입니다. 핵심은 세 가지 — 꼭 필요한 것만 구체적으로, 짧게(200줄 내외), 팀과 함께 키우기. AI에게 매번 같은 설명을 반복하는 시간을 아껴주는, 가장 가성비 좋은 투자예요.

다음 글에서는 최신 AI 모델 출시 소식을 빠르게 전해드리겠습니다. 여러분의 CLAUDE.md엔 어떤 규칙이 들어있나요? 댓글로 공유해주세요 🙌

---

※ 본 글은 2026년 6월 기준 출처를 교차검증해 작성했습니다. 주요 출처: Anthropic 공식 Claude Code 베스트프랙티스, AGENTS.md 오픈 표준(agents.md), 다수 실무 가이드. 도구 사양은 수시로 바뀌니 공식 문서 재확인을 권합니다.