이 장에서 배우는 것
•
CLAUDE.md가 무엇이고 언제 만들어야 하는지
•
Claude Code에게 시켜서 만드는 방법
•
좋은 규칙과 나쁜 규칙의 차이
•
프로젝트별 설정 vs 전역 설정 구분
•
CLAUDE.md가 너무 길어졌을 때 정리하는 방법
•
규칙이 안 먹힐 때 원인 파악하기
Claude Code에게 같은 말을 반복하고 있다면, CLAUDE.md에 적어둡니다. 이 장에서는 CLAUDE.md가 무엇이고, 어떻게 활용하는지 다룹니다.
CLAUDE.md란
CLAUDE.md는 Claude Code가 매 대화를 시작할 때 자동으로 읽는 설정 파일입니다.
예를 들어, 매번 "보고서는 한국어로 써줘", "표를 꼭 포함해줘"라고 말하고 있다면, 이 내용을 CLAUDE.md에 적어두면 더 이상 반복할 필요가 없습니다.
언제 만들면 좋을까
처음부터 만들 필요는 없습니다. Claude Code를 쓰다가 같은 지시를 3번 이상 반복하고 있다면, 그때 만드는 것을 권합니다.
CLAUDE.md가 없으면 생기는 문제 매주 보고서를 만드는데, 어느 날 "경영진 대상, 한국어, 표 포함"을 빼먹고 지시합니다. Claude가 영어로, 불릿 포인트만으로 보고서를 만들어버립니다. 다시 지시해서 수정하면 되지만, 매번 기억해서 말해야 한다는 것 자체가 비효율입니다.
CLAUDE.md를 만들 신호:
•
보고서를 쓸 때마다 "경영진 대상, 한국어, 표 포함"을 반복한다
•
파일 정리를 시킬 때마다 "/data 폴더는 건드리지 마"라고 말한다
•
매번 "~합니다 체로 써줘"라고 톤을 지정한다
만드는 방법
가장 쉬운 방법은 Claude Code에게 시키는 것입니다.
CLAUDE.md 파일을 만들어줘.
보고서는 항상 한국어로, 경영진 대상으로, 표와 그래프를 포함해서 작성해야 한다고 적어줘.
Plain Text
복사
또는 /init 명령어를 입력하면 Claude가 현재 폴더를 분석해서 기본 CLAUDE.md를 만들어줍니다.
내용을 추가하고 싶을 때도 직접 편집할 필요 없이:
CLAUDE.md에 "/data 폴더의 원본 파일은 수정하지 말 것"이라는 규칙을 추가해줘
Plain Text
복사
마크다운 기초
CLAUDE.md는 마크다운이라는 간단한 형식으로 작성됩니다. 핵심만 알면 됩니다:
•
# 제목 (큰 제목)
•
## 소제목
•
- 목록 항목
•
**굵은 글씨**
직접 수정할 일은 많지 않습니다. 대부분 Claude Code에게 "CLAUDE.md에 이 규칙 추가해줘"라고 시키면 됩니다.
실전 예시
마케팅 보고서 자동화
# 마케팅 보고서 자동화
## 파일 구조
- /data: 원본 데이터 (수정 금지)
- /reports: 생성된 보고서
## 규칙
- 보고서는 항상 표와 그래프를 포함합니다
- 독자는 경영진입니다. 전문 용어를 피합니다
- 한국어로 작성합니다
Plain Text
복사
블로그 글쓰기
# 블로그 작성
## 톤
- "~합니다" 체
- 쉽고 간결하게, 전문 용어 최소화
## 형식
- 제목 + 소제목 구조
- 한 문단은 3줄 이내
- 결론에 핵심 요약 포함
Plain Text
복사
거래처 관리
# 거래처 데이터 관리
## 파일 위치
- /거래처: 거래처 목록 및 계약서
- /송장: 월별 송장 파일
## 규칙
- 거래처 이름은 항상 정식 명칭 사용 (약칭 금지)
- 금액은 원 단위, 천 단위 쉼표 포함
- 원본 파일은 수정하지 않고 새 파일로 저장
Plain Text
복사
필요한 만큼만 적으세요. 짧을수록 좋습니다. CLAUDE.md는 매 대화마다 Claude가 읽습니다. 길어질수록 사용량도 늘어납니다. 10~50줄이 적당합니다.
CLAUDE.md에 넣으면 안 되는 것
CLAUDE.md가 편리하다고 해서 아무 내용이나 넣으면 오히려 문제가 됩니다.
일시적인 지시
# 이번 주 할 일
- 월요일: 마케팅 보고서 작성
- 화요일: 거래처 데이터 정리
Plain Text
복사
이런 내용은 일주일이 지나면 쓸모없어집니다. CLAUDE.md에는 반복적으로 적용되는 규칙만 넣으세요.
너무 당연한 규칙
- 오류가 없도록 정확하게 작업하세요
- 최선을 다해주세요
Plain Text
복사
Claude는 이런 규칙이 없어도 이미 정확하게 작업하려고 합니다. 의미 없는 규칙은 파일만 길어지게 합니다.
서로 모순되는 규칙
- 간결하게 작성합니다
- 근거와 배경을 상세히 설명합니다
- 1페이지 이내로 작성합니다
Plain Text
복사
간결함과 상세함을 동시에 요구하면, Claude는 매번 어중간한 결과를 냅니다.
자주 바뀌는 데이터
- 이번 분기 매출 목표: 15억
- 주요 거래처: A사, B사, C사
Plain Text
복사
이런 정보는 분기마다 바뀝니다. CLAUDE.md에 넣으면 업데이트를 잊어버리기 쉽고, 오래된 정보가 잘못된 결과를 만들어냅니다.
흔한 실수와 문제 해결
CLAUDE.md가 너무 길어졌을 때
규칙을 하나씩 추가하다 보면 어느새 50줄, 100줄이 됩니다. 두 가지 문제가 생깁니다:
1.
사용량 증가: CLAUDE.md 전체가 매 대화마다 읽히므로 긴 파일은 토큰을 소모합니다.
2.
규칙 간 충돌 가능성 증가: 규칙이 많아지면 서로 모순되는 경우가 생기기 쉽습니다.
50줄이 넘으면 정리가 필요한 신호입니다 `` CLAUDE.md를 보여줘 `` 내용을 확인한 뒤, 더 이상 쓰지 않는 규칙이나 중복된 내용을 정리하세요.
Claude가 CLAUDE.md 규칙을 안 따를 때
CLAUDE.md에 규칙을 적었는데 Claude가 무시하는 것처럼 보일 때가 있습니다. 원인은 대부분 다음 중 하나입니다:
•
규칙이 너무 모호해서: "좋은 문장으로 써줘"보다 "한 문장은 30자 이내로"가 Claude에게 더 명확합니다.
•
다른 규칙과 충돌해서: 앞의 규칙과 뒤의 규칙이 모순되면, Claude가 둘 중 어느 쪽을 따를지 예측하기 어렵습니다.
•
대화 중 지시가 CLAUDE.md를 덮어써서: 대화에서 직접 지시한 내용이 CLAUDE.md보다 우선합니다.
디버깅 방법:
CLAUDE.md에 있는 규칙을 전부 보여주고, 지금 이 작업에 어떤 규칙이 적용되는지 설명해줘
Plain Text
복사
/init으로 만든 CLAUDE.md가 이상할 때
/init 명령어로 자동 생성된 CLAUDE.md는 반드시 내용을 확인하고 맞지 않는 부분을 수정하세요. 자동 생성된 것을 그대로 쓰기보다는 검토 후 수정하는 것을 권장합니다.
프로젝트별 vs 전역 설정
CLAUDE.md는 여러 곳에 둘 수 있습니다.
위치 | 적용 범위 | 적합한 내용 |
./CLAUDE.md (프로젝트 폴더) | 해당 폴더에서만 | 파일 구조, 데이터 형식 등 |
~/.claude/CLAUDE.md (홈 폴더) | 어디서든 항상 | 언어, 톤, 응답 스타일 등 |
둘 다 있으면 두 파일 내용이 합쳐져서 적용됩니다 전역 설정에 "한국어로 답변"을 넣어두고, 프로젝트별로 해당 프로젝트 규칙만 추가하면 효율적입니다.
설정이 충돌할 때
프로젝트 CLAUDE.md에 "~합니다 체로 써줘"가 있고, 지시할 때 "~요 체로 써줘"라고 하면 어떻게 될까요?
직접 입력한 지시가 우선합니다. CLAUDE.md는 기본값이고, 대화에서 직접 지정하면 그쪽을 따릅니다.
주의할 점
CLAUDE.md가 길어지면 매 대화마다 Claude가 읽는 양이 늘어나서 사용량이 증가합니다. 꼭 필요한 내용만 넣고, 더 이상 쓰지 않는 규칙은 정리합니다.
현재 어떤 규칙이 설정되어 있는지 잊어버렸을 때는:
CLAUDE.md 내용을 보여줘
Plain Text
복사
직접 해보기
작업 폴더에서 "CLAUDE.md를 만들어줘. 한국어로 답변하라는 규칙을 넣어줘" 지시하기
CLAUDE.md에 규칙 하나 추가하기 (예: "표는 마크다운 형식으로 만들어줘")
"CLAUDE.md 내용을 보여줘" 요청해서 내용 확인하기
규칙이 제대로 적용되는지 테스트하기: 규칙을 넣은 후 관련 작업을 시켜서 결과 확인
정리
•
CLAUDE.md는 매번 반복하는 지시를 저장해두는 설정 파일입니다.
•
처음부터 만들 필요 없이, 반복이 느껴질 때 Claude Code에게 만들어달라고 하세요.
•
짧고 필요한 것만 적는 것이 좋습니다 (10~50줄 적당).
•
일시적인 지시, 모순되는 규칙, 자주 바뀌는 데이터는 CLAUDE.md에 넣지 마세요.
•
규칙이 무시되는 것 같으면 Claude에게 직접 물어봐서 어떤 규칙이 적용되고 있는지 확인하세요.