CLAUDE.md 작성법: Claude Code에 프로젝트 규칙을 알려 주는 방법

핵심 요약: CLAUDE.md에는 매번 다시 설명하는 프로젝트 규칙을 짧고 구체적으로 적으세요. 작업 명령, 수정 시 주의점, 완료 보고 기준처럼 실제로 확인할 수 있는 내용이 좋습니다. 모든 문서를 복사해 넣기보다 필요한 규칙을 골라 쓰고, 프로젝트가 바뀌면 파일도 함께 고쳐야 합니다.

1. CLAUDE.md에 담을 내용 고르기

공식 문서는 CLAUDE.md를 프로젝트나 사용자 작업에 대한 지속적인 지침을 적는 Markdown 파일로 설명합니다. 프로젝트 파일 위치와 읽히는 범위는 메모리 공식 문서에서 확인할 수 있습니다. 프로젝트 루트의 CLAUDE.md를 시작점으로 삼을 수 있습니다.

좋은 후보는 새 작업마다 반복해서 말하는 내용입니다. 예를 들어 “기존 사용자가 수정한 파일을 보존한다”, “이 프로젝트의 날짜는 한국 시간으로 표시한다”, “화면 문구는 용어표의 표현을 사용한다”처럼 코드만 읽어서는 의도를 알기 어려운 규칙입니다. 잠깐만 필요한 한 작업의 세부 요구는 대화에서 전달하고, 계속 적용할 규칙을 파일에 남기세요.

2. 짧은 작성 예시로 시작하기

아래는 가상의 할 일 관리 웹 프로젝트를 위한 예시입니다. 명령과 경로는 실제 저장소에 맞게 바꾸어야 합니다. 그대로 붙여 넣었다고 검증 환경이 생기거나 테스트가 실행되는 것은 아닙니다.

# 프로젝트 규칙
## 목적
한국어 사용자를 위한 개인 할 일 관리 화면이다.

## 작업 방식
- 작업 시작 전 기존 변경 사항을 확인하고 보존한다.
- 요청한 기능과 관계없는 파일은 수정하지 않는다.
- 화면 문구는 docs/terms.md의 용어를 따른다.

## 검증
- package.json에서 실제 실행 가능한 검증 명령을 확인한다.
- 관련 검증을 실행하고 명령과 결과를 보고한다.
- 화면 동작 변경은 정상 입력과 빈 입력을 함께 확인한다.

## 완료 보고
- 변경 파일과 이유를 간단히 정리한다.
- 실행하지 않은 검증은 실행했다고 쓰지 않는다.
- 남은 문제와 확인하지 못한 조건을 명시한다.

이 예시의 핵심은 문장이 검사 가능한 행동으로 연결된다는 점입니다. “완벽하게 만들기”는 완료 여부를 판단하기 어렵지만 “빈 입력에서 안내가 보이는지 확인하기”는 비교할 대상이 있습니다. 프로젝트에 용어표가 없다면 해당 규칙을 지우거나 실제 문서를 먼저 정리하세요.

3. 실행 명령은 확인한 것만 적기

다른 프로젝트의 예시를 보고 npm test나 npm run build를 그대로 적으면 실제로 없는 명령이 될 수 있습니다. 설정 파일과 프로젝트 안내에서 명령을 확인하고, 어떤 작업을 검증하는지 함께 기록하세요. 빠른 문법 검사와 전체 통합 테스트가 서로 다른 일을 한다면 한 줄씩 목적을 설명하면 됩니다.

예를 들어 “UI 문구 수정 후에는 지정한 화면을 열어 줄바꿈을 확인한다”와 “계산 로직 수정 후에는 경계값 사례를 확인한다”는 검토 방식이 다릅니다. 모든 변경에 같은 긴 작업을 반복시키기보다 해당 변경에 필요한 검증을 선택하는 기준을 적어 보세요. 실제 실행 여부와 결과는 매 작업의 보고에서 확인합니다.

4. 지침과 권한 설정의 역할 구분하기

“실제 고객 파일은 열지 않는다”라는 문장은 의도를 설명하는 지침입니다. 도구 접근을 기술적으로 제한해야 한다면 권한 설정을 따로 다루어야 합니다. Anthropic 문서는 CLAUDE.md를 강제 설정으로 취급하지 않는다고 설명하고, 도구 권한은 별도의 규칙으로 관리합니다. 설정 방법은 공식 권한 안내를 참고하세요.

