CLAUDE.md 작성법: AI가 프로젝트 규칙을 무시할 때

Claude Code 입문

Claude Code에 같은 프로젝트를 열고 매번 같은 지시를 반복하고 있다면, CLAUDE.md 파일 하나로 해결할 수 있습니다. 규칙 파일을 만들어두면 AI가 매 세션마다 자동으로 읽어서 일관된 결과물을 만들어냅니다.

📌 3줄 요약

• • 대화창에 입력한 규칙은 대화가 길어지면 컨텍스트에서 밀려나 유실됩니다.
• • CLAUDE.md 파일에 규칙을 적어두면 매 세션마다 자동 로드되어 일관성이 유지됩니다.
• • 규칙은 20개 이내로 짧고 명확하게, 목록 형태로 작성하는 것이 핵심입니다.

📑 목차

• 1. CLAUDE.md 없이 작업하면 반복되는 문제
• 2. CLAUDE.md의 역할과 동작 원리
• 3. CLAUDE.md 작성법 단계별 가이드
• 4. CLAUDE.md 관리 팁과 흔한 실수

CLAUDE.md 없이 작업하면 반복되는 문제

Claude Code에 같은 프로젝트를 열고 매번 같은 지시를 반복한 경험이 있을 겁니다. "우리 프로젝트는 격식체를 써", "테스트는 pytest로 돌려" 같은 규칙을 대화할 때마다 다시 알려줘야 합니다. 처음 한두 번은 괜찮지만, 매일 같은 프로젝트를 열 때마다 이 과정을 반복하면 생산성이 크게 떨어집니다. 특히 규칙이 5개, 10개로 늘어나면 전달하는 것 자체가 하나의 작업이 됩니다.

문제는 여기서 끝나지 않습니다. 규칙을 말해줘도 대화가 길어지면 AI가 슬그머니 원래 습관으로 돌아갑니다. 처음에는 분명히 규칙을 잘 따르다가, 파일을 여러 개 수정하거나 기능을 추가하는 중간에 점점 흐트러지는 패턴이 나타납니다.

예를 들어 "변수명은 snake_case로 써달라"고 분명히 말했는데, 파일 3개쯤 수정하고 나면 camelCase가 섞여 나옵니다. 코드 리뷰를 하다 보면 어떤 파일은 user_name이고 어떤 파일은 userName으로 되어 있어서 일관성이 무너집니다. 이건 AI가 고의로 무시하는 게 아니라, 대화 맥락이 밀려나면서 지시가 유실되는 현상입니다.

🔍 컨텍스트 윈도우란?

컨텍스트 윈도우는 AI가 한 번에 기억할 수 있는 텍스트 양을 말합니다. 대화가 길어질수록 초반에 했던 말이 잘려나가는 구조입니다. 마치 화이트보드에 글씨를 계속 쓰다가 공간이 부족해지면 맨 위부터 지우는 것과 비슷합니다. 내가 처음에 적어둔 규칙이 가장 먼저 사라지는 셈입니다.

💬 직접 써보니까 이 문제가 가장 답답했습니다. 분명 전달했는데 안 지켜지면 AI 탓을 하게 되는데, 사실은 구조적인 한계였던 겁니다. 이 문제를 해결하려면 대화창이 아닌 다른 곳에 규칙을 저장해두는 방법이 필요합니다. 그 해결책이 바로 CLAUDE.md 파일입니다.

 

CLAUDE.md의 역할과 동작 원리

CLAUDE.md는 프로젝트 폴더에 넣어두는 규칙 파일입니다. Claude Code가 대화를 시작할 때 이 파일을 자동으로 읽어서 시스템 프롬프트(system prompt)처럼 활용합니다. 별도의 설정이나 플러그인 설치 없이, 파일만 만들어두면 알아서 인식하는 구조입니다.

일반 대화에서 전달한 지시는 대화가 길어지면 밀려나지만, CLAUDE.md에 적은 규칙은 매 세션마다 새로 로드됩니다. 그래서 아무리 긴 작업을 하더라도 규칙이 유실되지 않습니다. 대화 중간에 컨텍스트가 압축되더라도 CLAUDE.md의 내용은 항상 유지됩니다. 이것이 대화창에 규칙을 입력하는 것과 결정적으로 다른 점입니다.

