CLAUDE.md는 어떤 파일인가: 같은 설명을 매번 다시 하지 않기 위한 안내문

Claude Code로 일을 시키다 보면 같은 말을 되풀이하게 됩니다. 「답은 한국어로 해 줘」「원본 파일은 고치지 마」「숫자는 표로 정리해 줘」. 어제 분명히 말했는데 오늘 새 대화를 열면 다시 말해야 합니다.

Claude Code는 대화를 새로 열 때마다 백지에서 시작하기 때문입니다. 앞 대화에서 한 약속은 다음 대화로 넘어가지 않습니다.

CLAUDE.md는 이 문제를 푸는 파일입니다. 매번 말로 하던 것을 파일에 적어 두면, Claude가 대화를 시작할 때마다 그 파일을 먼저 읽습니다.

CLAUDE.md는 무엇인가

세 가지로 정리할 수 있습니다.

보통의 글 파일입니다. 이름이 CLAUDE.md인 마크다운 파일이고, 메모장으로도 열고 고칠 수 있습니다. 특별한 문법이 없습니다.
내가 씁니다. Claude에게 바라는 것을 내 말로 적습니다.
Claude가 대화를 시작할 때마다 읽습니다. 따로 「읽어 줘」라고 하지 않아도 됩니다.

새로 온 동료에게 건네는 업무 안내문과 같습니다. 「우리 팀은 보고서를 이렇게 씁니다」「이 폴더는 건드리지 마세요」를 적어 둔 한 장짜리 문서입니다. 다만 이 동료는 매일 아침 기억을 잃고 출근하기 때문에, 그 안내문을 매일 아침 다시 읽습니다.

대화가 시작될 때

CLAUDE.md가 없을 때

1새 대화를 연다

2읽을 안내문이 없다

3내가 첫 요청을 한다

4Claude가 백지에서 답한다

CLAUDE.md가 있을 때

1새 대화를 연다

2Claude가 CLAUDE.md를 읽는다

3내가 첫 요청을 한다

4Claude가 안내문을 아는 상태로 답한다

달라지는 것은 둘째 칸 하나입니다.

무엇이 달라지나

같은 요청을 CLAUDE.md가 없을 때와 있을 때로 견주어 보겠습니다. 광고 성과 파일을 정리해 달라고 시키는 경우입니다.

	CLAUDE.md가 없을 때	CLAUDE.md가 있을 때
내가 치는 말	「지난주 광고 성과 정리해 줘. 한국어로, 표로, 원본 엑셀은 고치지 말고, 금액은 원 단위로, 결과는 reports 폴더에 저장해 줘」	「지난주 광고 성과 정리해 줘」
다음 날	같은 말을 처음부터 다시	「이번 주 것도 정리해 줘」

오른쪽이 되는 이유는 「한국어로, 표로, 원본은 고치지 말고, 금액은 원 단위로, reports 폴더에」가 CLAUDE.md에 이미 적혀 있기 때문입니다.

무엇을 적나

기준은 하나입니다. 적어 두지 않으면 매번 다시 설명하게 되는 것을 적습니다.

이럴 때 한 줄씩 더하면 됩니다.

Claude가 같은 실수를 두 번째로 했을 때
지난 대화에서 친 고침 말을 이번 대화에서 또 치고 있을 때
새로 온 동료에게도 똑같이 알려 줘야 하는 내용일 때

적어 둘 만한 것은 이런 것들입니다.

말투와 꼴: 답하는 언어, 표를 쓸지, 숫자 단위
폴더 안내: 어느 폴더에 무엇이 있는지, 결과물을 어디에 저장하는지
지킬 것: 고치면 안 되는 파일, 하기 전에 물어봐야 하는 일
일의 배경: 이 일이 무엇이고 누가 읽을 결과물인지

반대로 적지 않는 편이 좋은 것도 있습니다.

이번 한 번만 필요한 지시. 그냥 대화에서 말하면 됩니다.
단계가 많은 긴 절차. 이런 것은 「스킬」이라는 다른 자리에 두는 편이 맞습니다.

짧은 본보기

광고 성과를 정리하는 워크스페이스에 둔다고 하면 이 정도면 충분합니다.

# 광고 성과 정리

## 답하는 방식
- 답은 한국어로 한다.
- 숫자를 견줄 때는 표로 보여 준다.
- 금액은 원 단위로 적고 천 단위마다 쉼표를 넣는다.

