클로드 코드 CLAUDE.md 사용법, 매번 설명 줄이는 파일

연휴 마지막 날, 내일 다시 열 프로젝트가 벌써 부담스러운가요?

클로드 코드에 같은 규칙을 매번 설명하지 않으려면 프로젝트 안에 짧은 안내 파일을 둘 수 있습니다. 한 번 적어 둔 기준을 대화를 시작할 때마다 함께 읽는 방식이죠.

핵심 내용

CLAUDE.md는 클로드 코드가 프로젝트 규칙, 명령, 폴더 구조를 계속 참고하게 하는 마크다운 파일입니다.
프로젝트 공통 규칙은 ./CLAUDE.md 또는 ./.claude/CLAUDE.md에 두고, 개인 메모는 CLAUDE.local.md로 나눌 수 있습니다.
지침은 짧고 구체적으로 적어야 잘 지켜집니다. ‘잘 정리해 주세요’보다 들여쓰기, 테스트 명령, 파일 위치를 분명히 적는 편이 낫습니다.
규칙이 길어지거나 일부 파일에만 필요하다면 .claude/rules/ 아래 파일로 나누고, 필요하면 경로 조건을 붙일 수 있습니다.
/context로 읽힌 메모리 파일을 확인하고, /doctor prompt-audit으로 오래됐거나 충돌하는 지침을 점검할 수 있습니다.

왜 같은 설명을 또 해야 할까

클로드 코드에 작업을 맡길 때마다 “이 프로젝트는 이렇게 테스트해요”, “이 폴더에 파일을 넣어 주세요”라고 다시 입력한 적 있으시죠? 짧은 요청도 쌓이면 대화가 길어집니다. 빠뜨린 규칙 탓에 결과를 다시 고쳐야 하는 일도 생기고요.

CLAUDE.md는 이런 반복 설명을 프로젝트와 함께 보관하는 안내문입니다. 클로드 코드는 대화를 시작할 때 이 파일을 읽고, 프로젝트의 빌드·테스트 명령이나 이름 짓는 방식, 폴더 배치처럼 계속 필요한 정보를 참고합니다. 기존에 AGENTS.md를 쓰고 있다면 그 파일도 CLAUDE.md와 함께, 또는 단독으로 읽을 수 있습니다.

다만 이 파일이 절대적인 차단 장치는 아닙니다. 클로드 코드가 작업할 때 참고하는 문맥에 가깝죠. “알아서 잘해 주세요”처럼 범위가 넓은 문장보다는 확인할 수 있는 기준을 적는 편이 좋습니다. 예를 들어 들여쓰기 칸 수나 실행할 테스트 명령을 쓰면, 결과가 맞는지도 판단하기 쉽습니다.

같은 실수를 두 번째로 반복했을 때가 파일에 한 줄을 더할 때입니다. 코드 검토에서 계속 나오는 지적이나 지난 대화에서 다시 설명했던 배경도 후보가 됩니다. 내일 프로젝트를 열기 전에 자주 하는 설명 세 가지만 골라 적어 두면 시작이 한결 가벼워집니다.

💡 꿀팁 · 처음에는 ‘항상 지킬 규칙’ 세 줄만 적고, 같은 요청을 다시 하게 될 때 한 줄씩 보태세요.

CLAUDE.md는 어디에 만들까

팀이 함께 보는 기준과 나만의 습관을 한 파일에 섞으면 곤란할 수 있습니다. 팀원에게 필요한 테스트 명령은 공유해야 하지만, 개인 작업 방식까지 프로젝트 파일에 넣을 이유는 없을 수 있거든요.

프로젝트 전체에 적용할 내용은 프로젝트 최상위의 ./CLAUDE.md 또는 ./.claude/CLAUDE.md에 둡니다. 여기에 빌드와 테스트 명령, 코딩 기준, 구조상 결정된 원칙, 이름 규칙, 공통 작업 흐름을 기록합니다. 이 파일은 프로젝트와 함께 공유될 수 있으니 개인 취향보다 팀의 공통 약속에 집중하는 편이 좋습니다.

개인 메모는 CLAUDE.local.md에 따로 둘 수 있습니다. 이 파일도 CLAUDE.md와 함께 읽히지만, 커밋되지 않도록 .gitignore에 넣는 방법이 안내돼 있습니다. 개인 파일을 공유 규칙과 분리하면 팀 문서가 불필요하게 복잡해지는 일을 줄일 수 있죠.

현재 작업 폴더와 그 위쪽 폴더에 있는 CLAUDE.md, CLAUDE.local.md도 함께 읽힙니다. 작업 폴더에 가까운 파일 내용이 뒤에 들어오며, 같은 위치에서는 CLAUDE.local.md가 CLAUDE.md 다음에 읽힙니다. 파일을 만들었는데 적용되는지 모르겠다면 대화에서 /context를 실행한 뒤 Memory files 목록을 확인하세요.

💡 꿀팁 · 팀 공통 규칙은 ./CLAUDE.md에, 공개하고 싶지 않은 개인 메모는 CLAUDE.local.md에 나눠 두세요.

클로드 코드 CLAUDE.md는 어떻게 쓸까

처음 파일을 열면 길고 근사한 개발 문서를 써야 할 것처럼 느껴질 수 있습니다. 하지만 이 파일은 설명을 많이 담는 곳이라기보다, 클로드 코드가 매번 기억해야 할 짧은 기준을 두는 곳에 가깝습니다. 파일 하나당 200줄 이하를 목표로 하라는 안내도 있습니다.