또한 공개 저장소에 올리는 CLAUDE.md에 암호나 API 키를 쓰지 마세요. 필요한 값의 이름과 찾는 절차를 설명하되 실제 비밀값을 붙이지 않는 방식으로 작성합니다. “환경 변수 X가 필요하다”와 “X의 실제 값을 기록한다”는 다른 내용입니다. 규칙 파일을 공유할 범위도 확인하세요.

5. 규칙이 늘어날 때 정리하는 방법

오래된 명령, 중복 표현, 서로 충돌하는 규칙부터 지우거나 고치세요. “새 코드에는 A 라이브러리를 쓴다”와 “A는 더 이상 쓰지 않는다”가 함께 있으면 무엇을 따라야 할지 불명확합니다. 규칙을 추가할 때는 왜 필요한지와 어떤 작업에 적용되는지를 읽는 사람이 알 수 있게 적으세요.

파일이 잘 적용되는지 확인할 때는 Claude에게 현재 작업에 적용할 지침과 근거 경로를 정리하도록 요청하고 직접 비교할 수 있습니다. 다만 AI가 규칙을 설명했다는 사실만으로 모든 작업이 그 규칙을 지킨다고 볼 수는 없습니다. 완료 후 변경 파일과 검증 결과를 계속 확인해야 합니다.

정기 검토에는 간단한 세 질문을 쓰세요. “현재 프로젝트에서 가능한 명령인가?”, “다른 규칙과 충돌하는가?”, “답이나 변경 결과로 준수 여부를 확인할 수 있는가?” 세 질문에 답하지 못하는 문장은 더 구체적으로 바꾸거나 개별 작업 설명으로 옮길 후보입니다.

6. 넣을 규칙과 개별 대화에 남길 조건 구분하기

규칙 파일을 모든 작업의 기록장처럼 쓰면 지나간 요구와 현재 요구가 섞일 수 있습니다. “프로젝트에서 언제나 필요한 약속”과 “이번 요청에만 필요한 선택”을 나누어 보세요. 예를 들어 이번 화면의 버튼 색상은 작업 요청에 쓰고, 모든 화면에서 따라야 하는 용어표는 지속 지침에 넣을 수 있습니다.

규칙을 하나 추가할 때는 “이 프로젝트에서 반복해서 발생하는 문제인가?”를 생각하세요. 한 번의 답이 마음에 들지 않아 모든 작업에 긴 절차를 강제하면 작은 수정도 불필요하게 복잡해질 수 있습니다. 문제가 반복될 때 적용 조건을 함께 적는 편이 관리하기 좋습니다.

7. 적용 범위를 이해하고 파일을 나누기

현재 공식 메모리 문서는 사용자 지침, 프로젝트 지침, 하위 영역 지침을 구분합니다. 작업 디렉터리와 그 위 경로의 CLAUDE.md는 시작할 때 읽히며, 하위 폴더 지침은 관련 파일을 읽는 과정에서 포함될 수 있습니다. 여러 지침은 단순히 하나로 교체되는 파일이 아니라 함께 문맥에 들어가므로 충돌 여부를 살펴봐야 합니다.

[가상 배치 예시]
my-project/
  CLAUDE.md                 공통 약속
  docs/
    CLAUDE.md               문서 표현과 출처 기록 규칙
  src/
    ui/
      CLAUDE.md             화면 문구와 표시 검토 규칙

이 배치는 반드시 따라야 하는 공식 폴더 구조가 아니라 역할을 설명한 예시입니다. 작은 프로젝트는 루트 파일 하나로 충분할 수 있습니다. 나누려면 루트에는 모든 작업의 공통 약속을 두고 하위 파일에는 그 영역에만 필요한 차이를 적으세요. 같은 검증 명령을 세 파일에 복사하면 다음에 명령이 바뀔 때 모두 고쳐야 합니다.

“현재 적용되는 지침 경로와 이번 파일에 관계있는 규칙을 나열해 줘”라고 요청해 의도한 파일을 읽는지 살펴볼 수 있습니다. 파일이 빠졌다면 내용부터 길게 늘리기보다 작업 위치와 파일 배치를 비교하세요. 답변이 지침을 언급했다는 사실과 실제 변경이 지침을 지켰다는 사실은 따로 검토해야 합니다.