## 폴더
- raw/ 광고 매체에서 내려받은 원본. 고치지 않는다.
- reports/ 정리한 결과를 여기에 저장한다.

## 지킬 것
- 원본에 없는 숫자를 지어내지 않는다. 없으면 「없음」이라고 적는다.
- 파일을 지우거나 옮기기 전에 먼저 묻는다.

제목 줄(#, ##)과 목록(-)으로 나눠 적었습니다. 한 문단에 길게 이어 쓰는 것보다 이렇게 묶어 적는 편이 Claude도 따르기 쉽습니다.

잘 따르게 쓰는 법

구체적으로 적습니다. 지켰는지 아닌지 가려낼 수 있을 만큼 적어야 합니다.

모호한 말	구체적인 말
보고서는 보기 좋게	보고서는 맨 위에 세 줄 요약, 그 아래에 표
파일을 잘 정리해 줘	결과는 `reports/` 폴더에 `날짜_이름` 꼴로 저장
숫자를 조심해서	숫자는 원본 파일에서 다시 확인하고 적는다

짧게 둡니다. 공식 문서는 파일 하나를 200줄 아래로 두기를 권합니다. 길어질수록 대화마다 읽는 양이 늘고, 정작 중요한 줄을 덜 따르게 됩니다.

서로 어긋나지 않게 합니다. 한쪽에는 「표로 정리」, 다른 쪽에는 「글로 풀어서」라고 적혀 있으면 Claude가 어느 쪽을 따를지 알 수 없습니다. 가끔 처음부터 읽어 보고 낡은 줄을 지웁니다.

알아 둘 한계

CLAUDE.md는 부탁이지 잠금장치가 아닙니다. Claude는 적힌 내용을 읽고 따르려 하지만, 반드시 지킨다는 보장은 없습니다. 모호하게 적었거나 서로 어긋나는 줄이 있으면 더 그렇습니다.

그래서 「이 파일은 절대 지우면 안 된다」처럼 어겨지면 곤란한 것은 CLAUDE.md에만 맡기지 않습니다. Claude Code의 설정에서 그 행동 자체를 막아 두는 방법이 따로 있습니다. CLAUDE.md는 일하는 방식을 알려 주는 곳이고, 막는 일은 설정이 맡습니다.

만드는 법

VS Code에서 연 폴더(워크스페이스)에 CLAUDE.md라는 이름으로 새 파일을 만듭니다. 폴더를 오른쪽 클릭해 「새 파일」을 고르면 됩니다. 이 글에서 「워크스페이스」라고 부르는 것이 이 폴더입니다. Claude Code의 화면과 문서에서는 project라고 부릅니다.
위 본보기처럼 적고 저장합니다.
새 대화를 엽니다. 이미 열려 있던 대화가 아니라 새로 연 대화부터 읽힙니다.

Claude에게 시켜도 됩니다. 대화하다가 「방금 말한 것을 CLAUDE.md에 적어 줘」라고 하면 Claude가 파일에 더해 줍니다. 같은 말을 두 번 하고 있다는 것을 알아챈 그 자리에서 바로 적어 두는 것이 가장 쉽습니다.

어디에 두느냐에 따라 적용 범위가 달라집니다

위에서는 워크스페이스에 두는 경우만 다뤘습니다. 둘 수 있는 곳이 하나 더 있습니다.

둔 곳	적용되는 곳	부르는 말
워크스페이스의 `CLAUDE.md`	이 워크스페이스에서만	워크스페이스 적용
개인 폴더의 `CLAUDE.md`	내 모든 워크스페이스에서	전역 적용

개인 폴더의 자리는 C:\Users\<사용자 이름>\.claude\CLAUDE.md 한 곳으로 정해져 있습니다. Claude Code 프로그램을 어디에 설치했는지와는 상관이 없습니다.

「답은 한국어로」처럼 어디서나 같은 것은 개인 폴더에, 「이 폴더의 원본은 고치지 않는다」처럼 그 일에만 해당하는 것은 워크스페이스에 둡니다.

어느 쪽이든 고친 뒤에는 새 대화를 열어야 반영됩니다.

Claude에 바깥 서비스를 붙이는 이야기는 「MCP는 무엇인가」 글에서 이어집니다.

참고한 문서

Claude Code 문서, How Claude remembers your project