CLAUDE.md 작성법 총정리: 클로드 md 파일 만들기부터 업무별 예시까지

클로드 코드를 쓰다 보면 같은 설명을 여러 번 하게 될 때가 있습니다. 문서 작성 방식부터 파일 저장 위치, 작업할 때 주의할 점까지 매번 알려줘야 하죠. 특히 새로운 대화를 시작하면 이전에 정해둔 작업 규칙을 다시 설명해야 할 수도 있습니다.

이럴 때 활용할 수 있는 것이 CLAUDE.md(클로드 md)입니다. CLAUDE.md는 클로드 코드가 작업을 시작할 때 읽는 지침 파일로 자주 사용하는 작업 규칙을 미리 정리해 둘 수 있습니다. 개발 프로젝트뿐 아니라 보고서 작성, 자료 조사, 콘텐츠 제작에도 활용할 수 있는데요. 이번 글에서는 CLAUDE.md를 만드는 방법부터 작성법, 실제 업무에 활용할 수 있는 예시까지 살펴봅니다.

클로드 md 파일은 어떻게 만들고 어디에 저장하나요?

CLAUDE.md 사용법은 간단해요. 클로드 코드 설치를 마쳤다면 작업 폴더에 CLAUDE.md 파일을 만들어 보세요. 만드는 방법은 두 가지입니다.

1. 직접 만들기: 작업 폴더에 CLAUDE.md라는 이름으로 텍스트 파일을 만들고 지침 작성. 메모장 등 텍스트 편집기로도 가능

2. /init으로 자동 생성: 클로드 코드 실행 후 /init 입력. 프로젝트 파일을 분석해 CLAUDE.md 초안 생성. 기존 파일이 있다면 덮어쓰지 않고 개선 사항 제안

/init은 개발 프로젝트의 구조나 테스트 명령 등을 분석해 초기 지침을 만드는 데 유용합니다. 보고서나 자료만 있는 업무 폴더라면 파일을 직접 만들거나 클로드에게 필요한 지침을 작성해 달라고 요청해도 됩니다.

파일을 만든 뒤에는 클로드 코드에서 다음 명령어로 확인하고 수정할 수 있습니다.

• /memory: CLAUDE.md 파일 목록 확인 및 편집

• /context all: 현재 불러온 지침 파일 확인. Memory files 목록에서 CLAUDE.md 확인 가능

CLAUDE.md 저장 위치에 따른 차이

CLAUDE.md는 어디에 저장하느냐에 따라 적용 범위가 달라집니다.

예를 들어 보고서 작성과 마케팅 업무에 서로 다른 지침이 필요하다면 각 작업 폴더에 CLAUDE.md를 만들면 됩니다. 어떤 업무에서든 공통으로 적용할 지침은 ~/.claude/CLAUDE.md에 저장할 수 있습니다.

여러 위치에 파일이 있다면 클로드는 각 파일의 지침을 함께 참고합니다. 하위 폴더의 CLAUDE.md는 해당 폴더 안의 파일을 다룰 때 추가로 불러옵니다.

CLAUDE.md 작성법은 무엇인가요?

CLAUDE.md에는 어떤 내용을 적는 것이 좋을까요? 앤트로픽은 클로드에게 반복해서 알려줘야 하는 작업 규칙이나 지침을 적도록 권장합니다.

처음부터 모든 작업 방식을 정리할 필요는 없습니다. 다음 네 가지를 기준으로 시작해 보세요.

• 반복되는 오류와 수정 사항: 클로드가 같은 실수를 반복하는 부분과 올바른 처리 방법

• 결과물 작성 기준: 문서 구성, 분량, 말투, 표기 방식

• 파일 관리 규칙: 원본 자료와 결과물의 위치, 파일 이름

• 작업 시 주의사항: 원본 수정 제한, 파일 삭제 전 확인 등

한 번만 할 일은 대화에서 바로 요청하면 됩니다. 여러 단계로 이어지는 작업 절차는 CLAUDE.md에 길게 적기보다 스킬로 따로 만들어 두는 편이 좋습니다.

CLAUDE.md 예시는 무엇이 있나요?

비개발자 업무 폴더 예시 3가지

보고서 작성부터 리서치, 마케팅까지 업무 유형별로 활용할 수 있는 CLAUDE.md 예시를 준비했습니다. 그대로 복사해 시작하되, 폴더 이름과 작업 규칙은 자신의 업무에 맞게 바꿔 보세요.

예시에 등장하는 raw/, output/, drafts/ 등은 자료와 결과물을 구분하기 위한 폴더 이름으로 실제 사용하는 폴더 구조에 맞게 수정하거나 필요한 폴더를 만들어 사용하면 됩니다.

보고서·문서 작성 폴더

# 보고서 작성 지침

## 폴더
- raw/: 원본 자료. 읽기만 하고 수정하지 않는다
- output/: 완성한 보고서를 저장한다

## 작성 기준
- 독자는 팀장. 요약 3줄, 표, 근거 순서로 쓴다
- 수치에는 출처 파일 이름을 함께 적는다
- 합니다체로 쓴다

