CLAUDE.md는 새 직원에게 건네는 업무 인수인계 노트 같은 것 — Claude Code가 작업을 시작할 때 가장 먼저 읽는 규칙·지침 문서로, 프로젝트 설명과 지켜야 할 약속을 적어 둬요.
CLAUDE.md는 새로 온 직원에게 첫날 건네는 인수인계 노트와 같아요. '우리 회사는 이런 일을 하고, 이 폴더에는 이게 있고, 이건 절대 하지 마세요'가 적혀 있으면 직원이 매번 묻지 않아도 일을 이어 갈 수 있죠. Claude Code도 대화를 새로 시작할 때마다 기억이 비어 있어서, 이 파일을 먼저 읽고 프로젝트의 규칙과 맥락을 파악해요.
강의에서는 두 가지 장면에서 써요. 첫째, 프로젝트를 깃허브 저장소에 올릴 때 CLAUDE.md(클로드용)와 agent.md(코덱스·커서 같은 다른 도구용)를 함께 만들어 두면 어떤 환경에서 열어도 작업을 이어 갈 수 있어요. 둘째, 모든 프로젝트에 공통으로 적용되는 전역 지침이에요. 전역 지침이 내 PC에만 있으면 VPS의 AI는 다른 규칙을 보게 되므로, 저장소의 공유 폴더로 옮겨 PC와 VPS가 같은 지침과 메모리를 보게 만들어요.
무엇을 적어야 하냐는 질문에는 '매번 반복해서 말하게 되는 것'을 적으라고 답할 수 있어요. 프로젝트 목적, 폴더 구조, 쓰는 도구, 답변 언어, 하면 안 되는 일, 검증 순서 같은 것이요. 반대로 너무 길게 쓰면 AI가 중요한 규칙을 놓치고 컨텍스트도 많이 차지하니 핵심만 짧게 유지하는 게 좋아요. 대화 중 한 번 말한 지시는 압축되면 사라질 수 있지만, CLAUDE.md에 적은 규칙은 다음 대화에서도 계속 적용된다는 점이 가장 큰 차이예요.
AI와 함께 나만의 사이트·서비스를 만드는 법을 강의에서 배워보세요.