Claude Code CLAUDE.md 작성법 - 이거 하나로 AI 퀄리티가 완전 달라진다

지난달에 보안 분석 도구의 Phase 5를 Claude Code로 진행하고 있었다. 코드 작성하고 "완료했습니다" 보고를 받았는데, 실제로 실행해보니까 동작을 안 하는 거야. 뭐지? 확인해보니 Claude가 프로젝트 규칙을 전혀 모르는 상태로 작업한 거였거든. 매 세션마다 리셋되니까 당연한 건데, 그때는 진짜 열받았다.

그때 CLAUDE.md를 제대로 세팅하기 시작했다. 결론부터 말하면 - 지금은 프로젝트 10개를 동시에 돌리고 있고, 이런 사고가 거의 안 난다.

CLAUDE.md가 뭔데?

프로젝트 루트에 CLAUDE.md 파일 하나 만들어놓으면, Claude Code가 세션 시작할 때마다 자동으로 읽는다. 사수가 신입한테 주는 인수인계서 같은 거지. "이 프로젝트는 이런 구조고, 이건 절대 하면 안 돼" 적어놓는 건데 - 있고 없고의 차이가 하늘과 땅이야.

나는 보안 분석 도구, 임베디드 리눅스 BSP, 직접 만든 AI 코딩 웹 도구, VS Code 확장, 블로그 자동화까지 전부 Claude Code로 돌리거든. 종류가 완전 다른데, CLAUDE.md 없이? 매번 처음부터 설명해야 함. 답답하지.

500줄짜리 괴물을 만들었던 이야기

처음 CLAUDE.md를 만들었을 때 내가 뭘 했냐면. 프로젝트 파일 구조 전부, 함수 목록 전부, 내가 아는 버그 전부를 때려넣었다. 500줄. 괴물이야.

"이렇게 상세하면 완벽하게 하겠지?" 싶었는데, 결과는 처참했거든.

이유가 웃긴다. Claude Code가 CLAUDE.md를 매 세션마다 통째로 올리니까, 500줄이면 그것만으로 AI의 작업 공간을 엄청나게 잡아먹더라. 무거운 배낭 메고 마라톤 뛰는 꼴이지. 코드 읽을 공간이 부족해져서 오히려 느려지고, 부정확해지고. 본말전도야.

아 맞다, 그리고 500줄 중에 매 세션마다 진짜 필요한 정보? 한 20줄. 나머지 480줄은 특정 상황에서만 쓰는 거였음. 허무하더라.

"찾는 법"을 알려줘라

여기서 삽질을 좀 하다가, 우연히 흥미로운 글을 발견했다. Claude Code 만든 사람이 Boris Cherny라는 엔지니어인데, 이 사람이 한 얘기가 있거든.

"Claude에게 모든 걸 알려주지 마라. 찾는 법을 알려줘라."

이거 읽고 머리를 한 대 맞은 것 같았지. 내가 500줄 때려넣은 게 왜 실패했는지 정확히 설명되는 한 문장이었으니까.

예를 들어볼게.

내가 했던 실수: API 엔드포인트 30개를 CLAUDE.md에 전부 나열함. 매 세션마다 30줄이 날아가는 거지.

지금 하는 방식: "API 엔드포인트는 src/routes/ 확인. 파일 하나가 리소스 하나." 끝. 한 줄이야. Claude Code가 필요할 때 알아서 그 폴더를 뒤지면 되거든. CLAUDE.md는 가벼워지고, 작업 공간은 넉넉해지고. 이 원칙 하나가 모든 걸 바꿨다.

내 CLAUDE.md - 지금 쓰는 구조

3개월간 계속 깎고 다듬은 결과, 지금은 이런 뼈대로 쓰고 있다.

절대 규칙 (5줄 이내) - 프로젝트에서 어기면 안 되는 것만. "테스트 없이 완료 보고 금지", "추정치와 실측치 구분 필수" 이런 거. 왜 이런 규칙이 생겼냐고? 위에서 말한 Phase 5 사건 때문이야. 코드만 작성하고 "됐다" 하는 습관을 끊어야 했거든. 뼈아프지만 규칙 넣고 나서 확 달라졌다.

접속 정보와 경로 (10줄) - 서버 IP, SSH 정보, 핵심 파일 위치. 이게 없으면 세션마다 "서버 IP가 뭐야?" 물어봄. 짜증나.

