muaco Tech Note

Claude Codecode.claude.com

Claude Code CLAUDE.md 사용법프로젝트 규칙을 한 번만 적어 두기

CLAUDE.md를 어디에 두고 무엇을 적어야 하는지 아시면, Claude Code에 같은 설명을 매번 다시 하지 않으셔도 됩니다.

안녕하세요, muaco입니다.

새로 온 아르바이트생에게 가게 규칙을 매일 아침 처음부터 설명한다고 생각해 보세요. 금방 지치지 않을까요? 그래서 보통은 계산대 옆에 규칙을 적은 종이를 붙여 둡니다.

출근한 사람은 그 종이부터 읽고 일을 시작합니다. Claude Code에서 그 종이 노릇을 하는 파일, 바로 CLAUDE.md입니다.

이 글로 할 수 있는 일

이 글을 따라 하면 프로젝트 폴더에 CLAUDE.md 파일을 하나 만들고, 거기 적은 규칙을 Claude가 매번 읽고 시작하게 할 수 있습니다. 대화를 새로 열 때마다 Claude Code는 앞선 대화를 기억하지 못한 채 시작하기 때문입니다.

파일을 어느 폴더에 둬야 읽히는지, 무엇을 적고 무엇을 빼야 하는지도 함께 살펴봅니다. 마지막으로 파일이 제대로 읽혔는지 확인하는 방법까지 다룹니다.

미리 갖출 준비물

여기서 막히면 뒤를 다 읽어도 소용이 없습니다. 먼저 확인해 보세요.

  • 계정: Claude 구독(Pro, Max, Team, Enterprise)이나 Claude Console 계정이 필요합니다. 회사가 클라우드 업체를 통해 쓰고 있다면 그 계정도 됩니다.
  • Claude Code 설치: 터미널(글자로 명령을 쳐서 컴퓨터를 다루는 창)에 claude --version을 입력해 보세요. 숫자 뒤에 (Claude Code)가 붙어 나오면 설치된 상태입니다.
  • 설치가 안 돼 있다면: macOS, Linux, WSL에서는 curl -fsSL https://claude.ai/install.sh | bash, Windows PowerShell에서는 irm https://claude.ai/install.ps1 | iex로 설치합니다.
  • 작업할 폴더 하나: 규칙을 적용할 프로젝트 폴더가 있어야 합니다. 꼭 코드가 아니어도 됩니다. 보고서를 모아 두는 폴더라도 괜찮습니다.

2026년 9월 기준 공식 문서를 보고 쓴 글입니다. 버전마다 달라지는 동작은 해당 자리에 버전을 따로 적었습니다.

파일을 어디에 두면 읽힐까

규칙 종이를 어디에 붙이느냐에 따라 읽는 사람이 달라집니다. 본사 게시판에 붙이면 모든 지점이 보고, 우리 가게 계산대에 붙이면 우리 가게 직원만 봅니다. CLAUDE.md도 마찬가지입니다.

위치적용 범위누구와 함께 쓰나
~/.claude/CLAUDE.md내 컴퓨터의 모든 프로젝트나만
./CLAUDE.md 또는 ./.claude/CLAUDE.md이 프로젝트깃으로 공유하는 팀원 모두
./CLAUDE.local.md이 프로젝트나만 (.gitignore에 추가)

깃은 팀이 함께 쓰는 공유 서랍 같은 도구입니다. 누가 언제 무엇을 고쳤는지 기록을 남기면서 파일을 팀원과 주고받게 해 줍니다.

IT 부서 차원에서 회사가 모든 사람에게 거는 파일도 있습니다. Linux와 WSL은 /etc/claude-code/CLAUDE.md, macOS는 /Library/Application Support/ClaudeCode/CLAUDE.md, Windows는 C:\Program Files\ClaudeCode\CLAUDE.md입니다. 이 파일은 개인 설정으로 뺄 수 없다는 점도 기억해 두세요.

읽는 순서도 알아 두면 좋습니다. 실행한 폴더와 그 위쪽 폴더들에 있는 CLAUDE.md를 Claude Code는 전부 읽습니다. 서로 덮어쓰지 않고 이어 붙이며, 실행한 폴더에 가까운 파일이 가장 나중에 읽힙니다.

그렇다면 아래쪽 하위 폴더의 CLAUDE.md는 어떨까요? 처음에는 읽지 않습니다. Claude가 그 폴더의 파일을 열 때 함께 읽습니다.

따라 하기: 규칙 파일 만들기

준비

따라 하기
  1. 터미널에서 cd /path/to/your/project로 프로젝트 폴더에 들어간 뒤 claude를 입력합니다. 경로 부분은 내 폴더 주소로 바꾸세요. 설치 후 처음 켜면 로그인 안내가 먼저 나오니, 화면 안내를 따라 계정으로 로그인합니다. 화면 위쪽에 버전, 모델, 작업 폴더가 보이면 제대로 켜진 상태입니다.
  2. 입력창에 /init을 입력하세요. 그러면 Claude가 폴더를 훑어보고 CLAUDE.md 초안을 만들어 줍니다. 폴더에 CLAUDE.md가 새로 생겼다면 성공. 이미 파일이 있을 때는 덮어쓰지 않고 고칠 점만 제안합니다.

규칙 적기

따라 하기
  1. /memory를 입력합니다. 내 컴퓨터 전체용, 프로젝트용 파일 위치가 목록으로 나옵니다. 하나를 고르면 편집기로 열리고, 아직 없는 파일을 고르면 새로 만든 뒤 열어 줍니다.
  2. 초안 아래에는 내가 매번 반복하던 설명을 옮겨 적습니다. 제목과 글머리표로 묶어 두면 사람처럼 Claude도 훑어 읽기 쉽습니다. 아래 예시처럼 짧고 확인할 수 있게 써 보세요.
  3. 나만 쓰는 메모(내 테스트용 주소 같은)는 같은 폴더의 CLAUDE.local.md에 적고, 이 파일 이름을 .gitignore에 넣으세요. 그래야 팀 저장소에 올라가지 않습니다.
