CLAUDE.md 지침 작성법 — AI 코딩 비서에게 사규 만들어주기

CLAUDE.md는 클로드코드(Claude Code)에게 매 세션마다 다시 설명하기 싫은 규칙을 한 번만 적어두는 지침 파일입니다.

2026년 7월 기준, 클로드코드는 새 대화를 시작할 때마다 이 파일을 먼저 읽고 작업에 반영합니다.

그래서 톤, 빌드 명령, 금지 사항, 자주 틀리는 부분을 여기 적어두면 매번 같은 지시를 반복하지 않아도 됩니다.

이 글을 읽으면 CLAUDE.md가 무엇이고 어디에 두는지, /init으로 어떻게 시작하는지, 잘 쓰는 구조와 흔한 실패 패턴까지 한 번에 정리됩니다.

클로드코드를 아직 설치하지 않았다면 먼저 설치 글(클로드코드 설치 가이드)을 보고 오는 편이 좋습니다.

CLAUDE.md는 클로드코드가 매 세션 시작 시 읽는 마크다운 지침 파일입니다. 내 컴퓨터 전체에 적용하려면 ~/.claude/CLAUDE.md, 특정 프로젝트에만·팀과 공유하려면 프로젝트 폴더의 CLAUDE.md에 둡니다. 단 강제 규칙이 아니라 강력한 안내문이라, 파일이 길거나 모호하면 무시될 수 있습니다.

CLAUDE.md는 왜 필요한가

클로드코드는 대화가 끝나면 방금 나눈 맥락을 대부분 잊습니다.

세션이 바뀔 때마다 컨텍스트 창이 새로 비워지기 때문입니다.

그래서 지난번에 알려준 규칙을 이번 세션에서 또 설명해야 하는 상황이 반복됩니다.

"우리 프로젝트는 pnpm을 쓴다", "커밋 전에 테스트를 돌려라" 같은 지시를 매번 다시 치는 셈이죠.

CLAUDE.md는 이 반복을 없애려고 만드는 파일입니다.

클로드코드 공식 문서는 이 파일을 "매번 다시 설명하게 될 내용을 적어두는 곳"이라고 설명합니다.

가장 쉬운 비유는 신입사원 온보딩 문서입니다.

새 팀원이 알아야 할 규칙, 도구, 관례를 한 문서에 정리해두면 매번 말로 설명하지 않아도 되는 것과 같습니다.

실제로 공식 문서도 "새 팀원이 생산적으로 일하려면 필요했을 맥락"을 CLAUDE.md에 넣으라고 안내합니다.

개인적으로는 '사규'보다 '온보딩 문서 + 팀 하우스룰'이 더 정확한 비유라고 봅니다.

사규는 어기면 처벌받는 강제 규칙이지만, CLAUDE.md는 뒤에서 설명하듯 100% 강제되지는 않으니까요.

CLAUDE.md는 정확히 무엇이고 언제 읽히나

CLAUDE.md는 사용자가 직접 작성하는 마크다운(.md) 파일입니다.

클로드코드는 새 세션을 시작할 때마다 이 파일 전문을 읽어 작업에 참고합니다.

여기서 꼭 짚어둘 뉘앙스가 하나 있습니다.

공식 문서에 따르면 CLAUDE.md 내용은 시스템 프롬프트가 아니라, 시스템 프롬프트 뒤에 오는 사용자 메시지로 전달됩니다.

쉽게 말해 "반드시 지켜야 하는 명령"이 아니라 "강력하게 권하는 안내문"에 가깝습니다.

클로드코드가 읽고 따르려 하지만, 지침이 모호하거나 서로 충돌하면 지키지 못할 수 있습니다.

공식 문서도 "엄격한 준수를 보장하지는 않는다"고 명시합니다.

그래서 반드시 실행돼야 하는 규칙은 CLAUDE.md가 아니라 Hook으로 만들라고 공식적으로 권합니다.

