Claude Code의 진짜 출발점, CLAUDE.md
— AI에게 정체성과 규칙을 새기는 법
CLAUDE.md는 Claude Code가 매 세션 자동으로 읽는 단 하나의 파일이에요. '나는 누구인지, 어떻게 일하는지, 무엇을 기억하는지'를 한 번 적어두면 — 반복 설명이 사라지는 건 시작일 뿐이고, 매번 결과물의 형식이 같아지고, 빠뜨림·중복 같은 실수까지 줄어요. 매번 새로 가르치는 인턴이 아니라, 내 방식을 아는 동료가 되는 거예요.
그래서 뭐가 좋아지나 — 같은 요청, 달라지는 결과
말로만 들으면 추상적이니, 똑같은 요청에 AI가 어떻게 달라지는지 세 장면으로 볼게요. 왼쪽은 CLAUDE.md가 없을 때, 오른쪽은 딱 한 줄을 적어뒀을 때예요.
"네! 이번 분기 실적을 정리해 드리겠습니다 😊"로 시작해 길게 서술하고, 정작 핵심 숫자는 맨 아래 문단에 묻혀요. 내일 같은 걸 시키면 형식이 또 달라져서, 매번 손봐야 해요.
맨 위에 "TL;DR: 매출 전분기 대비 12% 성장, 영업이익률 3%p 개선" 한 줄, 이어서 항목별 표. 빈말 인사도 없어요. 매번 같은 형식이라 그대로 붙여 쓰면 돼요.
그럴듯한 초안을 줘요. 그런데 읽다 보면 내가 분명히 말한 '예산' 항목이 통째로 빠져 있어요. 내가 발견하고 "예산 빠졌어, 다시"라고 또 시켜야 해요.
초안 끝에 "요청하신 예산 항목이 누락돼 있어 5번 절에 추가했습니다"라고 스스로 밝히며 채워서 줘요. 빠뜨림이 나한테 오기 전에 걸러져요.
새 차트 코드를 처음부터 짜기 시작해요. 사실 지난주에 거의 똑같은 걸 만들어 뒀는데, AI는 그걸 모르니 중복으로 또 만들고 스타일도 제각각이 돼요.
먼저 폴더를 뒤져보고 "기존 analytics 폴더에 같은 차트가 있어 그걸 재사용했습니다"라고 알려줘요. 중복도, 스타일이 갈리는 일도 없어요.
눈치챘겠지만, 오른쪽을 만든 건 거창한 설정이 아니라 각각 딱 한 줄의 규칙이에요. 그 한 줄들을 어디에 어떻게 적는지가 이 글의 전부예요.
CLAUDE.md란 무엇인가
CLAUDE.md는 작업 폴더(루트)에 두는 마크다운 파일이에요. 특별한 건 매 세션이 시작될 때 Claude Code가 자동으로 읽어들인다는 점이에요. 즉 내가 매번 붙여넣지 않아도, 여기 적힌 내용이 항상 대화의 배경 지식으로 깔려요.
그래서 CLAUDE.md는 '프롬프트 모음'이 아니라 단일 진실(single source of truth)에 가까워요. AI가 나를 어떻게 대해야 하는지, 일을 어떤 절차로 처리해야 하는지, 과거에 어떤 결정을 내렸는지를 한곳에 모아두는 거예요. 잘 쓴 CLAUDE.md 하나가 프롬프트 수십 개보다 강력한 이유죠.
PART A — 나는 누구인가 (정체성)
가장 먼저 AI에게 '내가 누구를 대하고 있는지'를 알려줘요. 직무와 관점, 말투, 그리고 절대 어기면 안 되는 가치예요. 한 번 잘 정하면 거의 바뀌지 않는 부분이에요.
# A. 정체성
- 나는 로그·마케팅 데이터를 다루는 분석가다. 지표를 인사이트로 풀어 설명한다.
- 말투는 자연스러운 구어체. "좋은 질문이네요" 같은 빈말·과한 사과 금지.
- 모르면 모른다고 한다. 숫자·사실은 지어내지 않는다.그런데 이걸 직접 타이핑할 필요는 없어요. Claude Code에게 시키면 알아서 만들어줘요.
[ ] 부분만 내 상황으로 바꿔 말하면, 위 같은 형식으로 알아서 적어줘요.
PART B — 나는 어떻게 일하는가 (운영 절차)
여기가 결과물의 품질을 가르는 핵심이에요. 일을 처리하는 절차를 규칙으로 박아두는 것이에요. 효과가 가장 큰 두 가지부터요.
- 검토 게이트 — "결과를 내놓기 전에, 처음 목표를 실제로 충족했는지·빠진 요구는 없는지 스스로 점검하고, 통과한 것만 전달한다." (장면 2가 이 한 줄의 효과예요)
- 탐색 우선 — "새로 만들기 전에 기존 폴더를 먼저 뒤져 재사용할 게 있는지 본다." (장면 3이 이 한 줄의 효과예요)
# B. 운영 절차
- 보고는 결론 먼저 → 근거. 비교는 표로.
- 추정엔 "추정"이라 쓰고 가정을 1줄로 밝힌다.
- 검토 게이트: 결과를 주기 전 ①목표 충족 ②빠진 요구를 스스로 점검한다.
- 탐색 우선: 새로 만들기 전에 기존 파일부터 찾는다.PART C — 나는 무엇을 기억하는가 (누적 기억)
마지막은 시간이 지나며 쌓이는 기억이에요. 반복해서 내리는 결정, 한 번 겪은 시행착오, 자주 바뀌는 맥락 같은 거예요. 핵심은 "적어두지 않은 건 사라진다"예요. 머릿속 결정은 다음 세션으로 이어지지 않거든요.
# C. 누적 기억
- 외부 발송 문서는 항상 검수 후 보낸다.
- A 클라이언트는 보고를 짧게 선호한다.
- (앞으로 정한 규칙·결정을 여기에 한 줄씩 쌓는다)이 파트의 진짜 힘은 대화하다가 그 자리에서 쌓을 수 있다는 거예요. 뭔가 정해질 때마다 이렇게 한마디만 하면 돼요.
그러면 AI가 직접 기록해요. 다음 세션에 같은 상황이 오면 그 결정을 그대로 따라요.
나쁜 예 vs 좋은 예
같은 내용도 어떻게 적느냐에 따라 효과가 달라요. 핵심은 모호한 형용사 대신 구체적인 규칙이에요.
따라 하기 — 백지에서 한 번에 만들기
지금까지 PART별로 뜯어봤지만, 사실 골격은 한 번에 만들 수 있어요. 작업할 폴더에서 Claude Code를 열고, 아래 문장의 [ ]만 내 상황으로 바꿔 입력해 보세요. 직접 파일을 만들 필요도 없어요.
그러면 아래 같은 골격이 만들어지고 저장까지 끝나요. 처음부터 완벽할 필요는 없어요 — 쓰다가 "이건 매번 설명하네" 싶은 걸 한 줄씩 추가해 달라고만 하면 CLAUDE.md가 알아서 자라요.
# CLAUDE.md — 내 AI의 운영 지침
## A. 정체성 (나는 누구인가)
- 나는 로그·마케팅 데이터를 다루는 분석가다. # 직무·관점
- 결과는 인사이트 중심으로, 결론 먼저 정리한다.
- 말투: 자연스러운 구어체. 빈말 인사·과한 사과 금지.
## B. 운영 절차 (어떻게 일하는가)
- 결론 먼저 → 근거. 추정엔 "추정" 표기 + 가정 1줄.
- 검토 게이트: 전달 전 ①목표 충족 ②근거 ③빠진 요구를
스스로 점검하고, 통과한 것만 내놓는다.
- 탐색 우선: 새로 만들기 전에 기존 파일을 먼저 찾는다.
## C. 누적 기억 (무엇을 기억하는가)
- (반복되는 결정·겪은 시행착오를 한 줄씩 여기 쌓는다)
- 예) 외부 발송 문서는 항상 검수 후 전달하기로 함.참고로 위 박스의 #이나 - 같은 기호에 겁먹지 않아도 돼요. 코드가 아니라 그냥 'AI가 시킨 대로 만들어 놓은 결과'예요. 우리는 읽고 "여기 이 줄 바꿔줘"라고 말만 하면 되거든요.
비개발 실무자일수록 CLAUDE.md의 가치가 더 커요. 개발자는 코드로 규칙을 강제하지만, 우리는 '말로 일을 시키는' 사람이거든요. 그 말의 기준을 파일 하나에 박아두는 순간, AI는 매번 새로 가르치는 인턴이 아니라 내 방식을 아는 동료에 가까워져요.
한 가지만 당부하면 — CLAUDE.md를 처음부터 길게 쓰려 하지 마세요. 완벽한 30KB 문서를 한 번에 만드는 것보다, 5줄로 시작해 매주 한 줄씩 쌓는 쪽이 훨씬 잘 작동해요. 살아 있는 문서여야 하거든요.
자주 묻는 것
CLAUDE.md는 어디에 둬야 자동으로 읽히나요?
CLAUDE.md라는 이름으로 두면 그 폴더에서 Claude Code를 열 때 자동으로 읽혀요. 여러 사람이 쓰는 공통 규칙은 루트에, 개인 설정은 별도로 나눌 수도 있어요.