CLAUDE.md로 프로젝트 규칙을 AI에게 가르치는 법

Claude Code 입문

Claude Code에 우리 프로젝트 규칙을 알려주는 가장 쉬운 방법, CLAUDE.md 파일 하나면 충분해요.

📌 3줄 요약

• CLAUDE.md는 프로젝트 규칙을 Claude Code에 자동으로 전달하는 설정 파일이에요.
• 코딩 스타일·금지 사항·폴더 구조·커밋 규칙·명령어, 이 5가지만 넣어도 작업 품질이 확 달라져요.
• 프로젝트 루트에 두면 전체 적용, 하위 폴더에 두면 영역별 적용이 가능해요.

📑 목차

• 1. CLAUDE.md가 필요한 이유
• 2. CLAUDE.md 파일 만들기와 기본 구조
• 3. CLAUDE.md에 담으면 좋은 규칙 5가지
• 4. CLAUDE.md 적용 확인과 관리 요령

CLAUDE.md가 필요한 이유

Claude Code는 똑똑하지만, 우리 프로젝트만의 규칙까지 알지는 못해요. 변수 이름은 카멜케이스로 쓴다거나, 특정 폴더에는 파일을 만들지 말라는 규칙은 코드만 봐서 파악하기 어려워요. 프로젝트마다 선호하는 라이브러리가 다르고, 커밋 메시지 형식도 팀별로 제각각이잖아요. 이런 암묵적인 규칙들은 코드 어디에도 명시되어 있지 않기 때문에, AI가 스스로 알아내기를 기대하기는 어려워요.

이런 상황에서 매번 "변수명은 카멜케이스로 해줘"라고 반복 지시하면 피곤해요. 대화가 길어지면 앞에서 했던 지시를 Claude Code가 잊어버리는 경우도 생겨요.

💬 한 번은 같은 프로젝트에서 세 번 연속으로 들여쓰기 규칙을 고쳐달라고 한 적이 있었는데, 그때 "이걸 한 번에 알려줄 방법이 없을까?" 싶었어요.

CLAUDE.md 파일 하나만 만들어 두면, Claude Code가 매 대화 시작 시 자동으로 규칙을 읽어 가요.

🔍 일종의 "프로젝트 설명서"를 AI에게 건네는 셈이에요. 사람이 팀에 새로 합류하면 온보딩 문서를 읽듯, Claude Code도 CLAUDE.md를 읽고 프로젝트에 적응해요. 새 대화를 열 때마다 자동으로 로드되기 때문에, 한 번 작성하면 계속 효과가 유지돼요.

💬 제가 직접 써보니, CLAUDE.md 없이 작업할 때는 같은 지시를 세 번 이상 반복한 적이 많았어요. 파일 하나 만든 뒤로는 그런 반복이 거의 사라졌고, 작업 속도도 눈에 띄게 빨라졌어요.

CLAUDE.md 파일 만들기와 기본 구조

만드는 방법은 간단해요. 프로젝트 최상위 폴더에 CLAUDE.md라는 이름으로 파일을 하나 생성하면 돼요. 터미널에서 touch CLAUDE.md 한 줄이면 빈 파일이 만들어져요. VS Code 같은 에디터에서 새 파일을 만들어도 되고, 파일 탐색기에서 직접 생성해도 상관없어요. 중요한 건 파일 이름이 정확히 CLAUDE.md여야 한다는 점이에요 — 대소문자를 꼭 맞춰 주세요.

 