진행 상태 (10줄) - 지금 뭘 하고 있는지, 최근에 뭘 끝냈는지. 솔직히 세션 끝날 때마다 업데이트하는 게 귀찮긴 해. 근데 다음 날 새 세션 열었을 때 "어디까지 했더라?" 하는 시간이 사라지니까, 그 귀찮음을 감수할 가치가 있더라.

참조 포인터 (5줄) - 여기가 핵심이야! 상세 문서는 docs/ 폴더에 따로 두고, CLAUDE.md에서는 링크만 건다. "Phase 상세는 docs/phases.md 참조" 이런 식으로. 200줄짜리 Phase 기록을 CLAUDE.md에 직접 넣으면? 매 세션마다 200줄이 작업 공간 잡아먹잖아. 미친 짓이지.

총합 30~50줄. 500줄에서 여기까지 줄이는 데 한 달 걸렸다. 길었음.

관련 글

→ 구글 젬마4 써봤는데, 솔직히 이건 좀 미쳤다

글로벌 CLAUDE.md - 10개 프로젝트를 관리하는 비결

여기서 잠깐, Claude Code는 CLAUDE.md를 두 곳에서 읽는다는 거 알고 있었어?

하나는 홈 디렉토리의 글로벌 CLAUDE.md. 모든 프로젝트에 공통인 규칙을 여기에 넣어놓음. "응답은 한국어로", "코드 수정 후 테스트 필수" 같은 거.

다른 하나는 프로젝트 루트의 CLAUDE.md. 해당 프로젝트 전용 규칙.

이게 왜 좋냐면 - 프로젝트 10개인데 공통 규칙을 각각 복사하면 나중에 하나 고칠 때 10군데 다 고쳐야 하잖아. 현실적으로 안 하게 되지. 글로벌에 한 번만 적으면 끝이니까, 관리 부담이 확 줄었거든.

.claude/rules/ - 이걸 몰라서 한 달을 낭비했다

참고로 .claude/rules/ 라는 디렉토리가 있다. 규칙을 파일별로 쪼갤 수 있는 건데, 솔직히 이거 좀 늦게 알았어.

내가 뭘 했었냐면, 프론트엔드 규칙이랑 백엔드 규칙을 전부 CLAUDE.md 하나에 우겨넣었거든. 백엔드 API 작업하는데 "React 컴포넌트는 함수형으로 작성" 규칙이 올라와 있는 거야. 쓸데없이 공간만 차지하지.

rules/ 디렉토리를 쓰면 이걸 해결할 수 있다. rules/frontend.md, rules/backend.md 이렇게 나눠놓고, 파일 앞부분에 paths를 지정하면 해당 파일을 편집할 때만 규칙이 로딩돼. .tsx 만질 때만 프론트 규칙이 뜨고, .py 만질 때만 백엔드 규칙이 뜨는 거지.

이거 적용하고 나서 "아 진작 알았으면..." 했다. 한 달 동안 불필요한 규칙이 매번 올라오는 걸 그냥 참고 있었으니까.

실전에서 느낀 것

과장 좀 보태서가 아니라, CLAUDE.md 세팅이 Claude Code 활용의 절반이다.

나는 직접 만든 AI 코딩 웹 도구 프로젝트에서 Phase 30개를 Claude Code로 완주했거든. 에이전트 모드, 플랜 모드, 메모리 시스템, RAG 검색, Git 연동, 웹 터미널까지 - 2주 만에 전부 구현했다. CLAUDE.md 없이 이게 가능했을까? 절대 아니야. 10개도 못 했을 거다.

매 세션마다 "우리 프로젝트는요, 지금 Phase 17이고요, 서버 IP는요..." 이러면서 5~10분씩 날리는 거. 하루 두 세션이면 20분, 한 달이면 10시간이야. 그 시간에 Phase 하나를 더 끝낼 수 있었다는 거지.

아직 CLAUDE.md 안 만들었으면, 지금 당장 하나 만들어보자. 5줄이면 된다. "절대 규칙 3개 + 핵심 경로 2개" - 이것만으로도 다음 세션이 달라질 거야. 진짜로.

다음 편에서는 Claude Code 에이전트 10명을 세팅해서, 혼자인데 개발팀 있는 것처럼 굴리는 법을 다룬다.

이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.

'베스트셀러' 쿠팡에서 최저가 확인하기