Hook은 특정 시점에 무조건 실행되는 자동 규칙이라, 온보딩 문서보다는 '사규 위반 시 자동 차단'에 가깝습니다.

파일은 어디에 두나 — 위치와 우선순위

CLAUDE.md는 하나가 아니라 여러 곳에 둘 수 있고, 클로드코드는 이들을 모두 읽어 이어 붙입니다.

비개발자라면 두 곳만 기억하면 충분합니다.

내 컴퓨터의 모든 프로젝트에 적용할 개인 규칙은 ~/.claude/CLAUDE.md(전역)에 둡니다.

특정 프로젝트에만 적용하고 팀과 공유할 규칙은 프로젝트 폴더의 CLAUDE.md(프로젝트)에 둡니다.

더 깊이 들어가면 아래 표처럼 네 단계로 나뉩니다.

범위	위치	쓰임새
관리 정책	macOS /Library/Application Support/ClaudeCode/CLAUDE.md (Windows는 C:\Program Files\ClaudeCode\CLAUDE.md)	조직 전체 지침 (회사 IT·DevOps가 관리)
전역(사용자)	~/.claude/CLAUDE.md	내 모든 프로젝트에 적용될 개인 취향
프로젝트	./CLAUDE.md 또는 ./.claude/CLAUDE.md	팀과 공유하는 프로젝트 지침 (소스컨트롤로 공유)
로컬	./CLAUDE.local.md (.gitignore 대상)	나만 쓰는 프로젝트별 취향 (테스트 데이터, 샌드박스 URL)

로드 순서는 넓은 범위에서 좁은 범위로 흐릅니다.

작업 폴더에 가까운 지침이 뒤에 놓여, 더 구체적인 규칙이 나중에 반영됩니다.

여기에 더해 클로드코드는 현재 작업 폴더에서 상위 폴더로 거슬러 올라가며 각 폴더의 CLAUDE.md를 수집합니다.

예를 들어 foo/bar/에서 실행하면 foo/bar/CLAUDE.md와 foo/CLAUDE.md를 모두 읽고, 덮어쓰지 않고 이어 붙입니다.

다만 하위 폴더의 CLAUDE.md는 시작할 때가 아니라, 클로드코드가 그 폴더 파일을 실제로 읽는 순간 그때그때 불러옵니다.

/init으로 시작하기

처음부터 CLAUDE.md를 손으로 다 채울 필요는 없습니다.

클로드코드에는 초안을 자동으로 만들어주는 /init 명령이 있습니다.

프로젝트 폴더에서 클로드코드를 켜고 아래처럼 입력하면 됩니다.

/init

/init은 코드베이스를 분석해 빌드 시스템, 테스트 프레임워크, 코드 패턴을 감지합니다.

그렇게 파악한 내용을 바탕으로 CLAUDE.md 시작본을 자동으로 만들어줍니다.

이미 CLAUDE.md가 있으면 덮어쓰지 않고, 개선안을 제안하는 방식으로 동작합니다.

공식 문서는 "일단 /init으로 시작본을 만들고, 시간을 두고 다듬으라"고 안내합니다.

✅ 자동 생성된 초안을 그대로 두지 말고, 프로젝트에 맞게 손보는 것이 핵심입니다.

⚠️ 각 슬래시 명령의 자세한 쓰임은 클로드코드 명령어 정리 글에서 함께 보면 좋습니다.

공식 문서 원문에서 정확한 동작을 확인하고 싶다면 아래 버튼으로 이동할 수 있습니다.

📄 클로드코드 공식 메모리 문서 보러가기 →

잘 쓰는 구조 — 짧고 구체적으로

CLAUDE.md를 잘 쓰는 첫 번째 원칙은 "짧게"입니다.

이 파일은 매 세션 컨텍스트에 통째로 로드되므로, 길수록 토큰을 많이 먹고 준수율도 떨어집니다.

공식 권장 분량은 200줄 미만입니다.

