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

안녕하세요, muaco입니다.

새로 온 아르바이트생에게 가게 규칙을 매일 아침 처음부터 설명한다고 생각해 봐요. 금방 지치겠죠. 그래서 보통은 계산대 옆에 규칙을 적은 종이를 붙여 둬요. 출근한 사람은 그 종이부터 읽고 일을 시작해요. Claude Code에서 그 종이 노릇을 하는 파일이 CLAUDE.md예요.

이 글로 할 수 있는 일

Claude Code는 대화를 새로 열 때마다 앞선 대화를 기억하지 못한 채 시작해요. 이 글을 따라 하면 프로젝트 폴더에 CLAUDE.md 파일을 하나 만들고 거기에 적은 규칙을 Claude가 매번 읽고 시작하게 할 수 있어요. 파일을 어느 폴더에 둬야 읽히는지, 무엇을 적고 무엇을 빼야 하는지도 함께 봐요. 마지막에는 파일이 제대로 읽혔는지 확인하는 방법까지 다뤄요.

미리 갖출 준비물

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

• 계정: 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도 똑같아요.

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

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

읽는 순서도 알아 두면 좋아요. Claude Code는 실행한 폴더와 그 위쪽 폴더들에 있는 CLAUDE.md를 전부 읽어요. 서로 덮어쓰지 않고 이어 붙이는데, 실행한 폴더에 가까운 파일이 가장 나중에 읽혀요. 아래쪽 하위 폴더에 있는 CLAUDE.md는 처음엔 읽지 않아요. Claude가 그 폴더의 파일을 열 때 함께 읽어요.

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

준비

규칙 적기

# 보고서 폴더 규칙

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

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

확인

적을 내용과 뺄 내용

문서가 권하는 기준은 간단해요. 내가 또 설명하게 될 말을 적어요. 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 이상).

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

출처

• How Claude remembers your project (Claude Code 공식 문서)
• Quickstart (Claude Code 공식 문서)