CLAUDE.md 작성법: Claude Code가 프로젝트 규칙을 기억하게 만들기
Claude Code에 홈페이지를 만들어 달라고 요청했다고 생각해 보겠습니다.
첫날에는 “한국어로 작성해 줘”, “모바일 화면을 먼저 확인해 줘”, “내 승인 없이 사이트를 공개하지 마”라고 자세히 설명합니다.
그런데 며칠 뒤 새 대화에서 같은 프로젝트를 수정하려고 하면, 방금 설명한 규칙을 다시 알려줘야 하는 상황이 생길 수 있습니다.
이럴 때 활용할 수 있는 것이 CLAUDE.md입니다.
프로젝트에 꼭 필요한 작업 기준을 파일로 남겨 두면 Claude Code가 이후 세션에서 그 내용을 참고할 수 있습니다.
이번 글에서는 처음 사용하는 사람도 따라 할 수 있도록 파일 만들기 → 규칙 작성 → 적용 확인 → 잘못된 규칙 수정까지 순서대로 살펴보겠습니다.
이 글의 순서
- 1. CLAUDE.md 에는 어떤 내용을 적으면 좋을까요?
- 2. 파일은 어디에 만들어야 하나요?
- 3. 가장 쉬운 방법은 /init으로 시작하기
- 4. 복사해서 사용하는 CLAUDE.md 예제
- 5. 좋은 규칙과 나쁜 규칙은 어떻게 다를까요?
- 6. 작성한 규칙이 실제로 적용됐는지 확인하는 방법
- 7. 내 모든 프로젝트에 같은 규칙을 적용하려면?
- 8. 규칙을 너무 많이 적으면 오히려 불리합니다
- 9. 프로젝트가 커지면 규칙도 나눠 보세요
- 10. 다른 문서를 연결하면 더 효율적일까요?
- 11. CLAUDE.md 에 ‘배포 금지’를 쓰면 실제로 막히나요?
- 12. 규칙을 수정하고 유지하는 요령
- 자주 묻는 질문
- 결론: 프로젝트 규칙은 길게 쓰기보다 자주 필요한 것만 정확하게
1. CLAUDE.md에는 어떤 내용을 적으면 좋을까요?
정답은 의외로 간단합니다.
Claude가 새 대화에서도 반드시 알아야 하는 프로젝트의 공통 규칙을 적으면 됩니다.
예를 들어 이런 정보입니다.
- 홈페이지는 한국어로 작성합니다.
- 주로 수정할 파일은
index.html입니다. - 기존 디자인과 이미지는 사용자가 요청하지 않으면 삭제하지 않습니다.
- 실제 실행하지 않은 테스트를 성공했다고 보고하지 않습니다.
- 인터넷에 공개하거나 다른 사람에게 메일을 보내기 전에는 승인을 요청합니다. 매번 새 채팅에 복사하던 내용을 재사용 가능한 작업 지침으로 바꾸는 것입니다.
여기서 기억할 점이 있습니다. CLAUDE.md에 규칙을 적었다고 Claude가 모든 상황에서 100% 이를 따르는 것은 아닙니다.
이 파일은 AI가 참고하는 지침이며, 파일 삭제나 외부 배포를 기술적으로 차단하는 보안 기능 자체는 아닙니다. 권한 설정과 사용자 승인은 별도로 필요합니다.
2. 파일은 어디에 만들어야 하나요?
초보자는 작업 중인 프로젝트 폴더 맨 위에 CLAUDE.md 파일을 하나 만드는 방법부터 시작하면 됩니다.
앞서 GitHub Pages 실습에서 사용한 가상의 프로젝트를 예로 들겠습니다.
my-first-site/
├── index.html
├── README.md
└── CLAUDE.md
여기서 index.html은 홈페이지 파일이고, CLAUDE.md는 Claude Code가 해당 프로젝트를 작업할 때 참고할 규칙 파일입니다.
파일 이름은 정확히 CLAUDE.md로 적는 것이 좋습니다. claude.txt 또는 CLAUDE.md.txt로 저장하면 의도한 기능이 작동하지 않을 수 있습니다.
파일은 일반적인 텍스트 편집기로 직접 만들어도 됩니다.
다만 이미 프로젝트 안에 CLAUDE.md가 있다면 새 파일로 덮어쓰지 말고 기존 내용을 먼저 확인하세요.
3. 가장 쉬운 방법은 /init으로 시작하기
직접 작성하기 어렵다면 Claude Code의 초기화 기능을 사용할 수 있습니다.
먼저 Claude Code에서 실제 작업할 프로젝트를 엽니다. 터미널에서 시작한다면 프로젝트 폴더 안에서 실행해야 합니다.
claude
이후 Claude Code 대화창에 다음 명령을 입력합니다.
/init
Claude Code는 프로젝트의 파일 구조와 사용 기술을 살펴보고 기본 CLAUDE.md 파일을 만들기 위한 내용을 작성할 수 있습니다.
여기서 중요한 것은 자동 생성된 내용을 검토하는 것입니다.
AI가 프로젝트를 조사하면서 실제로 존재하지 않는 명령이나 오래된 파일 경로를 적을 수도 있습니다.
예를 들어 사이트가 단일 HTML 파일인데 npm run build라는 실행 명령을 만들어 넣었다면, 그 명령이 정말 필요한 프로젝트인지 먼저 확인해야 합니다.
공식 안내에 따르면 이미 CLAUDE.md가 있는 프로젝트에서 /init을 다시 사용하면 기존 파일을 무조건 덮어쓰기보다 개선 사항을 제안할 수 있습니다.
따라서 첫 사용 시에는 이렇게 요청해도 좋습니다.
이 프로젝트의 기존 파일을 확인하고, 꼭 필요한 공통 규칙만
CLAUDE.md에 정리해 줘. 이미 파일이 있다면 덮어쓰지 말고 변경할 내용을 먼저 보여 줘. 실제 존재하지 않는 빌드·테스트 명령은 추가하지 마.
4. 복사해서 사용하는 CLAUDE.md 예제
아래는 개인용 홈페이지 프로젝트에 사용할 수 있는 간단한 예시입니다.
직접 텍스트 파일에 복사하거나, Claude Code에 아래 내용을 토대로 생성해 달라고 요청할 수 있습니다.
파일 이름: CLAUDE.md
# 프로젝트 목적
- 한국어로 작성된 개인 소개용 정적 홈페이지입니다.
- 기존 기능을 유지하면서 필요한 부분만 수정합니다.
# 주요 파일
- 홈페이지는 index.html을 먼저 확인합니다.
- 요청하지 않은 파일이나 폴더를 새로 만들지 않습니다.
# 디자인
- 모바일 320px, 390px 화면에서 가로 넘침을 확인합니다.
- 제목과 버튼의 읽기 쉬운 대비를 유지합니다.
- 사용자가 요청하지 않은 디자인은 임의로 변경하지 않습니다.
# 안전
- 비밀번호, API 키, 개인정보를 공개 HTML에 넣지 않습니다.
- 외부 배포, 공개 저장소 수정, 파일 대량 삭제 전 승인받습니다.
- 외부 서비스 설치·연결이 필요하면 이유를 먼저 설명합니다.
# 검증
- 수정한 기능과 관련된 확인 방법을 안내합니다.
- 실제 실행한 테스트와 실행하지 못한 테스트를 구분합니다.
- 모바일 화면을 직접 보지 못했다면 확인하지 않았다고 보고합니다.
# 작업 완료 보고
- 변경한 파일과 변경 이유를 짧게 정리합니다.
- 실제 확인한 결과와 남아 있는 위험을 따로 알려줍니다.
이 정도만 있어도 프로젝트에서 무엇을 우선하고 무엇을 주의해야 하는지 훨씬 명확해집니다.
예시는 실제 Claude Code에서 검증한 결과가 아니라 공식 문서의 원칙을 바탕으로 만든 교육용 템플릿입니다. 자신의 프로젝트에 맞게 파일 경로와 검증 기준을 바꿔 사용하세요.
5. 좋은 규칙과 나쁜 규칙은 어떻게 다를까요?
규칙을 길게 쓴다고 반드시 잘 작동하는 것은 아닙니다.
예를 들어 이렇게 적으면 어떨까요?
항상 완벽하고 품질이 뛰어난 프로그램을 만들어라.
좋은 의도지만 무엇을 해야 완벽한지 확인하기 어렵습니다.
반면 아래 문장은 다릅니다.
index.html을 변경한 뒤 제목과 버튼이 모바일 320px 화면에서 겹치지 않는지 확인해 줘. 실제 브라우저에서 검증하지 않았다면 ‘미검증’이라고 보고해 줘.
어떤 파일을 확인하고, 어떤 문제가 없어야 하며, 무엇을 보고해야 하는지 분명합니다.
| 모호한 규칙 | 더 좋은 규칙 |
|---|---|
| 최고 품질로 작성해 | 수정 후 관련 테스트 명령을 실행하고 결과를 기록해 |
| 기존 기능을 망가뜨리지 마 | 요청받은 기능 외의 파일은 수정하지 말고 필요한 경우 이유를 설명해 |
| 화면을 예쁘게 만들어 | 320px·390px에서 가로 넘침과 버튼 겹침을 확인해 |
| 안전하게 배포해 | 배포 전에 변경 파일·공개 범위·검증 결과를 보여주고 승인을 요청해 |
결과를 확인할 수 있는 문장으로 작성하는 것이 핵심입니다.
6. 작성한 규칙이 실제로 적용됐는지 확인하는 방법
파일을 저장했다고 끝내지 말고 Claude Code가 읽었는지 확인해 보는 것이 좋습니다.
Claude Code에서 다음 명령을 입력합니다.
/context
현재 대화에 사용된 정보와 함께 Memory files 영역을 확인할 수 있습니다.
여기에 해당 프로젝트의 CLAUDE.md 파일이 나타나는지 살펴보세요.
규칙 파일과 관련된 설정을 확인하거나 편집하려면 아래 명령을 사용할 수도 있습니다.
/memory
그다음 실제 파일을 바꾸지 않는 요청으로 작은 확인을 해보세요.
지금 프로젝트에 적용된 규칙을 바탕으로, 홈페이지를 수정하기 전에 확인해야 할 사항 5개를 알려줘. 어떤 규칙 파일을 참고했는지도 알려줘. 지금은 파일을 수정하지 마.
이때 AI가 예제에 적어 둔 모바일 화면 확인, 배포 승인, 실제 테스트 여부 구분 등을 언급하는지 살펴보면 됩니다.
하지만 규칙이 화면에 보이고 AI가 이를 요약했다고 해서 모든 실제 행동에서 100% 지켜진다는 뜻은 아닙니다.
중요한 변경은 실제 실행 단계에서도 승인 요청과 결과를 확인하세요.
7. 내 모든 프로젝트에 같은 규칙을 적용하려면?
프로젝트마다 반복하는 개인적인 작업 습관도 있을 수 있습니다.
예를 들어 어떤 프로젝트에서든 답변은 한국어로 받고 싶다는 식의 선호입니다.
Claude Code는 규칙 파일을 여러 위치에 둘 수 있습니다.
| 파일 위치 | 적합한 규칙 |
|---|---|
~/.claude/CLAUDE.md |
개인의 모든 프로젝트에 공통으로 적용할 습관 |
프로젝트/CLAUDE.md |
해당 프로젝트의 공통 규칙과 파일 구조 |
프로젝트/.claude/CLAUDE.md |
해당 프로젝트의 공통 규칙을 다른 위치에 보관하는 방식 |
프로젝트/CLAUDE.local.md |
그 프로젝트에서 나만 사용할 별도 설정 |
예를 들어 개인 공통 파일에는 “작업 결과는 한국어로 설명한다”라고 적고, 홈페이지 프로젝트 파일에는 “index.html을 먼저 확인한다”라고 적을 수 있습니다.
개인 공통 규칙에 특정 프로젝트의 세부사항을 모두 섞어 넣지는 않는 편이 좋습니다.
또한 CLAUDE.local.md는 팀원과 공유하지 않는 파일이므로 프로젝트의 .gitignore에 추가해 실수로 GitHub에 올리지 않도록 관리하는 것이 좋습니다.
다만 비밀번호나 API 키 같은 실제 비밀정보를 그 파일에 보관하는 것을 권장하는 것은 아닙니다.
8. 규칙을 너무 많이 적으면 오히려 불리합니다
처음에는 CLAUDE.md에 모든 내용을 저장하고 싶을 수 있습니다.
작업 내역, 최근 오류, 회의록, 경쟁 제품 조사, 사이트 운영 기록, 앞으로 만들 기능까지 계속 추가하다 보면 파일이 매우 길어집니다.
하지만 CLAUDE.md의 내용은 새 세션의 시작부터 AI가 참고하기 때문에, 지나치게 길면 불필요한 정보까지 계속 포함될 수 있습니다.
Anthropic 공식 문서는 CLAUDE.md 파일당 200줄 이하를 목표로 간결하게 유지하라고 권장합니다.
이것은 200줄을 넘으면 프로그램이 작동하지 않는 제한이 아니라, 지침을 더 잘 이해하고 불필요한 입력을 줄이기 위한 권장 기준입니다.
무엇을 남길지 고민된다면 이렇게 판단해 보세요.
“이 규칙을 없앴을 때 Claude가 반복적으로 잘못된 작업을 할 가능성이 있나?”
그렇다면 남길 가치가 있습니다.
반대로 특정 날짜에만 필요했던 조사 내용이나 이미 끝난 오류 기록이라면 별도 문서로 옮기는 편이 낫습니다.
9. 프로젝트가 커지면 규칙도 나눠 보세요
홈페이지가 점점 복잡해지면 디자인 규칙, 테스트 규칙, 특정 폴더에서만 쓰는 규칙을 구분하고 싶어질 수 있습니다.
Claude Code에서는 아래처럼 .claude/rules/ 폴더를 활용할 수 있습니다.
my-first-site/
├── CLAUDE.md
├── index.html
└── .claude/
└── rules/
├── design.md
└── testing.md
디자인 지침과 테스트 지침을 주제별로 나누면 관리가 수월해집니다.
다만 폴더로 나누기만 하면 모든 규칙을 필요한 순간에만 읽는 것은 아닙니다. 별도 조건이 없는 .claude/rules 파일은 매 세션 불러올 수 있습니다.
특정 파일을 다룰 때만 규칙을 적용하려면 파일 맨 위에 대상 경로를 지정할 수 있습니다.
예를 들어 JavaScript 파일에만 적용할 지침은 다음처럼 작성할 수 있습니다.
---
paths:
- "src/**/*.js"
---
# JavaScript 작업 규칙
- 변경한 코드와 관련된 테스트를 실행하고 결과를 기록합니다.
- 테스트를 실행하지 않았다면 미실행이라고 보고합니다.
이 설정은 지정된 경로의 파일을 다룰 때 규칙을 불러오는 용도입니다. 프로그램 전체의 쓰기 권한을 강제로 제한하는 보안 설정은 아닙니다.
처음에는 굳이 이런 구조까지 만들 필요가 없습니다. 프로젝트 CLAUDE.md 하나로 시작하고, 실제 규칙이 늘어날 때 분리하세요.
10. 다른 문서를 연결하면 더 효율적일까요?
이미 프로젝트에 AGENTS.md라는 규칙 파일이 있을 수도 있습니다.
Claude Code는 CLAUDE.md를 읽으며, AGENTS.md 파일을 자동으로 똑같이 취급하지는 않습니다.
두 파일을 함께 사용하고 싶다면 CLAUDE.md 안에 다음처럼 적는 방법이 있습니다.
@AGENTS.md
# Claude Code 추가 규칙
- 수정 후 실제 수행한 테스트 결과를 보고합니다.
이렇게 하면 별도로 작성한 규칙을 가져올 수 있습니다.
하지만 중요한 점이 있습니다. @AGENTS.md처럼 파일을 가져오면 그 문서 내용도 함께 읽습니다.
즉, 긴 자료를 별도 파일로 옮겼다고 자동으로 토큰 사용량이 줄어드는 것은 아닙니다.
가끔만 필요한 긴 절차나 자세한 참고자료는 CLAUDE.md에 계속 포함시키기보다 별도의 Skill로 필요할 때 사용하는 방식을 검토할 수 있습니다.
처음부터 여러 설정을 복잡하게 만들기보다 늘 필요한 규칙과 가끔 필요한 자료를 구분하는 것만 기억해도 충분합니다.
11. CLAUDE.md에 ‘배포 금지’를 쓰면 실제로 막히나요?
이 부분은 특히 중요합니다.
예제에는 “공개 배포 전에 승인받는다”는 문장이 있습니다.
이것은 Claude에게 따라야 할 행동 기준을 알려주는 지침입니다.
하지만 CLAUDE.md에 적었다는 이유만으로 GitHub에 코드를 올리거나 파일을 삭제하는 동작이 기술적으로 절대 불가능해지는 것은 아닙니다.
실제 동작을 제한하려면 Claude Code의 권한 설정, 자동 실행 설정, 조직의 보안 정책, 필요한 경우 훅 등을 별도로 사용해야 합니다.
예를 들어 배포를 절대 허용하지 않는 개발 환경이라면 다음 두 가지를 구분해야 합니다.
행동 지침: “배포 전에 승인을 요청해 줘.”
실제 제한: 배포에 필요한 인증정보·명령 권한·네트워크 접근을 기술적으로 제한.
중요한 업무에서는 둘 다 필요할 수 있습니다.
또한 CLAUDE.md와 회사 기밀 문서를 GitHub에 잘못 공개하지 않도록 저장소의 공개 여부와 파일 내용을 항상 확인해야 합니다.
12. 규칙을 수정하고 유지하는 요령
CLAUDE.md를 처음부터 완벽하게 만들 필요는 없습니다.
실제 사용하면서 반복되는 문제를 발견했을 때 한두 줄씩 고치고 다시 검증하는 방식이 좋습니다.
예를 들어 Claude가 기존 화면을 자꾸 지나치게 바꾼다면 이런 항목을 추가할 수 있습니다.
사용자가 수정 범위를 지정했다면 그 범위 외의 디자인과 레이아웃을 변경하지 않습니다. 범위를 넓혀야 하는 경우 이유를 먼저 설명합니다.
또 Claude가 테스트를 실행하지 않고 완료라고만 말한다면 이렇게 바꿉니다.
실제 실행한 테스트, 단순 코드 검토, 실행하지 못한 테스트를 서로 구분해서 보고합니다.
새 규칙을 넣었다면 /context로 파일이 로드됐는지 확인하고, 간단한 요청으로 의도한 행동이 반영되는지 점검하세요.
오래된 규칙을 계속 쌓기만 하지 말고, 지금 프로젝트에 더는 맞지 않는 내용은 삭제하거나 수정하는 것이 중요합니다.
자주 묻는 질문
Q. CLAUDE.md는 무료로 만들 수 있나요?
네. 일반 텍스트 편집기로 만들 수 있는 파일 자체에는 별도 요금이 필요하지 않습니다. 다만 Claude Code를 실제로 사용하는 계정·모델의 사용량 조건은 별개입니다.
Q. 파일을 만들면 예전 대화 내용을 모두 기억하나요?
아닙니다. CLAUDE.md에는 작성하거나 연결한 내용만 들어갑니다. 이전 대화의 모든 메시지를 자동으로 완벽하게 저장·복원하는 기능은 아닙니다.
Q. /init을 실행하면 항상 좋은 규칙이 자동 완성되나요?
아닙니다. 프로젝트를 분석해 기본 내용을 작성하지만 실제 파일, 빌드 명령, 테스트 방식은 사람이 검토해야 합니다.
Q. CLAUDE.md와 자동 메모리는 같은 것인가요?
서로 다릅니다. CLAUDE.md는 사람이 관리하는 프로젝트 지침, 자동 메모리는 Claude가 작업 중 중요하다고 판단한 정보를 별도로 기록하는 방식입니다. 저장 위치와 관리 방법이 다릅니다.
Q. 파일이 200줄을 넘으면 적용되지 않나요?
아닙니다. 200줄 이하는 공식 권장 목표입니다. 지나치게 길면 매 세션 읽어야 할 정보가 많아지고 중요한 규칙을 놓칠 가능성이 있어 간결하게 유지하라고 안내합니다.
Q. GitHub에 CLAUDE.md를 올려도 되나요?
팀과 공유할 프로젝트 규칙이라면 올릴 수 있습니다. 다만 공개 저장소에서는 누구나 파일을 열람할 수 있으므로 인증정보·개인정보·비공개 운영 규칙을 넣으면 안 됩니다.
Q. Claude Code가 내 규칙을 안 지키면 어떻게 해야 하나요?
먼저 /context에서 파일 로딩 여부를 확인하고, 지침이 구체적인지, 다른 CLAUDE.md와 충돌하지 않는지 살펴보세요. 반드시 막아야 하는 행동은 권한 설정과 승인 절차도 함께 검토해야 합니다.
결론: 프로젝트 규칙은 길게 쓰기보다 자주 필요한 것만 정확하게
CLAUDE.md를 잘 활용하는 핵심은 Claude Code가 프로젝트에서 반복적으로 알아야 하는 내용을 짧고 명확하게 남기는 것입니다.
처음에는 파일 하나에 프로젝트 목적, 주로 다룰 파일, 디자인 기준, 안전 규칙, 검증 방법, 완료 보고 방식만 적어 보세요.
/init을 이용하면 출발점을 만들 수 있고, /context로 규칙 파일이 읽혔는지 확인할 수 있습니다.
프로젝트가 커지면 .claude/rules/나 Skills로 내용을 나누면 됩니다.
단, 안전 규칙을 파일에 적는 것과 실제로 권한을 제한하는 것은 다르다는 점을 잊지 마세요.
새 대화를 시작할 때마다 긴 지시문을 반복하는 대신, 작업할 프로젝트에 맞는 짧고 정확한 규칙 파일 하나부터 만들어 보세요.
함께 읽으면 좋은 글
- AI 에이전트란? 챗봇과 다른 점부터 실제 작업·주의사항까지 쉽게 설명 — 프로젝트 지침을 읽고 도구를 쓰는 AI의 작동 범위를 알아봅니다.
- AI 컨텍스트란? ChatGPT가 내 말을 이해하고 잊어버리는 이유 — AI가 참고하는 현재 작업 맥락과 지침 파일의 관계를 살펴봅니다.