CLAUDE.md 프로젝트 규칙 설정으로 AI 헛발질 줄이는 법

Claude Code 입문

Claude Code가 엉뚱한 파일을 수정하고, 안 쓰는 라이브러리를 설치하고, 관련 없는 코드를 리팩토링하는 문제를 겪고 계신가요?
CLAUDE.md 파일 하나면 이런 "AI 헛발질"을 대폭 줄일 수 있습니다.

📌 3줄 요약

• CLAUDE.md는 AI에게 프로젝트 맥락을 알려주는 온보딩 문서 역할을 한다
• 기술 스택, 금지 사항, 디렉토리 구조를 적으면 AI의 엉뚱한 행동이 크게 줄어든다
• 처음부터 완벽하게 쓰지 말고, AI가 실수할 때마다 규칙을 하나씩 추가하는 방식이 가장 효과적이다

🗂️ 목차

1. CLAUDE.md 없이 작업하면 생기는 문제들
2. CLAUDE.md 핵심 규칙 작성법
3. 실전 CLAUDE.md 템플릿 적용하기
4. CLAUDE.md 적용 후 달라지는 점

CLAUDE.md 없이 작업하면 생기는 문제들

Claude Code를 처음 쓰면 신기합니다.
"이 버그 고쳐줘"라고 하면 알아서 파일을 찾아 수정해 주니까요.
코드를 한 줄도 직접 치지 않아도 기능이 구현되는 경험은 정말 놀라운데요.
처음에는 "이거 만능 아닌가?" 싶은 생각이 들 정도입니다.

그런데 며칠 쓰다 보면 이상한 일이 벌어집니다.
분명 백엔드 로직만 고쳐달라고 했는데, 프론트엔드 파일까지 건드린다거나요.
심한 경우에는 잘 돌아가고 있던 다른 기능의 코드를 멋대로 리팩토링하기도 합니다.
한번은 데이터베이스 쿼리 하나만 수정해달라고 했더니, 관련 없는 API 라우터 파일 3개를 동시에 바꿔서 서버가 안 뜬 적도 있었습니다.

⚠️ 주의
테스트 코드를 작성해달라고 했더니 프로젝트에서 쓰지 않는 테스트 프레임워크를 설치하는 경우도 있습니다. 이미 jest로 테스트 환경을 구축해뒀는데, 느닷없이 vitest를 설치하고 설정 파일까지 새로 만들어 놓는 식이에요. 기존 테스트가 깨지는 건 물론이고, 패키지 충돌까지 일어나서 오히려 원래보다 상황이 악화되기도 합니다.

이런 "헛발질"은 AI가 프로젝트 맥락을 모르기 때문에 발생합니다.

🔍 배경지식
사람도 처음 합류한 프로젝트에서 코딩 컨벤션을 모르면 실수하는 것과 같은 원리입니다. 신입 개발자에게 "우리 프로젝트는 이런 규칙으로 돌아가"라고 온보딩 문서를 주면 실수가 줄어들잖아요. CLAUDE.md는 바로 그 온보딩 문서를 AI에게 제공하는 역할을 합니다. 프로젝트의 기술 스택, 디렉토리 구조, 코딩 규칙을 한 파일에 정리해두면 AI가 매번 이 정보를 참고하게 됩니다.

💬 경험담
제가 직접 써보니, CLAUDE.md를 만들기 전과 후의 차이가 꽤 극적이었습니다. 특히 파일 구조가 복잡한 프로젝트에서 AI가 엉뚱한 디렉토리를 건드리는 빈도가 눈에 띄게 줄었구요. 이전에는 한 번의 요청으로 끝날 작업이 AI의 실수를 되돌리느라 두세 번의 추가 요청이 필요했는데, CLAUDE.md 도입 후에는 첫 번째 시도에서 올바르게 처리되는 비율이 크게 올라갔습니다.

 

CLAUDE.md 핵심 규칙 작성법

1

기술 스택 명시
CLAUDE.md 파일은 프로젝트 루트 디렉토리(최상위 폴더)에 만듭니다. 파일 이름은 반드시 대문자로 CLAUDE.md여야 Claude Code가 자동으로 인식합니다. 소문자로 claude.md라고 만들면 인식이 안 되니 주의하세요. 확장자도 반드시 .md(마크다운)여야 하며, .txt나 다른 형식은 읽지 않습니다.

가장 먼저 적어야 할 내용은 프로젝트의 기술 스택입니다. 예를 들어 "이 프로젝트는 Python 3.11 + FastAPI를 사용한다"처럼 명시하면, AI가 다른 프레임워크의 문법을 섞어 쓰는 실수를 방지할 수 있습니다. 패키지 매니저도 함께 적어두면 좋습니다. npm을 쓰는 프로젝트에서 AI가 yarn 명령어를 실행하는 일을 막을 수 있거든요. 데이터베이스 종류나 ORM 같은 핵심 기술도 적어두면 AI가 엉뚱한 라이브러리를 추천하는 일이 줄어듭니다.

 