# 보고서 폴더 규칙

## 저장 위치
- 완성본은 reports/ 폴더에 저장해요
- 파일 이름은 2026-09-13-주제.md 형식으로 해요

## 작업 순서
- 초안은 drafts/ 폴더에서 쓰고 검토가 끝나면 옮겨요
- 들여쓰기는 공백 2칸으로 해요

확인

따라 하기
  1. 파일을 저장했다면 /exit로 나갔다가 claude로 다시 켜 두는 편이 확실합니다. 문서는 대화를 시작할 때 CLAUDE.md를 읽는다고 설명합니다. 따라서 켜 둔 대화에는 고친 내용이 바로 반영되지 않을 수 있습니다.
  2. /context를 입력합니다. Memory files 목록에 방금 만든 파일 이름이 있다면 Claude가 읽은 상태입니다. 목록에 없으면 Claude는 그 파일을 보지 못합니다.

적을 내용과 뺄 내용

문서가 권하는 기준은 간단합니다. 내가 또 설명하게 될 말을 적으세요. Claude가 같은 실수를 두 번 할 때, 지난번에 친 정정을 이번에 또 치고 있을 때, 새로 온 동료에게도 똑같이 알려 줘야 할 사정일 때가 바로 적을 때입니다.

  • 적을 내용: 빌드·테스트 명령, 이름 짓는 규칙, 폴더를 어떻게 쓰기로 했는지(예: 완성본은 reports/에 둡니다), "항상 이렇게 합니다" 같은 약속, 함정과 그 이유.
  • 뺄 내용: 여러 단계로 된 긴 절차나 프로젝트 한 구석에만 해당하는 규칙. 이런 내용은 스킬이나 .claude/rules/ 폴더로 옮기라고 문서가 권합니다.
  • 뺄 내용: Claude가 파일만 봐도 알 수 있는 정보. 폴더 목록, 설치된 부품 목록, 구조 소개가 여기에 들어갑니다.

둘 다 폴더 이야기라 헷갈릴 수 있습니다. 기준은 파일을 열어 봐서 알 수 있느냐입니다.

어떤 폴더가 있는지는 Claude가 직접 보면 되니 뺍니다. 반면 폴더를 어떻게 쓰기로 정했는지는 봐도 모르니 적어 두세요.

길이는 파일 하나에 200줄 아래가 목표입니다. 길수록 대화 공간을 많이 차지하고 규칙도 덜 지킵니다.

표현은 확인할 수 있게 쓰세요. "코드를 깔끔하게"보다 "들여쓰기는 공백 2칸"이 잘 먹힙니다.

하나 더 알아 둘 점이 있습니다. CLAUDE.md는 부탁일 뿐, 잠금장치가 아니라는 점. 절대 하면 안 되는 동작을 막아야 한다면 훅(정해진 순간에 자동으로 실행되는 명령)으로 걸라고 문서가 안내합니다.

막히기 쉬운 세 군데

규칙을 적었는데 따르지 않습니다

여기서 다들 한 번쯤 멈칫합니다. 먼저 /context의 Memory files에 파일이 떠 있는지 보세요.

목록에 없다면 위치가 틀린 경우가 많습니다. 하위 폴더에 둔 파일은 시작할 때 읽히지 않는다는 점을 떠올려 보세요.

목록에 있는데도 따르지 않는다면 문장이 모호하지 않은지 살펴봐야 합니다. 다른 CLAUDE.md에 반대되는 규칙이 있는지도 찾아보세요. 두 규칙이 부딪히면 Claude가 아무거나 고를 수 있기 때문입니다.

"기억해 줘"라고 했는데 CLAUDE.md에 없습니다

대화 중에 "기억해 줘"라고 하면 Claude는 CLAUDE.md가 아니라 자동 메모리에 적습니다. 자동 메모리는 Claude가 스스로 쓰는 노트로, ~/.claude/projects/<project>/memory/에 저장됩니다.

CLAUDE.md에 넣고 싶다면 "CLAUDE.md에 추가해 줘"라고 분명히 말하거나 /memory로 직접 열어 고치세요. 참고로 자동 메모리는 목차 파일 MEMORY.md의 앞 200줄 또는 25KB까지만 시작할 때 읽힙니다.

다른 도구용 AGENTS.md가 이미 있습니다

Claude Code는 AGENTS.md를 읽지 않습니다. 이럴 때는 CLAUDE.md를 만들고 첫 줄에 @AGENTS.md를 적어 보세요. 같은 내용을 두 번 쓰지 않고 불러올 수 있습니다.

@경로로 다른 파일을 끌어오는 이 방식은 최대 네 단계까지 이어집니다. 다만 불러온 파일도 시작할 때 전부 읽히니 길이를 줄이는 효과는 없습니다.

여기서 더 나아가려면

규칙이 늘어나면 .claude/rules/ 폴더에 주제별로 파일을 나눠 보세요. 파일 머리에 paths를 달면 특정 파일을 다룰 때만 그 규칙이 읽혀 대화 공간을 아낄 수 있습니다.

파일이 너무 커졌다면 어떻게 할까요? /doctor가 줄일 부분을 제안해 줍니다(v2.1.206 이상).

이상으로 글 마치겠습니다.

출처

#CLAUDE.md#Claude Code#메모리#프로젝트 규칙#자동 메모리#AI 코딩 도구#사용법

같은 분류의 글