Claude Code 프로젝트별 설정 파일 CLAUDE.md 작성법 가이드

💡 TL;DR

CLAUDE.md는 Claude Code에게 "이 프로젝트는 이런 규칙으로 일해줘"라고 미리 알려주는 안내문입니다. 프로젝트 폴더에 이 파일 하나만 잘 써두면 매번 같은 설명을 반복하지 않아도 되고, 코드 스타일·말투·금지사항까지 일관되게 유지됩니다. 작성에 30분~1시간 정도면 충분합니다.

Claude Code를 며칠 써보면 한 가지 답답한 순간이 옵니다. "이 프로젝트는 한국어로 답해줘", "이 폴더 건드리지 마", "함수 이름은 카멜케이스로" 같은 똑같은 잔소리를 매번 새 대화창마다 반복해야 한다는 점입니다. 이걸 한 방에 해결해주는 게 바로 CLAUDE.md 파일이고, 이 글에서는 claude.md 작성법을 비개발자도 따라할 수 있게 정리했습니다. 개발 경험이 없어도, 메모장에 글 쓸 줄만 알면 충분히 만들 수 있습니다.

저도 처음엔 "이런 파일 굳이 필요한가?" 싶었는데, 한 번 제대로 써놓고 나서는 작업 효율이 체감상 두 배 이상 올랐습니다. 일종의 "사수에게 인수인계 문서 넘겨주는" 느낌이라고 보면 됩니다.

CLAUDE.md가 정확히 무엇인가

CLAUDE.md는 Claude Code가 작업을 시작할 때 자동으로 먼저 읽는 프로젝트별 안내 문서입니다. Anthropic 공식 문서에 따르면 Claude Code는 실행 시 현재 작업 폴더와 상위 폴더에 있는 CLAUDE.md를 자동 인식해서 시스템 프롬프트(AI에게 미리 주는 기본 지시문)에 포함시킵니다.

쉽게 비유하자면 이렇습니다. 새 직원이 출근했을 때 책상 위에 놓여있는 "업무 매뉴얼"이라고 보면 됩니다. 매번 "우리 회사는 이렇게 일해요"를 말로 설명할 필요 없이, 매뉴얼만 읽히면 끝나는 거죠.

여기에 보통 들어가는 내용은 이렇습니다.

항목	예시
프로젝트 개요	"이건 블로그 자동 생성 도구다"
사용 언어/프레임워크	"Python 3.11, FastAPI 사용"
코드 스타일 규칙	"함수 이름은 snake_case로"
응답 언어	"모든 답변은 한국어로"
금지사항	"main 브랜치에 직접 커밋 금지"
자주 쓰는 명령어	"테스트는 pytest -v로 실행"