각 줄마다 "이 줄을 지우면 클로드코드가 실수하게 되나?"를 물어보고, 아니라면 지우라는 것이 공식 조언입니다.

두 번째 원칙은 "구체적으로"입니다.

"포맷을 제대로 해라"가 아니라 "2칸 들여쓰기를 써라"처럼 씁니다.

"테스트를 해라"가 아니라 "커밋 전 npm test를 돌려라"처럼 씁니다.

아래 표는 공식 문서가 정리한 넣을 것과 뺄 것입니다.

✅ 넣을 것	❌ 뺄 것
추측할 수 없는 빌드·테스트 명령	코드를 읽으면 알 수 있는 것
기본값과 다른 코드 스타일 규칙	이미 아는 표준 언어 관례
테스트 방법·선호 테스트 러너	상세 API 문서 (링크만 걸기)
브랜치 네이밍·PR 관례	자주 바뀌는 정보
자주 걸리는 함정·비직관적 동작	"깨끗한 코드를 써라" 류 자명한 원칙

공식 문서가 그대로 보여주는 좋은 예시 스니펫은 이렇게 생겼습니다.

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

728x90

헤더와 불릿으로 관련 지침을 묶어주는 것도 도움이 됩니다.

클로드코드도 사람처럼 구조를 훑어보기 때문입니다.

특히 꼭 지켜야 하는 규칙에 "IMPORTANT"나 "YOU MUST"를 붙이면 준수율이 올라간다고 공식 문서는 설명합니다.

그럼 언제 규칙을 추가해야 할까요. 공식 문서는 네 가지 신호를 듭니다.

① 클로드코드가 같은 실수를 두 번째로 할 때 ② 코드리뷰가 클로드코드가 알았어야 할 것을 잡아낼 때 ③ 지난 세션에도 쳤던 교정을 또 치고 있을 때 ④ 새 팀원이 필요로 할 맥락일 때입니다.

나쁜 예 — 소설처럼 길게 쓰면 무시된다

가장 흔한 실패는 규칙을 너무 많이, 너무 길게 적는 것입니다.

공식 문서는 이를 "과하게 상세한 CLAUDE.md"라고 부릅니다.

파일이 길어지면 클로드코드가 절반을 무시하고, 정작 중요한 규칙이 소음에 묻힙니다.

공식 문서 표현으로는 "비대해진 CLAUDE.md는 클로드코드가 진짜 지시를 무시하게 만든다"입니다.

진단법도 명쾌합니다.

규칙이 있는데도 클로드코드가 계속 안 지키면, 파일이 너무 긴 것입니다.

클로드코드가 CLAUDE.md에 이미 답이 있는 질문을 하면, 그 문구가 모호한 것입니다.

그래서 튜토리얼처럼 긴 설명, 파일별 코드 설명, "깨끗하게 짜라" 같은 자명한 관례는 빼는 편이 낫습니다.

개인적으로는 CLAUDE.md를 처음 만들 때보다, 주기적으로 가지치기할 때 효과가 더 크다고 봅니다.

커뮤니티에서도 "다들 처음엔 규칙을 잔뜩 넣다가, 길수록 무시된다는 걸 깨닫고 다이어트하는 쪽으로 수렴한다"는 분위기가 공통적입니다.

한 가지 오해도 짚어둡니다.

CLAUDE.md는 @파일경로 문법으로 외부 파일을 불러올 수 있는데(재귀 불러오기는 최대 4단계), 이건 정리·구조화용이지 토큰을 줄여주지는 않습니다.

불러온 파일도 시작할 때 전부 컨텍스트에 로드되기 때문입니다.

반응형

실사례 — 이 블로그도 CLAUDE.md로 굴러간다

추상적으로 들릴 수 있으니, CLAUDE.md를 실제로 쓰는 예를 하나 들겠습니다.

지금 읽고 있는 이 블로그가 바로 그 예입니다.