8. 추상적인 규칙을 검사 가능한 문장으로 바꾸기

오른쪽 문장은 가상 프로젝트의 요구를 정리한 것이므로 그대로 적용하기 전에 자기 프로젝트의 정상 동작을 정해야 합니다. 예를 들어 결과 0개일 때 안내를 보여 주는 것이 모든 앱에서 같은 정답은 아닙니다. 규칙 파일은 제품의 결정을 기록하는 곳이지, AI가 임의로 결정을 확정하게 하는 곳이 아닙니다.

현재 CLAUDE.md를 검토해 주세요. 파일은 수정하지 마세요.
각 규칙에 대해 다음을 정리하세요.
- 적용할 작업의 종류
- 지켰는지 판단할 결과나 근거
- 코드나 설정과 충돌하는 부분
- 이번 작업만의 요구가 섞인 부분
모호한 규칙에는 구체화한 문장 초안을 제안하세요.
근거가 없는 실행 명령과 경로는 만들지 마세요.

9. 가상 규칙 충돌을 정리하는 예시

가상의 루트 지침에는 “화면 문구는 모든 경우에 영어”, UI 지침에는 “새 화면 문구는 한국어”라고 적혀 있다고 가정해 보겠습니다. 가까운 파일에 적혔다는 이유만으로 팀의 결정을 대신 확정하기보다, 어떤 작업에 어떤 규칙을 적용하려는지 확인해야 합니다. 적용 범위를 명시하면 모순이 줄어듭니다.

[수정 전 가상 지침]
루트: 화면 문구는 영어로 쓴다.
UI 폴더: 새 화면은 한국어로 쓴다.

[작성자가 제안한 정리 예시]
루트: 기존 화면 문구는 이번 작업에서 번역하지 않는다.
UI 폴더: 새 한국어 화면의 문구는 docs/terms.md를 따른다.
대상 화면 목록은 개별 작업 요청에서 지정한다.

이 수정안은 기존 화면 유지와 새 화면 작성이라는 서로 다른 대상을 구분한 예시입니다. 실제 프로젝트의 결정이 “모든 화면을 한국어로 전환”이라면 전혀 다른 규칙이 필요합니다. 정리하기 전 제품의 선택을 확인하고, 그 선택을 지침으로 옮겨야 합니다.

/init로 만든 초안을 읽을 때

공식 문서의 /init은 시작용 지침을 만들 때 사용할 수 있습니다. 생성 초안에서는 발견한 명령이 실제 설정에 있는지, 파일 구조를 너무 길게 복제하지 않았는지, 프로젝트가 아닌 개인 취향을 공통 규칙으로 쓰지 않았는지 살펴보세요. 자동 생성됐다는 이유로 승인된 팀 규칙이 되는 것은 아닙니다.

/init 초안에서 다음 부분을 다시 검토해 주세요.
1. 명령은 설정 파일의 근거 위치를 함께 적으세요.
2. 일반적인 설명과 이 프로젝트만의 주의점을 구분하세요.
3. 실행하지 않은 명령을 성공한 것으로 쓰지 마세요.
4. 서로 다른 폴더 지침이 충돌하면 목록으로 보여 주세요.
5. 제안은 먼저 검토 가능한 초안으로 제시하세요.

명령이나 저장 형식이 바뀐 작업을 마친 뒤에는 관련 지침도 찾아보세요. 변경한 코드의 설명이 지침과 다른 상태로 남으면 다음 작업에서 잘못된 전제를 다시 사용할 수 있습니다. 규칙의 개수보다 현재 코드·팀 결정·검증 절차가 서로 맞는지가 중요합니다.

자주 묻는 질문과 실수 해결

자동으로 만들 수 있나요? 공식 문서에는 /init으로 시작용 파일을 만드는 방법이 나와 있습니다. 생성된 내용도 실제 명령과 팀 규칙에 맞는지 검토하세요. 길수록 좋은가요? 필요한 지침을 분명하게 유지하는 것이 목적입니다. 규칙을 무시하는 것 같다면요? 파일 위치와 적용 범위, 모순된 지침을 확인하고 실제 위반 내용을 구체적으로 비교하세요.

공식 출처와 확인일

• How Claude remembers your project
• Configure permissions

공식 문서 확인일: 2026년 10월 3일. 화면과 제공 조건은 이후 바뀔 수 있습니다.