리서치·자료 정리 폴더

# 리서치 지침

- 자료마다 출처 URL과 확인 날짜를 적는다
- 확인하지 못한 수치는 '확인 필요'로 표시한다
- 추측한 내용은 사실과 구분해 '추정'으로 표시한다
- 요약은 핵심 3줄과 원문 링크로 정리한다
- 같은 주제의 자료는 notes/주제명.md에 모은다

마케팅·콘텐츠 폴더

# 콘텐츠 작성 지침

- 말투: 해요체
- 문장: 짧고 자연스럽게 작성한다
- 금지 표현: 역대급, 압도적인, 단돈
- 분량: 블로그 2,000자 안팎, 인스타그램 캡션 300자 이내
- 초안은 drafts/ 폴더에 채널명_날짜.md로 저장한다
- 이미지 대체 텍스트(alt)를 함께 제안한다

카파시 가이드라인과 클로드 코드 창시자 사례

CLAUDE.md를 활용하는 방법은 개발자들의 사례에서도 찾아볼 수 있습니다. 대표적으로 카파시 가이드라인과 클로드 코드 개발자 보리스 체르니의 업무 방식을 살펴보겠습니다.

• 카파시 가이드라인: AI 연구자 안드레이 카파시(Andrej Karpathy)가 X에서 지적한 AI 코딩의 문제점을 바탕으로, 다른 개발자가 CLAUDE.md에 적용할 네 가지 원칙을 정리했습니다. 카파시가 직접 작성한 파일은 아닙니다. 작업 전에 충분히 생각하기, 단순하게 만들기, 필요한 부분만 수정하기, 완료 기준을 정하고 결과 검증하기라는 네 가지 원칙을 담고 있습니다. 업무 폴더에서도 "요구사항이 불명확하면 먼저 확인한다", "요청하지 않은 파일은 수정하지 않는다"처럼 활용할 수 있습니다.

• 클로드 코드 창시자 보리스 체르니: 클로드 코드를 만든 보리스 체르니(Boris Cherny)는 동료의 코드 리뷰에서 발견한 내용을 CLAUDE.md에 추가하는 업무 방식을 소개했습니다. 앤트로픽의 각 팀도 CLAUDE.md를 Git 저장소에서 공유하며, 클로드가 저지른 실수와 작업 과정에서 얻은 교훈을 기록해 이후 작업에 활용합니다.

CLAUDE.md는 짧게 시작해 필요할 때마다 추가하세요

CLAUDE.md는 처음부터 완벽하게 작성할 필요가 없습니다. 자주 사용하는 지침 몇 가지만 적어 두고, 작업하면서 필요한 내용을 추가해 보세요. 중복되거나 더 이상 사용하지 않는 지침은 정리하는 것이 좋습니다.

아직 클로드 코드 사용이 익숙하지 않다면, 실제 업무를 지시하고 결과를 확인하는 연습부터 시작해 보세요. 코드트리의 세발자전거에서는 별도 설치나 AI 유료 구독 없이 클로드 코드와 코덱스를 활용한 업무 자동화 과정을 연습할 수 있습니다.

자주 묻는 질문

CLAUDE.md와 AGENTS.md는 무엇이 다른가요?

CLAUDE.md는 클로드 코드에서 사용하는 지침 파일이고, AGENTS.md는 여러 AI 코딩 도구에서 지원하는 공통 지침 파일입니다. Claude Code 2.1.277 버전부터는 기본 설정에서 프로젝트에 CLAUDE.md가 없으면 AGENTS.md를 대신 읽습니다. 두 파일이 모두 있다면 CLAUDE.md를 우선하며, /config에서 설정을 변경해 두 파일을 함께 읽도록 할 수도 있습니다. 두 파일을 함께 활용하는 또 다른 방법은 CLAUDE.md에 @AGENTS.md를 추가하는 것입니다.

CLAUDE.md와 스킬은 어떻게 다른가요?

CLAUDE.md는 클로드가 지속적으로 참고하는 작업 지침이고, 스킬은 특정 작업에 필요할 때 불러오는 지침과 절차입니다. 말투나 파일 저장 위치처럼 공통으로 적용할 규칙은 CLAUDE.md에 적습니다. 월간 보고서 작성처럼 여러 단계로 이어지는 반복 업무는 스킬로 만들어 두면 CLAUDE.md를 간결하게 유지할 수 있습니다.

CLAUDE.md가 적용되지 않으면 어떻게 하나요?

먼저 /context all을 입력해 Memory files 목록에 CLAUDE.md가 있는지 확인하세요. 목록에 없다면 파일을 저장한 위치를 확인합니다. 작업 폴더와 상위 폴더의 지침은 시작할 때 읽지만, 하위 폴더의 지침은 해당 폴더의 파일을 다룰 때 추가로 불러옵니다.

파일이 정상적으로 불러와졌는데도 지침을 따르지 않는다면 모호하거나 서로 충돌하는 지시가 있는지 확인하세요. CLAUDE.md는 작업을 안내하는 지침이므로 모든 규칙이 반드시 지켜지는 것은 아닙니다.