CLAUDE.md 파일을 놓을 수 있는 위치는 세 곳입니다. 프로젝트 루트, 하위 디렉토리, 그리고 홈 디렉토리(~/.claude/CLAUDE.md)입니다.

위치	적용 범위	사용 예시
프로젝트 루트	해당 프로젝트 전체	프로젝트별 코드 컨벤션
하위 디렉토리	해당 폴더 안에서만	프론트/백엔드 분리 규칙
홈 디렉토리	모든 프로젝트 공통	"항상 한국어로 응답" 등

프로젝트 루트에 놓으면 해당 프로젝트 전체에 적용되고, 하위 디렉토리에 놓으면 그 폴더 안에서만 적용됩니다. 홈 디렉토리에 놓으면 모든 프로젝트에 공통으로 적용되니, 개인 작업 스타일을 고정할 때 유용합니다. 예를 들어 "항상 한국어로 응답해줘" 같은 규칙은 홈 디렉토리에 넣어두면 어떤 프로젝트를 열든 자동으로 적용됩니다. 반대로 프로젝트별 코드 컨벤션은 프로젝트 루트에 넣는 것이 적절합니다.

아래 화면처럼 프로젝트 루트에 CLAUDE.md를 생성하면 됩니다.

 

이 구조를 이해하면 규칙 관리가 훨씬 체계적으로 바뀝니다. 단순히 "AI한테 말하기"에서 "설정 파일로 관리하기"로 전환되는 셈입니다. 코드와 함께 Git에 커밋할 수 있으니 버전 관리도 자연스럽게 됩니다. 규칙이 언제, 왜 바뀌었는지 히스토리로 추적할 수 있다는 뜻입니다.

CLAUDE.md 작성법 단계별 가이드

가장 먼저 프로젝트 루트에 CLAUDE.md 파일을 생성합니다. 터미널에서 아래 명령어를 실행하면 됩니다.

touch CLAUDE.md

Windows를 사용하고 있다면 파일 탐색기에서 직접 만들어도 되고, VS Code에서 새 파일을 만들어도 됩니다.

⚠️ 파일 이름이 정확히 CLAUDE.md(대문자)여야 합니다. claude.md나 Claude.md로 쓰면 인식되지 않을 수 있으니 주의가 필요합니다.

파일 안에는 프로젝트에서 지켜야 할 규칙을 마크다운 형식으로 적습니다. 실전에서 바로 쓸 수 있는 템플릿 구조는 다음과 같습니다.

# 프로젝트 규칙

## 문체
- 격식체(~습니다) 사용
- 해요체 금지

## 코드 컨벤션
- 변수명: snake_case
- 함수명: snake_case
- 들여쓰기: 스페이스 4칸

## 테스트
- pytest 사용
- 테스트 파일명: test_*.py

## 금지 사항
- console.log 대신 logger 사용
- any 타입 사용 금지

핵심은 규칙을 짧고 명확하게, 목록 형태로 작성하는 것입니다. 장황한 설명보다 한 줄짜리 규칙이 AI에게 훨씬 잘 전달됩니다. "가능하면 snake_case를 사용해주세요"보다 "변수명: snake_case"가 더 명확합니다. 모호한 표현은 AI가 판단을 흔들리게 만드니, 단정적으로 적는 것이 좋습니다.

 

💡 규칙 개수 팁

규칙의 개수는 처음부터 욕심내지 않는 게 좋습니다. 5~10개 규칙으로 시작해서, 실제로 AI가 어기는 항목을 발견할 때마다 추가하는 방식이 효과적입니다. 처음부터 규칙을 30개씩 쏟아내면 정작 중요한 규칙이 묻히는 역효과가 생깁니다. 먼저 가장 자주 어기는 항목 3~5개만 적어두고 시작하는 것을 권장합니다.

💡 "왜"를 함께 적으면 더 효과적

규칙을 적을 때 "왜 이 규칙이 필요한지" 배경을 한 줄 덧붙이면 AI가 맥락을 파악해서 더 잘 따릅니다. 예를 들어 - console.log 금지 (프로덕션 로그가 오염되므로) 같은 식입니다. 이유를 함께 적으면 비슷한 상황에서도 AI가 규칙의 의도를 추론해서 일관되게 적용합니다. 단순히 "하지 마"보다 "이런 이유로 하지 마"가 AI에게도 효과적입니다.

