Claude Code 쓰면서 배운 CLAUDE.md 활용법 — 토큰도 아끼고 맥락도 잡는 방법
세션 껐다가 다시 켜면 어떻게 되는지 아시죠?
열심히 쌓아놓은 대화 맥락이 전부 날아가요. 그러면 또 처음부터 “이 프로젝트는 파이썬 기반이고, 폴더 구조는 이렇고, 지금 하고 싶은 건…” 이렇게 다시 설명해야 해요. 솔직히 이게 한두 번이면 괜찮은데, 매번 반복되니까 진짜 지치더라고요.
반대 문제도 있었어요. 세션을 너무 오래 유지하면 이번엔 Claude가 초반에 했던 얘기를 슬슬 잊어버리기 시작해요. 앞에서 분명히 “이 파일은 건드리지 말자”고 했는데 어느 순간 아무렇지 않게 수정하고 있는 거예요.
저도 한동안 이 두 문제를 번갈아 겪으면서 뭔가 근본적인 해결책이 없나 찾아봤어요. 그러다가 알게 된 게 CLAUDE.md예요.
CLAUDE.md가 뭔지, 비전공자 눈높이로 설명해볼게요
프로그래밍 잘 모르셔도 괜찮아요. 아주 쉽게 설명할게 있어요.
Claude Code는 AI와 함께 코딩하는 툴인데요, 보통 AI는 대화를 시작할 때마다 “저 아무것도 몰라요” 상태로 다시 시작해요. 사람으로 치면 매 출근마다 기억을 잃고 오는 동료 같은 거예요. 그 동료한테 매일 “우리 프로젝트는 이런 거야”부터 설명해야 하는 거죠.
CLAUDE.md는 쉽게 말하면 Claude한테 주는 사전 브리핑 문서예요. 프로젝트 폴더 안에 이 파일을 만들어두면, Claude Code가 작업을 시작할 때 이 파일을 자동으로 읽어요. 여러분이 매번 설명하지 않아도 되는 거예요.
마크다운(.md) 형식이라 메모장처럼 그냥 텍스트로 쓰면 돼요. 특별한 코딩 지식 없어도 작성할 수 있어요.
핵심 한 줄 정리: CLAUDE.md = Claude가 매번 읽는 프로젝트 설명서
더 자세한 내용은 Claude Code 공식 가이드도 참고해보세요.
왜 토큰 사용량이랑 연결되냐고요?
여기서 잠깐 ‘토큰’이랑 ‘컨텍스트 윈도우’ 얘기를 해야 해요. 어렵게 들리지만 진짜 간단해요.
토큰은 AI가 처리하는 텍스트 단위예요. 단어 하나가 대략 토큰 하나라고 생각하면 돼요. Claude 같은 AI는 한 번에 처리할 수 있는 토큰 수에 한계가 있어요. 이 한계를 ‘컨텍스트 윈도우’라고 불러요.
문제는 대화가 길어질수록 이 공간이 점점 찬다는 거예요. 처음엔 잘 기억하다가 나중엔 앞 내용을 잊어버리는 이유가 이거예요. 컨텍스트가 꽉 차면 오래된 내용부터 밀려나거든요.
근데 CLAUDE.md를 잘 쓰면 이 공간을 훨씬 효율적으로 쓸 수 있어요. 매번 대화에서 길게 설명하던 내용을 파일 하나로 압축해서 전달하니까, 실제 작업 대화에 쓸 수 있는 토큰이 늘어나는 거예요.
핵심 한 줄 정리: CLAUDE.md = 매번 반복 설명 줄이기 → 남은 토큰으로 진짜 작업에 집중
제가 직접 써보고 효과 봤던 CLAUDE.md 구성
처음엔 뭘 써야 할지 막막했어요. 그냥 프로젝트 이름 적으면 되나? 싶기도 하고요. 여러 번 써보면서 지금은 크게 네 가지 섹션으로 나눠서 작성해요.
1. 프로젝트 개요
가장 기본이에요. 이 프로젝트가 뭔지, 왜 만들고 있는지 두세 문장으로 써요.
프로젝트 개요
파이썬 기반 ETL 파이프라인 프로젝트입니다.
공공데이터를 수집해서 PostgreSQL에 적재하는 게 목표예요.
현재 데이터 수집 단계까지 완료, 변환 로직 작업 중입니다.
이것만 있어도 Claude가 엉뚱한 방향으로 가는 걸 꽤 막을 수 있어요.
2. 폴더/파일 구조 요약
세션 새로 시작할 때마다 “폴더가 어떻게 생겼냐”고 다시 설명하는 게 정말 귀찮았거든요. 주요 폴더 구조랑 각 파일이 뭐 하는 건지 간단하게 적어두면 돼요.
전체를 다 적을 필요는 없고, 핵심 파일 위주로요. 너무 길게 쓰면 토큰만 잡아먹으니까 요점만 담는 게 포인트예요.
3. 코딩 원칙 (이게 진짜 핵심이었어요)
솔직히 말하면 이 섹션이 제일 효과가 컸어요.
처음에 Claude Code를 쓸 때 답답했던 게 있었어요. 제가 뭔가 물어보면 Claude가 일단 코드를 짜고 보는 거예요. 저는 아직 방향도 못 잡았는데 이미 50줄짜리 코드가 뚝 나와 있는 거죠. 그 코드가 제 의도랑 다르면 다시 설명하고, 또 코드 나오고… 이 반복이 생각보다 피로했어요.
그래서 코딩 원칙 섹션에 딱 두 줄을 넣었어요.
코딩 원칙
- 코드 작성 전에 관련 파일 먼저 읽고 파악하기
- 방향이 애매하면 바로 짜지 말고 먼저 질문하기
이 두 줄을 넣고 나서 확 달라졌어요. Claude가 먼저 관련 파일들을 열어보고, 모호한 부분이 있으면 “이 부분은 어떻게 할까요?”하고 물어보는 방식으로 바뀌었거든요. 같이 보고, 대화하고, 이해하고 넘어가니까 전체 프로젝트 흐름을 함께 파악하면서 갈 수 있었어요. 결과물의 품질도 올라가고, 토큰 낭비도 확 줄었어요.
4. 현재 작업 상태 및 다음 할 일
이게 있으면 세션 새로 켤 때 “어디까지 했더라”부터 다시 설명 안 해도 돼요. 작업할 때마다 이 부분만 업데이트해주면 돼요.
현재 상태
- 데이터 수집 모듈 완료
- 변환 로직 중 날짜 형식 처리 부분 작업 중
다음 할 일
- 날짜 파싱 함수 완성
- 단위 테스트 작성
핵심 한 줄 정리: 개요 + 구조 + 코딩 원칙 + 현재 상태, 이 네 가지가 CLAUDE.md의 뼈대예요
CLAUDE.md 잘 쓰는 실전 팁
쓰다 보면서 “이렇게 하면 더 좋겠다”고 느낀 것들도 공유할게요.
짧게 쓰는 게 진짜 중요해요. 처음엔 이것저것 다 적고 싶어서 엄청 길게 썼는데, 역효과가 나더라고요. CLAUDE.md도 결국 토큰을 잡아먹어요. 필요한 정보만 압축해서 담는 게 핵심이에요. 한 섹션에 5줄 이내를 목표로 해보세요.
너무 자주 업데이트하려고 하지 않아도 돼요. 프로젝트 구조가 크게 바뀌거나, 새로운 원칙이 생겼을 때만 수정해도 충분해요. 다만 ‘현재 상태’ 섹션은 작업 세션 끝낼 때마다 짧게 업데이트해주는 게 좋아요.
Claude한테 CLAUDE.md 초안을 맡길 수도 있어요. 처음 만들기 막막하면 현재 프로젝트 구조를 Claude한테 보여주고 “이걸 기반으로 CLAUDE.md 초안 써줘”라고 하면 돼요. 그걸 바탕으로 내 스타일에 맞게 고치는 게 훨씬 빠르더라고요.
실전 예시가 궁금하다면 이 GitHub 레포도 참고해보세요.
모호한 표현은 피해요. “코드를 잘 짜주세요” 같은 말보다는 “함수 하나당 하나의 역할만 담당하도록 작성하기” 처럼 구체적으로 쓸수록 Claude가 의도를 정확히 이해해요.
핵심 한 줄 정리: 짧고 구체적으로, 그리고 코딩 원칙만큼은 신경 써서 작성하기
마무리하며
CLAUDE.md 하나가 이렇게 큰 차이를 만들 줄은 처음엔 몰랐어요. 세션마다 맥락 날아가는 문제, 긴 세션에서 앞 내용 잊어버리는 문제, 이 두 가지가 동시에 해결됐거든요.
특히 코딩 원칙 섹션에 “방향 애매하면 먼저 물어보기” 두 줄을 넣은 것만으로도 Claude랑 일하는 방식 자체가 바뀌었어요. 혼자 코딩하는 게 아니라 같이 프로젝트를 파악해가면서 나아가는 느낌이랄까요.
비전공자로 데이터 엔지니어링 공부하다 보면 AI 툴을 얼마나 잘 활용하느냐가 진짜 중요하더라고요. CLAUDE.md는 그 활용법 중에서 진입장벽도 낮고 효과도 확실한 방법이라서, 아직 안 써보셨다면 지금 바로 프로젝트 폴더에 파일 하나 만들어보시는 걸 추천해요.
처음엔 세 줄이라도 괜찮아요. 쓰다 보면 자연스럽게 채워져요.
바이브코딩 자체가 처음이라면 이 튜토리얼부터 보는 것도 좋아요.