확장자가 .md인 건 마크다운(Markdown, 글자 앞에 #이나 - 같은 기호로 제목·목록을 표시하는 간단한 문서 양식)이라는 뜻인데, 그냥 메모장에서 글을 쓰고 파일명만 CLAUDE.md로 저장하면 됩니다.

파일을 어디에 둬야 하는지

CLAUDE.md는 놓는 위치에 따라 적용 범위가 달라집니다. 이게 의외로 중요합니다.

[홈 폴더]
└── ~/.claude/CLAUDE.md          ← 모든 프로젝트에 공통 적용 (전역)

[프로젝트 폴더]
└── my-project/
    ├── CLAUDE.md                ← 이 프로젝트에만 적용 (프로젝트별)
    └── src/
        └── CLAUDE.md            ← src 폴더 안에서만 적용 (하위 폴더별)

세 가지 위치를 정리하면 다음과 같습니다.

위치	적용 범위	추천 용도
~/.claude/CLAUDE.md	내 컴퓨터의 모든 작업	"한국어로 답해줘", "줄바꿈은 LF로" 같은 개인 취향
프로젝트 루트 CLAUDE.md	해당 프로젝트 전체	프로젝트 규칙, 사용 라이브러리, 폴더 구조
하위 폴더 CLAUDE.md	그 폴더 안 작업	"이 폴더는 테스트 코드만", "여기는 손대지 마"

루트(root)는 그 프로젝트의 가장 바깥 폴더라고 보면 됩니다. 보통은 프로젝트 루트에 하나만 둬도 충분하고, 협업하는 사람이 많거나 폴더 구조가 복잡할 때 하위 폴더에 추가합니다.

💡 팁: 팀 프로젝트라면 CLAUDE.md를 git(코드 변경 이력을 관리해주는 도구)에 같이 올려두세요. 팀원 모두가 같은 규칙으로 Claude Code를 쓸 수 있습니다.

좋은 CLAUDE.md의 6가지 구성 요소

작성할 때 빠지면 안 되는 핵심 항목 6가지입니다. 글 작성 시점 기준 Anthropic이 공식 예시로 제시한 구조와 제 경험을 합쳐 정리했습니다.

1. 프로젝트 개요 (Project Overview)

이 프로젝트가 뭘 하는 건지 2~3줄로 적습니다. AI가 이 한 문단만 봐도 "아, 이런 맥락이구나"를 잡을 수 있게요.

## Project Overview
이 프로젝트는 사용자가 입력한 키워드로 블로그 초안을 생성하는 CLI 도구입니다.
주요 사용자는 1인 운영 블로거이며, OpenAI API와 Anthropic API를 모두 지원합니다.

2. 기술 스택 (Tech Stack)

어떤 언어·라이브러리를 쓰는지 알려줍니다. 이게 없으면 Claude가 엉뚱한 문법으로 코드를 쓸 수 있습니다.

## Tech Stack
- Python 3.11
- FastAPI 0.110+
- SQLite (운영 DB는 PostgreSQL)
- 패키지 관리: uv

3. 자주 쓰는 명령어 (Common Commands)

테스트·실행·빌드 명령을 적어두면 Claude가 작업 후 알아서 검증까지 해줍니다.

## Common Commands
- 개발 서버 실행: `uv run fastapi dev`
- 테스트: `uv run pytest -v`
- 린트 검사: `uv run ruff check .`

4. 코드 스타일 규칙

들여쓰기, 네이밍, 주석 스타일을 명시합니다. 사람마다 취향이 다른 부분이라 명시 안 하면 매번 다르게 나옵니다.

5. 금지사항 (Do Not)

이게 의외로 가장 중요합니다. "하지 말 것"을 명확히 적어주는 거죠.

## Do Not
- `main` 브랜치에 직접 커밋하지 말 것
- `legacy/` 폴더는 절대 수정하지 말 것
- 외부 라이브러리를 새로 추가하기 전 반드시 확인 요청

6. 톤·언어 설정

## Communication
- 모든 응답은 한국어로
- 코드 주석은 영어로
- 불확실하면 추측하지 말고 질문할 것

비개발자를 위한 실전 예시

코딩을 안 하시는 분이라도 "AI에게 글쓰기를 시키는 프로젝트"는 충분히 만들 수 있습니다. 예를 들어 블로그 글 초안을 자동으로 만드는 폴더를 운영한다고 가정하면 이런 식으로 적을 수 있습니다.

# CLAUDE.md

## 프로젝트 개요
이 폴더는 IT 블로그 초안을 작성하는 작업 공간입니다.
주제별 마크다운 파일을 모아두고, Claude Code가 새 글을 만들거나
기존 글을 다듬는 작업을 합니다.

## 글쓰기 규칙
- 모든 글은 "~합니다"체로 작성
- 문단당 4~6줄을 넘기지 않기
- 영어 약어는 첫 등장 시 한국어 풀이를 괄호로 추가
- 이모지는 본문에 1~2개까지만

## 폴더 구조
- `drafts/`: 작성 중인 초안
- `published/`: 발행 완료한 글 (수정 금지)
- `references/`: 참고 자료

## 하지 말 것
- `published/` 폴더의 파일은 절대 수정하지 말 것
- 출처가 불분명한 통계 인용 금지
- 광고성 표현("미친 도구", "역대급") 사용 금지

## 작업 방식
- 새 초안은 `drafts/YYYY-MM-DD-제목.md` 형식으로 저장
- 글 마지막에 작성일과 예상 독자층을 메타 정보로 추가

이 정도만 적어둬도 Claude Code에게 "오늘 ChatGPT 활용법 글 초안 써줘"라고만 하면 위 규칙을 모두 지킨 결과물이 나옵니다. 매번 "한국어로 써줘, 4~6줄 단락으로 써줘"를 입력할 필요가 없어집니다.

작성 후 확인하는 방법

파일을 만들었으면 제대로 인식되는지 확인해봐야겠죠. Claude Code 실행 후 이렇게 물어보면 됩니다.

현재 적용된 CLAUDE.md 내용을 요약해줘

Claude가 파일 내용을 요약해서 답하면 정상 작동입니다. 만약 "CLAUDE.md를 찾을 수 없다"고 하면 다음을 확인하세요.

• [ ] 파일명이 정확히 CLAUDE.md인지 (대소문자 주의)
• [ ] 확장자가 .txt로 잘못 저장되지 않았는지
• [ ] Claude Code를 실행한 폴더가 그 파일이 있는 폴더인지
• [ ] 파일이 비어있지 않은지

⚠️ 주의: 윈도우 메모장은 기본적으로 .txt 확장자를 자동으로 붙입니다. 파일명을 큰따옴표로 감싸 "CLAUDE.md"로 저장하거나, VS Code 같은 편집기를 쓰는 게 안전합니다.

자주 막히는 부분

직접 써본 경험과 커뮤니티 후기를 종합해 자주 겪는 문제 세 가지입니다.

1. 너무 길게 쓰면 오히려 손해

CLAUDE.md 내용은 매 요청마다 토큰(AI가 글을 처리하는 단위)으로 소비됩니다. 1000줄짜리 매뉴얼을 넣으면 그만큼 응답 비용도 늘고 답변 속도도 느려집니다. 경험상 300~500줄 이내가 적정선입니다. 자주 안 쓰는 정보는 별도 문서로 빼고 "자세한 건 docs/style.md 참고"라고 링크만 걸어두는 게 낫습니다.

2. 규칙끼리 충돌하는 경우

"간결하게 써라"와 "모든 함수에 상세 주석을 달아라"가 같이 있으면 Claude는 헷갈립니다. 작성 후 한 번 읽어보면서 모순되는 지시가 없는지 점검하세요.

3. 전역 파일과 프로젝트 파일이 둘 다 있을 때

~/.claude/CLAUDE.md(전역)와 프로젝트 CLAUDE.md가 충돌하면, 일반적으로 더 가까운 위치(프로젝트별)가 우선됩니다. 다만 두 내용이 단순히 합쳐져 들어가는 구조라 모순이 생기면 결과가 들쭉날쭉할 수 있습니다. 전역에는 정말 개인 취향(언어, 톤)만 두고 프로젝트별 규칙은 프로젝트 파일에 몰아두는 걸 권장합니다.

마무리

CLAUDE.md는 한 번 잘 써두면 두고두고 시간을 아껴주는 투자입니다. 처음부터 완벽하게 쓰려고 하지 말고, 일단 짧게 시작해서 작업하다가 "이 잔소리 또 하네" 싶을 때마다 한 줄씩 추가하는 방식이 현실적입니다. 저도 지금 쓰는 파일은 처음 만든 후 두 달 동안 수십 번 고친 결과물입니다.

오늘 당장 해볼 만한 것은 이 정도입니다. 메모장을 열어서 위 6가지 항목 중 프로젝트 개요·금지사항·톤 설정 세 개만 먼저 적고 CLAUDE.md로 저장해보세요. 나머지는 쓰면서 채우면 됩니다. Claude Code의 진짜 가치는 도구 자체보다 "내 작업 방식을 가르치는 과정"에서 나옵니다.