기본 구조는 제목(#)과 목록(-)만으로 충분해요. 파일 안에는 마크다운(Markdown) 문법으로 규칙을 적어요.

🔍 마크다운을 처음 접하는 분이라도 걱정하지 마세요. #은 제목, -은 목록 항목이라는 것만 알면 돼요.

# 프로젝트 규칙

## 코딩 스타일
- 변수명은 camelCase를 사용한다
- 함수명은 동사로 시작한다 (예: getUser, saveFile)
- 들여쓰기는 스페이스 2칸

## 금지 사항
- console.log를 커밋에 포함하지 않는다
- any 타입 사용 금지

## 폴더 구조
- 컴포넌트는 src/components/ 아래에 생성
- 유틸 함수는 src/utils/ 아래에 생성

복잡한 문법이 필요 없어요. Claude Code가 자연어를 이해하기 때문에, 사람이 읽기 편한 문장으로 적으면 돼요. 표나 코드 블록을 넣어도 되지만, 단순한 목록 형태가 가장 잘 작동해요.

💬 제가 직접 써보니, 처음부터 완벽한 규칙을 쓰려고 하면 오히려 시작이 늦어져요. 규칙 3~5개로 시작해서 점차 늘려 가는 방식이 훨씬 실용적이었어요.

💡 작업하다가 "아, 이것도 규칙으로 넣어야겠다" 싶은 순간이 오면 그때 한 줄 추가하면 돼요.

 

CLAUDE.md에 담으면 좋은 규칙 5가지

어떤 내용을 넣어야 할지 막막할 수 있어요. 실제로 효과가 좋았던 규칙 다섯 가지를 정리해 드릴게요. 이 다섯 가지만 넣어도 Claude Code의 작업 품질이 확실히 달라져요.

1

코딩 스타일 규칙

네이밍 컨벤션(naming convention), 들여쓰기, 따옴표 종류처럼 팀마다 다른 스타일을 명시해요. 예를 들어 "변수명은 camelCase, 컴포넌트명은 PascalCase, CSS 클래스명은 kebab-case"처럼 구체적으로 적어요. 이 규칙이 없으면 Claude Code가 파일마다 다른 스타일을 적용하는 경우가 생겨요. 일관된 코드 스타일은 나중에 코드를 읽을 때도 큰 차이를 만들어요.

2

금지 사항

"이 폴더는 건드리지 마", "이 라이브러리는 사용 금지"처럼 하면 안 되는 것을 적어요. 특히 레거시 코드가 있는 프로젝트에서는 "이 파일은 수정하지 말 것"이라는 규칙이 매우 유용해요. Claude Code가 잘못된 판단으로 중요한 설정 파일을 건드리는 사고를 예방할 수 있어요. "axios 대신 fetch를 사용할 것"처럼 대안까지 함께 적으면 더 효과적이에요.

3

폴더 구조 설명

어떤 파일이 어디에 위치해야 하는지 알려주면, Claude Code가 새 파일을 엉뚱한 곳에 만드는 실수를 방지할 수 있어요. "API 관련 파일은 src/api/, 타입 정의는 src/types/, 테스트는 __tests__/ 아래에 생성"처럼 적어요. 프로젝트 규모가 커질수록 이 규칙의 가치가 높아져요. 폴더 구조를 모르는 상태에서 AI가 파일을 만들면, 나중에 정리하는 데 더 큰 시간이 들어요.

 

4

커밋 메시지 형식

fix: 버그 설명, feat: 기능 설명처럼 팀에서 쓰는 커밋 메시지 규칙을 적어 둬요. Conventional Commits 형식을 따르는 팀이라면 그 규칙을 그대로 적으면 돼요. Claude Code에게 커밋을 맡길 때 매번 형식을 지정하지 않아도 알아서 맞춰 줘요.

5

자주 쓰는 명령어

테스트 실행 명령(npm test), 빌드 명령(npm run build), 린트 명령(npm run lint) 같은 것을 적어 둬요. Claude Code가 코드를 수정한 뒤 테스트를 돌리거나 빌드를 확인할 때 이 명령어를 바로 사용해요. 프로젝트마다 스크립트 이름이 다를 수 있으니, 정확한 명령어를 알려주는 게 중요해요.

⚠️ 규칙을 쓸 때 핵심은 "구체적으로" 적는 거예요. "깔끔하게 코딩해줘"보다 "변수명은 camelCase, 함수명은 동사로 시작"이 훨씬 효과적이에요.

💬 제가 직접 써보니, 추상적인 규칙은 Claude Code가 해석을 제멋대로 할 때가 있었어요. 구체적인 예시를 한 줄 추가하는 것만으로 정확도가 크게 올라갔어요.

CLAUDE.md 적용 확인과 관리 요령

CLAUDE.md를 저장한 뒤, Claude Code를 실행하면 자동으로 파일을 인식해요. 별도의 설정이나 명령어 없이, 프로젝트 폴더에 파일이 있으면 돼요. Claude Code를 처음 실행할 때 터미널 상단에 "CLAUDE.md found"라는 메시지가 뜨는 걸 확인할 수 있어요. 이 메시지가 보이면 규칙이 정상적으로 로드된 거예요.

💡 제대로 적용됐는지 확인하는 방법도 간단해요. Claude Code에게 "CLAUDE.md에 어떤 규칙이 있어?"라고 물어보면 읽은 내용을 요약해 줘요. 만약 기대한 규칙이 빠져 있다면, 파일 이름이나 위치를 다시 확인해 보세요. 파일 이름에 오타가 있거나 하위 폴더에 잘못 넣은 경우가 대부분이에요.

 

CLAUDE.md는 한 번 만들고 끝이 아니라, 프로젝트와 함께 업데이트하는 문서예요. 새로운 규칙이 생기거나 기존 규칙이 바뀌면 바로 반영해요. 프로젝트 초반에는 규칙이 3~5개로 시작하더라도, 한 달쯤 지나면 자연스럽게 10개 이상으로 늘어나는 경우가 많아요. 이렇게 점진적으로 쌓이는 규칙이 결국 프로젝트의 "암묵지"를 문서화하는 효과를 줘요.

🔍 파일 위치에 따라 적용 범위도 달라져요. 프로젝트 루트에 두면 전체 프로젝트에 적용되고, 특정 하위 폴더에 두면 그 폴더 작업 시에만 적용돼요. 예를 들어 frontend/CLAUDE.md에 React 관련 규칙을 넣고, backend/CLAUDE.md에 Express 관련 규칙을 넣으면 각각의 영역에서만 동작해요. 이 구조를 활용하면 모노레포(monorepo)에서도 영역별로 다른 규칙을 적용할 수 있어요.

팀 프로젝트라면 CLAUDE.md를 Git에 커밋해서 팀원 모두가 같은 규칙을 공유할 수 있어요. 개인 규칙은 홈 디렉토리(~/.claude/CLAUDE.md)에 두면 모든 프로젝트에 공통 적용돼요. 예를 들어 "항상 한국어로 답변해줘" 같은 개인 선호는 홈 디렉토리에, "이 프로젝트는 TypeScript만 사용" 같은 규칙은 프로젝트 루트에 두는 식이에요. 이렇게 계층 구조로 관리하면 규칙이 많아져도 깔끔하게 유지할 수 있어요.

 

💬 제가 직접 써보니, 규칙이 20개를 넘어가면 오히려 중요한 규칙이 묻히는 느낌이 있었어요. Claude Code가 모든 규칙을 읽긴 하지만, 규칙 사이에 우선순위 충돌이 생길 수 있어요.

핵심 규칙 10~15개 정도로 유지하고, 세부 규칙은 하위 폴더 CLAUDE.md로 분리하는 것을 추천해요. 정기적으로 규칙을 점검해서 더 이상 필요 없는 항목은 과감히 삭제하는 습관도 중요해요.

✍️ 마치며

CLAUDE.md는 복잡한 설정 파일이 아니라, 우리 프로젝트의 규칙을 AI에게 전달하는 간단한 문서예요. 파일 하나 만들어서 핵심 규칙 몇 개만 적어 두면, 매번 반복하던 지시가 사라지고 작업 흐름이 훨씬 매끄러워져요. 지금 바로 프로젝트 루트에 CLAUDE.md를 만들어 보세요 — 규칙 3개로 시작해도 충분해요.

#ClaudeCode #CLAUDE_md #AI코딩 #프로젝트설정 #개발생산성