마크다운 제목과 글머리표로 관련 규칙을 묶어 보세요. ‘테스트’, ‘파일 위치’, ‘작성 규칙’처럼 제목을 나누면 긴 문단보다 기준이 선명해집니다. 서로 반대되는 지시가 섞이면 클로드 코드가 어느 하나를 임의로 따를 수 있으니, 오래된 내용은 지우거나 고쳐야 합니다.

아래처럼 실제로 확인할 수 있는 한 문장으로 시작하면 됩니다. 프로젝트마다 명령과 폴더 이름은 다르니 예시는 현재 프로젝트의 사실에 맞춰 바꿔 넣으세요. 존재하지 않는 명령을 적어 두면 오히려 혼란만 커집니다.

“커밋하기 전에 npm test를 실행하고 결과를 알려 주세요.”

“API 처리 파일은 src/api/handlers/ 폴더에 만드세요.”

“새 파일의 들여쓰기는 2칸을 사용하세요.”

‘코드를 적절히 정리해 주세요’처럼 기준이 없는 요청은 사람마다 해석이 달라집니다. 반면 명령, 위치, 숫자처럼 검증 가능한 정보는 결과를 확인하기도 쉽습니다. 개인적으로도 처음부터 많은 항목을 적기보다, 반복해서 불편했던 항목부터 쓰는 편이 부담이 적다고 봅니다.

💡 꿀팁 · ‘잘’, ‘적절히’ 같은 말이 보이면 실행 명령·폴더 경로·들여쓰기처럼 확인 가능한 기준으로 바꾸세요.

규칙이 길어지면 어떻게 나눌까

프로젝트가 커지면 모든 규칙을 CLAUDE.md 하나에 넣기 어렵습니다. 화면 관련 파일에만 적용할 기준이나 테스트할 때만 필요한 기준까지 매번 모두 읽히면, 정작 필요한 내용을 찾기 어려워질 수 있습니다.

이때는 .claude/rules/ 폴더에 마크다운 파일을 넣어 주제별로 나눌 수 있습니다. testing.md, api-design.md처럼 파일 이름만 봐도 내용을 알 수 있게 정하면 관리하기 좋습니다. 하위 폴더로 다시 정리할 수도 있습니다. 경로 조건이 없는 규칙은 대화 시작 시 읽히고, 조건을 둔 규칙은 해당 파일을 읽거나 쓰고 고칠 때 적용됩니다.

특정 범위에만 적용하려면 규칙 파일 맨 위 설정 영역에 paths를 적습니다. 이 설정에서 클로드 코드가 읽는 항목은 paths뿐입니다. 설정 형식이 잘못되면 경로 조건을 무시한 채 규칙이 읽힐 수 있으므로, 문제가 의심되면 claude --debug로 형식 오류를 확인할 수 있습니다.

규칙이 지켜지지 않거나 예전 지침이 남아 있다면 /doctor prompt-audit을 실행해 보세요. CLAUDE.md, CLAUDE.local.md, AGENTS.md와 관련 규칙 등을 검사해 오래된 모델 기준, 없는 파일이나 명령 참조, 서로 충돌하는 내용을 찾아 제안합니다. 보고서만 보여 줄 뿐, 적용을 요청하기 전에는 파일을 바꾸지 않습니다. 이 명령은 Claude Code v2.1.283 이상에서 사용할 수 있습니다.

💡 꿀팁 · 테스트 규칙처럼 주제가 뚜렷하면 .claude/rules/testing.md로 빼고, 점검 전에는 /doctor prompt-audit을 실행하세요.

그래서 나에게 무엇이 달라질까

CLAUDE.md를 쓰면 클로드 코드와의 대화가 프로젝트 설명부터 시작되는 일을 줄일 수 있습니다. 팀의 작업 기준은 파일로 남기고, 개인 메모는 따로 관리할 수 있어 새 작업이나 재개 작업에서 무엇을 먼저 말해야 할지 덜 고민하게 됩니다. 다만 짧게 쓰고 충돌 없이 유지해야 장점이 살아납니다.

내일 바로 써먹기

프로젝트 최상위에 ./CLAUDE.md를 만들고, 현재 쓰는 테스트 명령과 파일 배치 규칙을 각각 한 줄로 적어 보세요.
클로드 코드 대화에서 /context를 실행해 Memory files에 만든 파일이 보이는지 확인하세요.
기존 지침이 있다면 /doctor prompt-audit을 실행해 오래된 명령이나 충돌하는 규칙이 있는지 점검하세요.

용어사전

CLAUDE.md · 클로드 코드가 대화 시작 때 읽는 프로젝트 안내 파일입니다. 반복해서 알려 줄 규칙과 작업 맥락을 담습니다.
CLAUDE.local.md · 프로젝트 규칙과 분리해 개인 메모를 적는 파일입니다. 공유하지 않을 내용에 사용할 수 있습니다.
AGENTS.md · CLAUDE.md 대신 또는 함께 프로젝트 지침으로 읽을 수 있는 파일입니다.
paths · 규칙을 적용할 파일 위치나 종류를 정하는 설정 항목입니다. 맞는 파일을 작업할 때만 해당 규칙이 읽히게 할 수 있습니다.
frontmatter · 마크다운 파일 맨 위에서 설정을 적는 구역입니다. 규칙 파일에서는 paths 같은 조건을 넣는 데 씁니다.

출처

원문: Claude Code 공식 도움말 · https://code.claude.com/docs/ko/memory

함께 읽으면 좋은 글

오늘 글이 재미있으셨다면, 제 공간에도 한 번 놀러 와 주세요 🙂

제 인포크 링크 둘러보기