클로드 코드로 이 블로그를 작업하던 초기에는 세션을 새로 열 때마다 같은 말을 반복했습니다. "빌드는 build.py로 해", "프레임워크 폴더는 건드리지 마", "이미지는 webp로". 그러다 CLAUDE.md를 만들고 나서 이 반복이 사라졌습니다.
CLAUDE.md란?
CLAUDE.md는 클로드 코드가 세션을 시작할 때 자동으로 읽는 마크다운 파일입니다. 사람으로 치면 새로 합류한 동료에게 건네는 "프로젝트 안내서"입니다.
파일 위치별 적용 범위
CLAUDE.md는 둘 수 있는 위치가 여러 곳이고, 위치에 따라 적용 범위가 다릅니다.
| 위치 | 적용 범위 | 용도 |
|---|---|---|
프로젝트 루트 ./CLAUDE.md |
이 프로젝트 전체 | 팀 공유 규칙 (깃에 올림) |
하위 폴더 ./src/CLAUDE.md |
해당 폴더 작업 시 | 폴더별 세부 규칙 |
사용자 폴더 ~/.claude/CLAUDE.md |
내 모든 프로젝트 | 개인 선호 (말투, 공통 습관) |
여러 파일이 있으면 함께 읽힙니다. 공통 규칙은 사용자 폴더에, 프로젝트 규칙은 루트에 두는 식으로 나누면 관리가 쉽습니다.
/init으로 초안 만들기
빈 파일에서 시작할 필요는 없습니다. 프로젝트 폴더에서 클로드 코드를 실행하고 다음 명령을 입력합니다.
/init
클로드가 프로젝트 구조, 설정 파일, 빌드 스크립트를 살펴보고 CLAUDE.md 초안을 만들어 줍니다. 이 초안을 그대로 쓰지 말고 반드시 다듬으세요. 자동 생성된 내용에는 당연한 설명이 많고, 정작 중요한 "하지 말아야 할 것"이 빠져 있는 경우가 많습니다.
꼭 넣어야 할 5가지
- 프로젝트 한 줄 설명 — 무엇을 만드는 프로젝트인지
- 자주 쓰는 명령어 — 빌드, 테스트, 실행, 린트
- 폴더 구조 중 중요한 부분 — 어디에 무엇이 있는지 (전체 트리는 불필요)
- 코딩 규칙 — 팀이 지키는 스타일, 네이밍
- 하지 말아야 할 것 — 건드리면 안 되는 폴더, 금지된 명령
실제로 쓰는 예시
이 블로그 작업에 쓰는 CLAUDE.md를 간추린 것입니다.
# GPTPRO 블로그
정적 사이트 생성기(파이썬)로 만드는 클로드 활용 블로그.
## 명령어
- 빌드: `python build.py`
- 전체 재빌드: `python build.py --force`
- 대표 이미지 생성: `python scripts/make_covers.py`
## 구조
- content/posts/: 글(마크다운, front matter 필수)
- themes/default/templates/: 이 사이트 전용 템플릿 오버라이드
- 프레임워크(antigravity_ssg/)는 다른 사이트와 공용이므로 수정 금지.
바꿔야 하면 사이트 로컬 테마에 오버라이드할 것.
## 글 작성 규칙
- date는 미래 시각 금지, ISO 8601(+09:00) 형식
- 요금·기능 정보에는 "작성 시점 기준" 표기와 공식 링크
## 금지
- public/ 폴더 직접 수정 금지 (빌드 결과물)
- 배포(scripts/deploy_s3.py → S3·CloudFront)는 사용자가 요청할 때만
"수정 금지"와 그 이유를 같이 적어 두니, 클로드가 프레임워크 대신 로컬 테마를 고치는 방향으로 알아서 작업했습니다.
넣지 말아야 할 것
- 비밀번호, API 키, 토큰 — CLAUDE.md는 깃에 올라가는 경우가 많습니다.
- 코드를 보면 알 수 있는 설명 — "main.py는 메인 파일이다" 같은 내용은 토큰만 차지합니다.
- 너무 긴 문서 — 긴 가이드는
docs/폴더에 두고 "자세한 배포 절차는 docs/deploy.md 참고"처럼 경로만 적습니다. - 자주 바뀌는 정보 — 이번 주 할 일 같은 내용은 금방 낡습니다.
유지 관리 요령
- 클로드가 같은 실수를 두 번 하면 그 규칙을 CLAUDE.md에 추가합니다.
- 한 달에 한 번 정도 읽어 보며 더 이상 맞지 않는 내용을 지웁니다.
- 세션 중에 "이 규칙 CLAUDE.md에 추가해 줘"라고 요청하면 클로드가 직접 파일을 수정합니다.
/memory명령으로 메모리 파일을 열어 편집할 수도 있습니다.
'하지 말 것' 섹션의 효과
CLAUDE.md의 효과를 가장 크게 느낀 순간은 "하지 말아야 할 것" 섹션을 추가했을 때였습니다. 그전에는 클로드가 공용 프레임워크 파일을 고치려고 해서 매번 막아야 했는데, 이유와 함께 금지 규칙을 적은 뒤로는 알아서 로컬 오버라이드 방식을 택했습니다. 처음에는 10줄 내외로 시작해, 실수가 생길 때마다 한 줄씩 늘려 가는 방식을 추천합니다.
핵심 요약
- CLAUDE.md는 클로드 코드가 세션마다 읽는 프로젝트 안내서입니다.
/init으로 초안을 만들고, 명령어·구조·규칙·금지 사항 위주로 다듬으세요.- 비밀 정보와 긴 문서는 넣지 말고, 같은 실수가 반복될 때마다 규칙을 추가합니다.