이 블로그의 글 작성 규칙은 프로젝트 CLAUDE.md에 통째로 담겨 있습니다.

글의 말투, 티스토리 HTML 출력 규칙, 쓰면 안 되는 문구, 이미지 프롬프트 규칙까지 전부 이 파일에 적혀 있습니다.

덕분에 새 글을 쓸 때마다 "인사말로 시작하지 마라", "제목을 본문에서 반복하지 마라" 같은 지시를 다시 입력할 필요가 없습니다.

예를 들어 지침에 "'안녕하세요'로 시작하는 인사말을 금지한다"는 한 줄을 넣어두면, 그 뒤로는 어떤 글도 인사말로 시작하지 않습니다.

세션이 바뀌어도, 다른 주제를 써도 이 규칙은 그대로 적용됩니다.

이것이 바로 "매번 다시 설명하게 될 내용을 적어두는 곳"이라는 공식 정의가 실제로 작동하는 모습입니다.

이 블로그가 어떻게 CLAUDE.md 기반 자동화로 굴러가는지는 블로그 자동화 구축기 글에서 더 자세히 다룹니다.

자주 묻는 질문

CLAUDE.md는 어디에 둬야 하나요?

내 컴퓨터 전체에 적용하려면 ~/.claude/CLAUDE.md, 특정 프로젝트에만·팀과 공유하려면 프로젝트 폴더의 CLAUDE.md에 둡니다.

둘 다 두면 전역 규칙 위에 프로젝트 규칙이 더해지는 식으로 함께 적용됩니다.

AI가 알아서 기억하는 것과 뭐가 다른가요?

CLAUDE.md는 사람이 직접 써서 규칙을 지시하는 파일입니다.

반면 오토 메모리(Auto memory)는 클로드코드가 대화 중 스스로 알아낸 것을 기록하는 별도 기능이라, 둘은 다릅니다.

예를 들어 그냥 "항상 pnpm을 써라"고 말하면 CLAUDE.md가 아니라 오토 메모리에 저장됩니다.

CLAUDE.md에 쓴 대로 AI가 무조건 따르나요?

아닙니다.

강제 규칙이 아니라 강력한 안내문이라, 파일이 길거나 모호하면 무시될 수 있습니다.

반드시 실행돼야 하는 규칙은 Hook으로 만들어야 확실합니다.

정리하며

CLAUDE.md는 클로드코드에게 같은 말을 반복하지 않으려고 두는 온보딩 문서입니다.

전역(~/.claude/CLAUDE.md)과 프로젝트(CLAUDE.md) 두 곳만 기억하면 시작하기 충분합니다.

/init으로 초안을 만들고, 짧고 구체적으로 다듬는 것이 핵심입니다.

세션 중에 규칙을 추가하고 싶으면 "CLAUDE.md에 추가해줘"라고 말하거나 /memory로 파일을 직접 열어 편집하면 됩니다.

클로드코드 버전에 따라 # 입력으로 바로 추가하는 방식이 남아 있을 수 있으니, 이 부분은 본인 버전에서 확인하는 것이 좋습니다.

지침이 잘 로드됐는지는 /context로 점검할 수 있습니다.

처음엔 짧게 시작해서, 클로드코드가 실수할 때마다 한 줄씩 채워가면 됩니다.

그렇게 쌓인 CLAUDE.md는 시간이 지날수록 가치가 복리로 불어납니다.

다음 편에서는 반복 작업을 명령 하나로 묶는 클로드코드 스킬(Skill) 만드는 법을 다룹니다.

 

 

참고한 자료

클로드코드 공식 문서 How Claude remembers your project(CLAUDE.md·memory)와 Best practices for Claude Code를 사실 근거로 삼았고, HumanLayer의 Writing a good CLAUDE.md, Dale Seo·요즘IT·한컴테크의 한글 정리 글을 보조로 참고했습니다. 모델 동작·명령·권장 분량은 발행 전 공식 문서 확인이 필요합니다.