💬 이 방식으로 관리하면 팀 프로젝트에서도 규칙을 Git으로 공유할 수 있습니다. 새 팀원이 Claude Code를 쓸 때 별도 안내 없이도 동일한 규칙이 적용되는 구조입니다. 온보딩 문서에 "CLAUDE.md를 읽어보세요"라고 한 줄만 추가하면 됩니다. 팀 전체의 AI 활용 품질이 일관되게 유지되는 효과를 얻을 수 있습니다.

CLAUDE.md 관리 팁과 흔한 실수

가장 흔한 실수는 CLAUDE.md에 너무 많은 내용을 넣는 것입니다. 규칙이 50개를 넘어가면 오히려 AI가 우선순위를 혼동해서 중요한 규칙을 놓칠 수 있습니다. 컨텍스트 윈도우를 효율적으로 쓰려면 규칙 파일도 간결해야 합니다. 불필요하게 긴 설명이나 예시를 줄줄이 넣으면 핵심이 희석됩니다.

규칙은 20개 이내로 유지하고, 정말 중요한 항목에는 "절대", "반드시" 같은 강조 표현을 붙이는 것을 권장합니다. 모든 규칙이 똑같은 무게를 가지면 어떤 것도 강조되지 않는 것과 같습니다. 예를 들어 - 절대 .env 파일을 커밋하지 마 같은 보안 규칙에는 "절대"를 붙이고, 일반적인 스타일 규칙은 평서형으로 적는 식으로 무게를 다르게 주면 됩니다.

🔍 하위 디렉토리별 규칙 분리

하위 디렉토리별로 다른 규칙이 필요하다면 해당 폴더에 별도의 CLAUDE.md를 만들 수 있습니다. 예를 들어 frontend/CLAUDE.md에는 React 컨벤션을, backend/CLAUDE.md에는 Python 컨벤션을 적는 식입니다. 이렇게 하면 프론트엔드 코드를 수정할 때와 백엔드 코드를 수정할 때 각각 다른 규칙이 적용됩니다. 프로젝트 구조가 커질수록 이런 분리가 유지보수에 큰 도움이 됩니다.

규칙이 제대로 적용되는지 확인하는 방법도 간단합니다. Claude Code를 실행하면 대화 시작 시 CLAUDE.md가 로드되었다는 메시지가 표시됩니다. 이 메시지가 보이지 않는다면 파일 위치나 이름이 잘못된 것이니 확인이 필요합니다.

 

규칙을 수정했는데 반영이 안 되는 경우가 간혹 있습니다. 이때는 /clear 명령어로 대화를 초기화한 뒤 다시 시작하면 최신 규칙이 로드됩니다. 이미 진행 중인 대화에서는 이전에 로드된 CLAUDE.md가 유지되기 때문에, 수정 사항을 바로 반영하려면 대화를 새로 시작해야 합니다.

CLAUDE.md는 한번 만들어두면 끝이 아니라, 프로젝트와 함께 성장하는 문서입니다. AI가 반복적으로 어기는 패턴이 보이면 그때마다 규칙을 추가하고, 더 이상 필요 없는 규칙은 정리하면 됩니다. 한 달에 한 번 정도 규칙을 훑어보면서 여전히 유효한지 점검하는 습관을 들이면 좋습니다. 프로젝트가 성숙해질수록 CLAUDE.md도 함께 정제되어, 점점 더 정확한 결과물을 얻을 수 있게 됩니다.

✍️ 마치며

CLAUDE.md는 AI에게 "이 프로젝트에서는 이렇게 해달라"고 말하는 설정 파일입니다. 대화창에 매번 규칙을 반복 입력하는 비효율을 없애고, 긴 작업에서도 규칙이 유실되지 않도록 보장합니다. 파일 하나 만드는 데 5분이면 충분하니, 오늘 바로 프로젝트 루트에 CLAUDE.md를 생성하고 가장 자주 어기는 규칙 3개부터 적어보세요. 그것만으로도 Claude Code와의 협업 품질이 눈에 띄게 달라질 겁니다.

#ClaudeCode #CLAUDE.md #AI코딩 #프로젝트규칙 #컨텍스트윈도우 #AI활용팁