Claude Code에 같은 프로젝트 규칙을 매번 다시 설명하고 있다면 CLAUDE.md에 적어 두세요. Markdown 형식의 일반 텍스트 파일입니다. Claude Code는 세션을 시작할 때 이 파일을 읽고, 다른 컨텍스트와 함께 여러분이 정한 약속도 전달받습니다.
처음에는 검증된 몇 줄이면 충분합니다. 어디서 작업할지, 결과를 어떻게 확인할지, 변경할 때 무엇을 유지해야 할지 적어 두세요.
CLAUDE.md 예시
카드가 있는 간단한 페이지를 예로 들어 보겠습니다. 마크업, 스타일, JavaScript가 하나의 index.html에 있고, 브라우저에서 바로 열 수 있습니다. 이런 프로젝트의 지침 파일은 다음과 같을 수 있습니다.
# CLAUDE.md
## 프로젝트
- 페이지, 스타일, JavaScript는 `index.html`에 있다.
## 확인
- 브라우저에서 `index.html`을 연다.
- 넓은 화면과 좁은 화면에서 페이지를 확인한다.
## 규칙
- 현재 색상과 카드 스타일을 유지한다.
- 확인 없이 완성된 블록을 삭제하지 않는다.
- 작업 후 변경 사항과 확인 내용을 나열한다.여기에는 프로젝트 구성, 결과 확인, 서로 합의한 규칙이라는 세 가지 묶음이 있습니다. 이제 "카드를 하나 더 추가해 주세요"라고 요청할 때마다 모든 규칙을 다시 나열할 필요가 없습니다. 다만 페이지는 여러분이 직접 확인해도 됩니다. 지침 파일이 있다고 해서 브라우저 도구가 없는 에이전트가 브라우저에 접근할 수 있게 되지는 않습니다.
이 예시는 파일 하나로 된 프로젝트용일 뿐, 만능 템플릿은 아닙니다. 여러분의 프로젝트에는 별도 폴더나 실행 명령이 있을 수 있습니다. 바로 그런 폴더와 명령을 적어 두세요. 테스트가 없다면 완성도를 높이려고 없는 명령을 만들어 넣지 마세요.
무엇을 기록하면 좋을까요?
가장 중요한 기준은 이것입니다. 다음 작업에서도 이 기록이 필요할까요? 검증된 명령, 중요한 경로, 코드만으로 에이전트가 확실히 알아내기 어려운 약속이 유용합니다. 특히 여러분이 이미 여러 번 반복해서 설명했던 내용이 그렇습니다.
에이전트가 어떤 행동을 해야 하는지 명확하게 규칙을 작성하세요.
- "모두 확인해" → "카드를 변경한 뒤 페이지를 넓은 화면과 좁은 화면에서 확인해";
- "중요한 건 건드리지 마" → "이미 완성된 블록은 내용이 합의된 것이니 확인 없이 삭제하지 마".
첫 번째 예시는 확인할 항목을, 두 번째는 제한 범위와 그 이유를 알려 줍니다. "꼼꼼하게 작업해" 같은 바람을 길게 늘어놓는 것보다 훨씬 유용합니다.
README.md는 사람에게 프로젝트가 무엇인지, 어떻게 시작하는지 설명합니다. CLAUDE.md에는 에이전트를 위한 지침을 모읍니다. README 전체를 반복해서 적을 필요는 없습니다. "카드 너비 때문에 캡션이 밀리는 것 같아" 같은 추측은 현재 작업의 메모, 예를 들면 PROJECT_NOTE.md에 남겨 두세요. 원하는 이름으로 만든 일반 파일이며, 작업을 이어갈 때 에이전트에게 읽어 달라고 하면 됩니다.
추측을 확인된 사실처럼 기록하지 말고, 비밀번호나 접근 키도 여기에 보관하지 마세요. 공용 CLAUDE.md는 보통 Git에 추가해 동료들도 프로젝트와 함께 같은 지침을 받도록 합니다.
파일을 만들고 확인하는 방법
이미 알고 있는 규칙부터 시작하세요. 오류가 잔뜩 쌓일 때까지 기다리거나 가능한 모든 상황을 미리 설명할 필요는 없습니다.
- 프로젝트에 이미
CLAUDE.md가 있는지 확인하세요. 있다면 읽고 필요한 내용을 덧붙이세요. 새 파일은 프로젝트 루트에 두면 됩니다..claude/CLAUDE.md경로도 지원하지만 두 위치에 복사본을 만들 필요는 없습니다. - 몇 줄을 직접 작성하거나 프로젝트 폴더에서 Claude Code를 열고
/init을 입력하세요. 이 명령은 프로젝트를 살펴보고 초안을 작성합니다. 기존 파일이 있다면 개선 사항을 제안합니다. - 결과를 읽으세요. 명령과 경로가 프로젝트와 맞는지 확인하고 추측은 삭제하세요. 예를 들어, 프로젝트에 없는 테스트 명령이 들어갔다면 지우세요. 여러분만 아는 제약 사항은 직접 추가하면 됩니다.
- 파일을 저장하고 프로젝트 폴더에서 새 세션을 여세요.
/context를 입력하면 Memory files 섹션에 CLAUDE.md 경로가 표시되어야 합니다.
이제 작은 변경을 시도해 보세요. 예를 들어 카드 추가를 요청하고 색상이 유지됐는지, 확인 결과 보고서가 나왔는지 살펴보세요. 파일이 목록에 없다면 먼저 파일 이름과 실행한 폴더를 확인하세요. 목록에는 있지만 결과가 규칙과 다르다면 표현이 명확한지, 서로 충돌하는 지침이 있는지 확인하세요.
목록에 파일이 보이면 로드된 것은 확인할 수 있지만, 규칙 준수까지 보장되지는 않습니다. 에이전트가 정답을 내놓았다고 해서 파일이 로드됐다고 볼 수도 없습니다. 다른 파일에서 정보를 찾았을 수 있으니까요. 지침은 작업 방향을 잡아 주지만, 기술적으로 특정 행동을 금지하지는 않습니다.
나머지는 어디에 기록할까요?
첫 프로젝트에는 CLAUDE.md 하나면 충분합니다. 개인 지시사항이 생기거나 공통 규칙이 많아지면, 이 다이어그램을 보고 어디에 기록할지 정해 보세요.
공통 규칙이 한 폴더에만 적용되더라도 팀 전체에 필요할 수 있습니다. .claude/rules/를 사용하면 지침을 주제별로 나눌 수 있습니다. 특정 경로에만 적용하는 설정은 별도로 해야 합니다. 규칙이 몇 개뿐이라면 구조를 복잡하게 만들 필요는 없습니다.
CLAUDE.local.md는 이 프로젝트에서 개인 지시사항을 적어 두기에 알맞습니다. 예를 들어 짧은 답변을 선호한다는 내용입니다. 커밋되지 않도록 .gitignore에 추가하세요. 로컬 파일도 에이전트가 읽으므로 비밀 정보는 넣지 마세요.
자동 메모리(auto memory)는 기능이 켜져 있을 때 Claude가 작업 중에 저장하는 별도의 메모입니다. 중요한 규칙을 Claude의 판단에만 맡기지 마세요. CLAUDE.md에 추가해 달라고 분명히 요청하세요. 일시적인 버그 추측은 작업 메모에 남기면 됩니다.
프로젝트에 이미 AGENTS.md가 있다면 내용을 다른 파일에 그대로 복사하지 마세요. CLAUDE.md에 @AGENTS.md라는 줄을 넣어 인접한 파일을 불러올 수 있습니다. 특히 CLAUDE.local.md를 추가할 때 유용합니다. 개인 파일이 AGENTS.md를 직접 읽는 방식에 영향을 줄 수 있기 때문입니다. 다른 방법은 문서에 설명되어 있습니다.
규칙은 언제 업데이트할까요?
프로젝트와 함께 파일도 수정하세요. 스타일을 index.html에서 별도 파일로 옮겼다면 구조 설명을 고치세요. 확인 방법을 바꿨다면 이전 지침을 교체하세요. 충돌하는 이전 규칙을 그대로 둔 채 새 규칙을 덧붙이지 마세요.
반복되는 지적은 에이전트에게 기록하도록 맡길 수 있습니다. "완성된 블록을 삭제하기 전에 내 확인을 받도록 CLAUDE.md에 추가해 줘."라고 요청해 보세요. 그런 다음 변경 사항을 읽어 보세요. 에이전트가 임의로 새 제약을 덧붙이지 않고 여러분의 약속을 그대로 담아야 합니다. 한 줄이면 충분한 경우가 많습니다.
에이전트가 규칙을 어겼다면 같은 말을 세 번 더 반복하기보다 먼저 원인을 살펴보세요. 오래된 기록은 지우고 다음 작업에 도움이 되는 내용만 남기세요.
GO TO FULL VERSION