결론부터 말하면 — CLAUDE.md 하나 잘 쓰면 매번 같은 설명 안 해도 됩니다. 이 글에서는 그게 왜 그런지, 어떻게 쓰면 되는지 직접 써본 경험을 바탕으로 정리했습니다.
왜 이 글을 쓰게 됐나
사실 매번 같은 말을 반복하는 게 은근히 피곤합니다. "주석 영어로 써줘", "이 라이브러리 쓰지 마", "톤은 이래", "톤은 이래", "톤은 이래"... 어느새 같은 말을 세 번째 하고 있는 자신을 발견하게 돼요. Claude Code든 Copilot이든, 새 대화 = 기억 리셋이라는 사실은 변하지 않습니다. 이걸 받아들이고 한 가지 도구를 쓰기 시작했습니다. 이름은 거창하지만 실은 그냥 마크다운 파일 하나입니다.
CLAUDE.md가 뭔가요
한 문장으로 말하면 "AI가 매번 자동으로 읽는 프로젝트 메모장"입니다. 프로젝트 루트에 CLAUDE.md라는 이름으로 두면, Claude Code가 실행될 때 그 파일을 자동으로 컨텍스트에 포함시킵니다. 별도로 "이 파일 읽어"라고 명령할 필요 없어요. 일종의 자동 로드되는 시스템 프롬프트 같은 거라고 보시면 됩니다.
파일 위치
딱 한 군데, 프로젝트의 최상위 폴더면 됩니다.
[프로젝트 루트] ├── CLAUDE.md ← 여기에 두면 끝 ├── src/ │ └── main.py ├── tests/ └── README.md
왜 최상위냐면 Claude Code가 모든 명령을 실행할 때 작업 디렉토리부터 상위로 탐색하면서 CLAUDE.md를 찾기 때문입니다. 만약 모노레포처럼 여러 패키지가 있다면 각 패키지 폴더마다 따로 둘 수도 있어요. 그러면 폴더별로 다른 규칙이 적용됩니다.
그래서 뭐가 달라지나
체감상 큰 건 세 가지입니다.
1. 매번 같은 설명 안 해도 됩니다
예를 들어 "주석은 영어로 작성"이라고 매번 쳐야 했다면, 이제는 CLAUDE.md에 한 줄 적어두는 걸로 끝이에요. 다음 대화부터는 AI가 그 규칙을 이미 알고 있는 상태로 시작합니다. 인간한테 같은 말을 반복하는 그 묘한 피곤함이 사라져요.
2. 프로젝트 톤이 일관됩니다
블로그 글 같은 경우 톤이 특히 중요하죠. "친근하게", "2000자 내외", "Hook → 본문 → CTA" 같은 규칙을 박아두면, 주제를 던질 때마다 같은 호흡으로 글이 나옵니다. 5화, 10화 쌓여도 톤이 안 새요.
3. 토큰이 절약됩니다
매 대화 시작할 때마다 컨텍스트를 길게 써 보내는 것보다, 파일 한 번 쓰는 게 훨씬 효율적입니다. 응답 속도도 빨라지고, 비용도 줄고, 무엇보다 인간이 더 편해집니다.
어떻게 쓰면 좋은가
100줄짜리 문서를 작성해서 붙여넣는 분들을 가끔 봤는데, 솔직히 별로 안 먹힙니다. 이유는 단순해요 — 100줄짜리 파일에서 AI가 핵심을 못 잡습니다. 30줄 안쪽이 sweet spot이에요. 길어지면 길어질수록 정확도는 더 떨어지는 걸 직접 봤습니다.
제 경험칙: 처음엔 30줄로 시작하고, 쓰다 보면 "아 또 이거 교정했네" 싶은 게 생깁니다. 그때마다 한 줄씩 추가하세요. 몇 달 지나면 진짜 필요한 것만 남습니다.
그리고 단순히 "규칙을 나열"하지 마시고 가능하면 Good / Bad 예시를 같이 적어주세요. 추상적인 한 줄보다 구체적인 코드 예시가 10배는 효과적입니다.
실전 예시 3가지
도메인별로 자주 쓰는 패턴을 정리했습니다. 그대로 복사해서 본인 프로젝트에 맞게 수정하시면 됩니다.
코딩용 — Python 백엔드
FastAPI + SQLAlchemy로 백엔드 짤 때 쓰는 설정입니다.
# 프로젝트: FastAPI 백엔드 ## 코드 스타일 - Python 3.11+ - 타입 힌트 필수 (변수, 함수 반환값) - 비동기(async) 함수 우선 사용 - 들여쓰기: 스페이스 4 ## 주석 규칙 - 영어로 작성 - 복잡한 로직에만 (3줄 이상 또는 알고리즘) - 예시: # Calculate user balance ## 라이브러리 우선순위 1. Pydantic v2 (데이터 검증) 2. SQLAlchemy 2.0 (ORM) 3. pytest (테스트) ## 금지 - print() 디버깅 (logger 사용) - any 타입 남용
기획용 — 콘텐츠 마케팅
SNS 카드뉴스나 블로그 글을 만들 때 씁니다.
# 콘텐츠 기획 가이드 ## 페르소나 - 30대 직장인 - 자기계발 관심 높음 - 메인 채널: 인스타그램, 블로그 ## 톤 - 친근하고 가벼움 (반말 OK) - 이모지 적절히 - 두괄식 구조 (결론 먼저) ## 캠페인 구조 1. Hook (3초 안에 시선 잡기) 2. 공감 (현실적 문제) 3. 해결 (실전 팁) 4. CTA (구독/댓글 유도) ## 피해야 할 것 - 어구(어쩌구) 두리뭉술한 표현 - "~할 수 있다" 같은 추상적 마무리
글쓰기용 — 이 블로그
사실 이 글을 포함한 이 블로그 전체가 이 템플릿을 따르고 있습니다. 지금 보고 계신 이 글도 자동으로 톤이 맞춰진 거예요.
# 블로그 가이드 ## 기본 규칙 - 분량: 2000-3000자 - 한국어 기준, 비격식체 - 제목에 숫자 포함 권장 ## 글 구조 1. Hook (질문 또는 반전) 2. 본문 (Step별 정리) 3. 마무리 (다음 행동 제안) ## 스타일 - 짧은 문장 - 단락은 3줄 이내 - 강조는 **굵게** 또는 > 인용구 ## 예시 톤 - "AI는" 1인칭 시점 - 이모지 절제 (글당 2-3개)
자주 하는 실수 3가지
직접 겪거나 다른 분들 코드 보다가 배운 것들입니다.
너무 많이 쓰기
100줄, 200줄로 늘려놓으면 AI가 핵심을 못 잡습니다. 30줄 이내 권장.
모호한 표현
"깔끔하게", "효율적으로" 같은 단어는 AI마다 해석이 다 다릅니다. 측정 가능한 기준을 적어주세요. "줄 수 80자 이내", "함수 20줄 이내"처럼요.
예시 없이 규칙만
"변수명 동사로"보다 get_user(), user()가 훨씬 효과적입니다.
자주 묻는 것들
Q. CLAUDE.md는 정확히 어디에 두나요?
프로젝트의 루트 디렉토리 최상단에 CLAUDE.md라는 이름으로 두면 됩니다. Claude Code가 자동으로 감지해서 모든 대화 컨텍스트에 포함시켜요.
Q. AGENTS.md와 CLAUDE.md의 차이는?
AGENTS.md는 OpenAI Codex가, CLAUDE.md는 Claude Code가 자동으로 읽는 파일이에요. 둘 다 마크다운 형식이지만 도구마다 인식하는 파일명이 다릅니다.
Q. 한 프로젝트에 여러 개 둘 수 있나요?
네. 서브디렉토리마다 다른 CLAUDE.md를 두면, Claude Code가 현재 작업 중인 폴더의 파일을 자동으로 읽어 적용합니다.
Q. 코딩 말고 다른 일에도 쓸 수 있나요?
당연하죠. 기획, 글쓰기, 번역, 데이터 분석 등 어떤 작업이든 가능합니다. AI에게 영구적으로 기억시킬 컨텍스트라면 무엇이든 담을 수 있어요.
Q. API 키 같은 비밀이어도 되나요?
권장하지 않습니다. 보통 Git에 커밋되니까 .env 같은 별도 파일로 분리하고, CLAUDE.md에는 "비밀키는 .env에서 관리" 같은 언급만 해두는 게 안전합니다.
ConversionConversion EmoticonEmoticon