2

"하지 말아야 할 것" 목록
두 번째로 중요한 것은 "하지 말아야 할 것" 목록입니다. 금지 사항을 구체적으로 적을수록 AI의 헛발질이 줄어듭니다. 막연하게 "코드를 깔끔하게 써줘"보다 "console.log를 남기지 마세요"처럼 구체적으로 쓰는 것이 훨씬 효과적입니다.

실제로 효과가 좋은 금지 규칙 예시를 보겠습니다.

# 금지 사항
- node_modules/, dist/ 디렉토리의 파일은 절대 수정하지 마세요
- 새로운 패키지를 설치하기 전에 반드시 사용자에게 확인하세요
- 테스트는 jest만 사용하세요 (mocha, vitest 사용 금지)
- console.log 디버깅 코드를 남기지 마세요

이런 규칙을 적어두면 Claude Code가 작업 전에 이 목록을 확인하고, 금지된 행동을 스스로 걸러냅니다.

💡 팁
"절대", "반드시" 같은 강조 표현을 쓰면 AI가 해당 규칙을 더 엄격하게 따르는 경향이 있습니다.

💬 경험담
저는 프로젝트를 진행하면서 AI가 실수할 때마다 금지 사항을 하나씩 추가했는데, 규칙이 5개쯤 쌓이니 같은 실수가 거의 재발하지 않았습니다.

3

파일 구조 안내
"src/api/는 API 라우터, src/services/는 비즈니스 로직"처럼 디렉토리별 역할을 적어두면, AI가 코드를 올바른 위치에 생성합니다. 새로운 API 엔드포인트를 만들어달라고 했을 때, src/services/에 라우터 코드를 넣는 실수를 방지할 수 있어요. 프로젝트가 모노레포 구조라면 각 패키지의 역할까지 적어두는 것을 추천합니다.

 

💬 경험담
제가 여러 프로젝트에서 테스트해본 결과, 금지 사항 목록이 가장 효과적이었습니다. "~하지 마세요"라는 명확한 지시가 AI에게 경계선을 만들어 주는 셈이구요. 반면 "좋은 코드를 작성해주세요" 같은 추상적인 지시는 거의 효과가 없었습니다.

실전 CLAUDE.md 템플릿 적용하기

바로 복사해서 쓸 수 있는 템플릿을 준비했습니다.
프로젝트 상황에 맞게 내용만 바꾸면 됩니다.
괄호 안의 내용을 본인의 프로젝트 정보로 교체하면 바로 사용할 수 있어요.

# 프로젝트 개요
- 이름: (프로젝트 이름)
- 기술 스택: (예: Python 3.11, FastAPI, PostgreSQL)
- 패키지 매니저: (예: pip, npm, pnpm)

# 디렉토리 구조
- src/          → 소스 코드
- tests/        → 테스트 파일
- docs/         → 문서

# 코딩 컨벤션
- 변수명: snake_case
- 함수 docstring 필수
- 타입 힌트 사용

# 금지 사항
- (프로젝트에 맞게 작성)

# 테스트
- 명령어: pytest tests/
- 새 기능 추가 시 테스트 파일도 함께 생성

🔍 템플릿 구조 설명
이 템플릿의 각 섹션은 AI가 가장 자주 실수하는 영역을 커버하도록 설계되어 있습니다. 프로젝트 개요는 기술 스택 혼동을 막고, 디렉토리 구조는 파일 위치 오류를 방지하며, 금지 사항은 불필요한 행동을 차단합니다. 처음에는 이 템플릿 그대로 사용하다가, 프로젝트에 맞는 규칙을 점차 추가해나가면 됩니다.

이 템플릿을 저장한 뒤 Claude Code를 실행하면, 터미널에서 CLAUDE.md를 읽었다는 메시지가 표시됩니다.

 

CLAUDE.md는 대화가 시작될 때마다 자동으로 로드됩니다.
따라서 매번 "이 프로젝트는 Python이야"라고 반복해서 알려줄 필요가 없습니다.
새 터미널을 열고 Claude Code를 시작해도, 프로젝트 루트에 CLAUDE.md가 있으면 자동으로 읽어옵니다.
팀원이 같은 프로젝트에서 Claude Code를 쓸 때도 동일한 규칙이 적용되니, 코드 일관성 유지에도 도움이 됩니다.

💡 팁
처음부터 완벽한 CLAUDE.md를 만들려고 하지 않는 것이 좋습니다. AI가 실수할 때마다 해당 실수를 방지하는 규칙을 하나씩 추가하는 방식이 훨씬 실용적이구요.

💬 경험담
실제로 저도 처음에는 기술 스택과 금지 사항 3개 정도만 적고 시작했습니다. 일주일 정도 쓰면서 AI가 틀리는 패턴을 발견할 때마다 규칙을 추가했더니, 자연스럽게 프로젝트에 딱 맞는 CLAUDE.md가 완성되었습니다.

CLAUDE.md 적용 후 달라지는 점

CLAUDE.md를 제대로 설정하면 체감되는 변화가 세 가지 있습니다.

변화	설명
불필요한 패키지 설치 방지	"새로운 패키지 설치 전 확인 필수"라는 규칙 하나만 넣어도, AI가 npm install이나 pip install을 실행하기 전에 반드시 물어봅니다.
코딩 스타일 일관성	변수명을 camelCase로 썼다가 snake_case로 썼다가 하는 혼란이 없어집니다. 들여쓰기 스타일, 문자열 따옴표 종류 같은 세부 컨벤션도 지켜집니다.
수정 범위 제한	"이 함수만 고쳐줘"라고 했을 때 진짜 그 함수만 건드리게 됩니다. 과잉 수정이 크게 줄어듭니다.

첫째, AI가 프로젝트와 무관한 라이브러리를 마음대로 설치하는 일이 사라집니다.
"새로운 패키지 설치 전 확인 필수"라는 규칙 하나만 넣어도, AI가 npm install이나 pip install을 실행하기 전에 반드시 물어봅니다.
예전에는 간단한 유틸 함수 하나 때문에 lodash 전체를 설치하는 일이 있었는데, 이런 상황이 완전히 사라졌습니다.

둘째, 코딩 스타일이 일관됩니다.
변수명을 camelCase로 썼다가 snake_case로 썼다가 하는 혼란이 없어집니다.
CLAUDE.md에 "변수명은 camelCase를 사용한다"라고 한 줄만 적어두면, AI가 생성하는 모든 코드에서 이 규칙이 지켜집니다.
들여쓰기 스타일, 문자열 따옴표 종류 같은 세부 컨벤션도 마찬가지입니다.
코드 리뷰 때 스타일 지적을 하는 횟수가 확연히 줄어든 것을 체감할 수 있습니다.

셋째, 수정 범위가 요청한 부분으로 한정됩니다.
"이 함수만 고쳐줘"라고 했을 때 진짜 그 함수만 건드리게 됩니다.
이전에는 관련 함수, 호출하는 쪽, 심지어 import 문까지 AI가 자기 판단으로 수정하는 경우가 많았습니다.
CLAUDE.md에 "요청한 범위 외의 코드는 수정하지 마세요"라는 규칙을 넣으면 이런 과잉 수정이 크게 줄어듭니다.

 

⚠️ 주의
CLAUDE.md가 너무 길어지면 오히려 역효과가 날 수 있습니다. 규칙이 수십 개를 넘어가면 AI가 우선순위를 혼동하기도 합니다. 서로 모순되는 규칙이 들어가면 AI가 어떤 규칙을 따라야 할지 판단하지 못해 오히려 품질이 떨어질 수 있어요. 규칙은 많을수록 좋은 것이 아니라, 핵심만 담겨 있을수록 잘 작동합니다.

경험상 금지 사항 5~10개, 디렉토리 설명 10줄 이내가 가장 효과적이었습니다.
핵심 규칙만 간결하게 유지하는 것이 비결입니다.
필요 없어진 규칙은 주기적으로 정리해주는 것도 중요합니다.

🔍 하위 디렉토리 CLAUDE.md
하위 디렉토리에도 별도의 CLAUDE.md를 둘 수 있습니다. 예를 들어 frontend/CLAUDE.md에 프론트엔드 전용 규칙을 적고, backend/CLAUDE.md에 백엔드 전용 규칙을 적으면, Claude Code가 해당 디렉토리에서 작업할 때 자동으로 해당 규칙을 추가 로드합니다. 루트 CLAUDE.md에는 프로젝트 공통 규칙을, 하위 CLAUDE.md에는 영역별 세부 규칙을 적는 식으로 계층 구조를 활용하면 규칙이 깔끔하게 정리됩니다.

✍️ 마치며

처음에는 CLAUDE.md 작성이 번거롭게 느껴질 수 있습니다. 하지만 한번 세팅해두면 이후 모든 대화에서 같은 말을 반복하지 않아도 되니, 장기적으로 시간이 크게 절약됩니다. 특히 프로젝트를 오래 진행할수록 CLAUDE.md의 가치가 점점 커집니다. AI와의 협업 품질을 한 단계 올리고 싶다면, 오늘 바로 프로젝트 루트에 CLAUDE.md 파일 하나를 만들어 보세요.

#ClaudeCode #CLAUDE_md #AI코딩 #프로젝트규칙 #AI헛발질방지 #코딩컨벤션 #개발생산성