[클로드 시리즈_19] CLAUDE.md

CLAUDE.md 한 파일로 AI에게 '우리 회사 룰'을 통째로 가르치는 법

매번 "한국어로 답해줘", "원본 파일은 건드리지 마", "보고체로 써줘"를 반복 입력하고 계신가요? CLAUDE.md 파일 하나면 Claude Code가 매 세션마다 우리 팀의 규칙을 자동으로 기억하고 시작합니다. 단 4줄로 끝나는 세팅, 지금 바로 만들어 보세요.

핵심 결론 먼저

CLAUDE.md는 Claude Code 에이전트에게 프로젝트 전용 행동 지침을 자동 로딩시키는 마크다운 파일입니다. 프로젝트 루트에 이 파일 하나만 두면, 매 세션이 시작될 때마다 Claude가 자동으로 읽고 우리 팀의 코딩 컨벤션, 답변 스타일, 금지 사항을 기본 행동으로 삼습니다. "매번 같은 지시를 반복하는 시간"을 0으로 만드는 방법입니다.

1. CLAUDE.md란 무엇인가 — AI에게 주는 '사내 매뉴얼'

CLAUDE.md는 특정 프로젝트나 환경에 맞춰 Claude Code 에이전트의 행동 방식을 제어하는 핵심 설정 파일입니다.

매번 AI에게 "나는 이런 규칙을 써", "이 폴더에서는 이렇게 코딩해 줘"라고 반복해서 설명할 필요가 없습니다. 이 파일 하나면 AI가 프로젝트의 맥락을 완벽하게 숙지하고 작업을 시작합니다.

비유하자면 새로 입사한 직원에게 건네는 '사내 업무 매뉴얼'과 같습니다. 일을 시킬 때마다 회사 규칙을 처음부터 설명할 필요 없이, 매뉴얼 한 권을 미리 읽혀두는 것이죠.

2. 3가지 핵심 개념 — 이것만 알면 끝

CLAUDE.md를 제대로 활용하려면 아래 3가지 개념을 먼저 이해해야 합니다.

1) 매 세션 자동 로딩

프로젝트 최상단(Root) 경로에 CLAUDE.md라는 마크다운 파일을 생성해 두기만 하면 됩니다. Claude Code를 실행하여 새로운 세션이 열릴 때마다 AI가 이 파일을 자동으로 읽어들여 기본 행동 지침으로 삼습니다.

2) 정교한 2계층 적용 시스템

지시문은 적용되는 범위에 따라 2단계로 나뉘어 체계적으로 작동합니다. (뒤로 갈수록 좁은 범위입니다)

• 루트 폴더: 루트 폴더에 있는 CLAUDE.md → 프로젝트 전체에 적용
• 개별 폴더: 개별 폴더에 있는 CLAUDE.md → 해당 폴더 작업 시에만 추가 적용

3) 마크다운 기반 단순 구조

복잡한 환경 설정 파일이 아닌, 일반 마크다운 문법으로 작성하는 텍스트 파일입니다. 누구나 메모장으로 열어서 수정할 수 있습니다.

3. 실전 가이드 — 단 두 줄로 끝내는 CLAUDE.md 만들기

"복잡한 환경 설정 파일은 필요 없습니다. 터미널 명령어 단 두 줄이면 프로젝트 전용 AI 지시문 세팅이 완료됩니다."

방법 ① 터미널 명령어 2줄로 생성 및 열기

현재 작업 중인 프로젝트 폴더의 터미널(PowerShell 등)에서 아래와 같이 입력해 보세요.

> /init
> notepad CLAUDE.md

1. /init: 이 명령어를 입력하면 해당 폴더에 CLAUDE.md 파일이 즉시 자동 생성됩니다.
2. notepad CLAUDE.md: 생성된 파일을 메모장(Notepad)으로 엽니다. (VS Code 등 본인이 사용하는 다른 에디터 명령어를 사용하셔도 무방합니다.)

방법 ② 프롬프트로 AI에게 직접 작성시키기 (🔥 추천)

빈 파일에 직접 규칙을 적어 내려가는 것보다 더 스마트한 방법은, AI에게 자신의 가이드라인을 직접 작성하도록 지시하는 것입니다.

실전 프롬프트 예시

"이 폴더에 CLAUDE.md를 만들어 줘. 앞으로 답변은 무조건 한국어로 하고, 원본 데이터 파일은 절대 수정하지 마. 그리고 새로 생성하는 파일에는 항상 '_new'이라는 접미사를 붙이도록 설정해 줘."

실무 적용 예시 (5줄 구성)

위와 같은 명령이나 프롬프트를 통해 완성된 CLAUDE.md 파일은 보통 아래와 같이 직관적인 마크다운 리스트 형태로 구성됩니다.

# 답변 원칙
- 한국어로 답변
- 원본 데이터는 수정 금지, _new 접미사로 새 파일 생성
- 표는 마크다운(Markdown) 표 형식으로 출력

단 4줄의 명확한 규칙만으로도, 이후 AI가 이 프로젝트 내에서 작업할 때 발생할 수 있는 치명적인 실수(원본 훼손 등)를 완벽하게 차단하고 일관된 결과물을 얻을 수 있습니다.

4. 직무 및 시나리오별 CLAUDE.md 작성 템플릿

"직무가 다르면 AI에게 내리는 기본 지침도 달라져야 합니다."

소속된 부서나 현재 진행 중인 작업의 성격에 맞춰 CLAUDE.md의 내용을 어떻게 구성하면 좋을지, 대표적인 4가지 실무 시나리오를 통해 알아봅니다.

🧪 1. 데이터 분석 및 실험 환경

핵심 목표: 원본 데이터의 철저한 보호 및 무결성 유지

연구나 데이터 분석을 진행할 때 가장 치명적인 실수는 AI가 원본 데이터를 덮어쓰는 것입니다. 이를 원천 차단하는 지시가 필수적입니다.

권장 지시문 예시:

• "어떠한 경우에도 원본 데이터 파일(.csv, .xlsx 등)은 수정하거나 덮어쓰지 말 것."
• "가공된 데이터는 반드시 지정된 랩실(Lab) 표기 규칙과 네이밍 컨벤션을 따라 별도의 파일로 저장할 것."

💻 2. 개발 및 시뮬레이션 환경

핵심 목표: 일관된 코딩 스타일 및 컨벤션 강제

여러 개발자가 협업하는 것처럼, AI가 작성하는 코드도 팀의 표준 컨벤션을 따르도록 통제해야 합니다.

권장 지시문 예시:

• "Python 코드 작성 시 반드시 f-string 포맷을 사용할 것."
• "코드 포매팅은 Black 스타일을 엄격하게 적용할 것."
• "모든 코드의 주석(Comment)은 반드시 한국어로 상세히 작성할 것."

🏢 3. 기획 및 행정 실무 환경

핵심 목표: 즉시 보고 가능한 정형화된 문서 포맷팅

행정 업무에서는 서술형 텍스트보다 한눈에 들어오는 보고서 형태의 결과물이 필요합니다. AI의 출력 스타일을 '보고체'로 고정하세요.

권장 지시문 예시:

• "모든 답변은 공공기관/사내 표준 보고서 포맷(보고체)을 사용할 것."
• "줄글을 피하고 반드시 개조식(Bullet points)으로 요약할 것."
• "가독성을 위해 한 줄의 길이는 50자를 넘지 않도록 작성할 것."

5. 글로벌 표준이 된 'Andrej Karpathy'의 CLAUDE.md 가이드라인

전 테슬라 AI 디렉터이자 OpenAI 공동 창업자인 안드레이 카파시(Andrej Karpathy)의 메시지를 바탕으로, 한 개발자가 정리하여 단 며칠 만에 10만 개의 GitHub 스타를 받은 레포지토리가 있습니다. LLM 코딩 어시스턴트(Claude Code 등)가 흔히 저지르는 실수를 줄이기 위한 행동 지침으로, 속도보다는 '신중함'을 우선시하는 것이 핵심입니다.

🚨 기존 AI 코딩의 3가지 고질병

AI는 코딩 능력이 부족한 것이 아니라, 너무 빠르고 자신감 있게 짜다 보니 '브레이크'가 없어서 문제가 발생합니다.

1. 잘못된 가정 (묻지마 코딩): 사용자에게 되묻지 않고 임의로 해석하여 마음대로 작업을 시작해 버림.
2. 코드 부풀리기: 몇 줄이면 끝날 문제를 불필요한 추상화를 넣어 수백 줄의 복잡한 코드로 짜거나, 더 이상 안 쓰는 코드를 방치함.
3. 무단 수정 (사이드 이펙트): 요청하지 않은 주변 코드, 주석, 서식 등을 마음대로 고쳐버림.

① 코딩 전 생각하기 (Think Before Coding)

"추측하지 마라. 혼란을 숨기지 마라. 장단점(Tradeoff)을 드러내라."

코드를 구현하기 전에 AI가 지켜야 할 원칙입니다.

• 가정 명시: 실행 전 가정한 내용을 명확히 밝힐 것.
• 질문 우선: 불확실하거나 이해가 안 되는 부분이 있다면 작업을 멈추고 무엇이 헷갈리는지 질문할 것.
• 선택지 제공: 여러 가지 해석이 가능하다면 임의로 하나를 선택하지 말고 모두 제시할 것.
• 대안 제시: 더 간단한 접근 방식이 있다면 말하고, 필요하다면 사용자의 요청에 반박할 것.

② 단순함 최우선 (Simplicity First)

"문제를 해결하는 최소한의 코드. 추측성 코드는 작성하지 마라."

AI의 '코드 부풀리기'를 막기 위한 원칙입니다.

• 오버엔지니어링 금지: 요청받은 기능 외의 추가 기능 금지. 일회용 코드에 불필요한 추상화 금지.
• YAGNI 원칙 준수: 요청받지 않은 '유연성'이나 '설정 가능성'을 추가하지 말 것. 불가능한 시나리오에 대한 에러 핸들링도 금지.
• 코드 다이어트: 200줄로 작성한 코드를 50줄로 줄일 수 있다면 다시 작성할 것.
• 자가 점검: "시니어 엔지니어가 보기에 너무 복잡하다고 얘기할까?"라는 질문에 '그렇다'면 무조건 단순화할 것.

      →  YAGNI("You Ain't Gonna Need It", 당신은 그것이 필요 없을 것이다)는 소프트웨어 개발에서 "지금 당장 필요하지 않은 기능은 절대로 미리 만들지 마라"는 원칙

③ 수술하듯 정밀한 변경 (Surgical Changes)

"반드시 필요한 부분만 만져라. 본인이 어지른 것만 치워라."

사이드 이펙트와 불필요한 수정을 방지하기 위한 원칙입니다.

• 기존 코드 존중: 인접한 코드, 주석, 포맷팅을 마음대로 "개선"하지 말 것. 고장 나지 않은 것을 리팩토링하지 말 것. 기존 스타일이 본인 방식과 달라도 무조건 따를 것.
• 사망 코드(Dead Code) 처리 규칙:
  • 관련 없는 기존 사망 코드를 발견하면 지우지 말고 언급만 할 것.
  • 단, 자신의 코드 변경으로 인해 사용되지 않게 된(Orphan) 임포트(imports)/변수/함수는 삭제할 것.
• 최종 테스트: 변경된 모든 코드 라인은 사용자의 요청과 직접적으로 연결(Trace)되어야 함.

④ 목표 중심적 실행 (Goal-Driven Execution)

"성공 기준을 정의하라. 검증될 때까지 반복하라."

모호한 지시를 검증 가능한 목표로 전환하여 스스로 실행하게 만드는 원칙입니다.

검증 가능한 목표로 전환 예시:

모호한 지시	검증 가능한 목표로 전환
"검증 추가해 줘"	"유효하지 않은 입력에 대한 테스트를 작성하고, 통과하게 만들어"
"버그 수정해 줘"	"버그를 재현하는 테스트를 작성하고, 통과하게 만들어"
"리팩토링해 줘"	"리팩토링 전후에 테스트가 통과하는지 확인해"

명확한 기준의 힘: 성공 기준이 명확하면 AI가 독립적으로 루프를 돌며 작업할 수 있지만, "되게 만들어 줘" 같은 약한 기준은 끊임없는 추가 설명이 필요합니다.

6. 내 프로젝트에 카파시 가이드라인 적용하는 3가지 방법

총 3가지 방법 중 본인에게 편한 방식을 선택하여 적용할 수 있습니다.

방법 1: VS Code 스킬(Skill)로 등록하여 사용

터미널에서 Claude Code 실행 후, 레포지토리에 안내된 스킬 추가(add) 및 설치(install) 명령어를 입력합니다.

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

사용 시 챗에 /ka를 입력하면 명시적으로 카파시 가이드라인 스킬이 로드됩니다.

방법 2: 터미널로 파일 직접 다운로드

터미널 명령어를 통해 CLAUDE.md 파일을 전역(Global)이나 프로젝트 단위로 다운로드합니다.

전역 적용:

curl -o ~/.claude/CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

프로젝트 단위 적용:

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

⚠️ 주의: 기존 프로젝트에 CLAUDE.md 파일이 이미 있다면 덮어씌워질 수 있으니 꼭 확인하세요.

방법 3: 수동 복사 & 붙여넣기 (가장 직관적)

1. 내 프로젝트 루트 경로에 CLAUDE.md라는 이름의 새 텍스트 파일을 만듭니다.
2. 깃허브 레포지토리의 원문 내용을 복사하여 파일에 그대로 붙여넣고 저장합니다.

프로젝트 컨텍스트가 시작될 때마다 자동으로 해당 가이드라인이 로드되어 적용됩니다.

7. Q&A — 자주 묻는 질문 5가지

Q1. CLAUDE.md는 얼마나 길게 써야 하나요?
짧을수록 좋습니다. 권장 분량은 150~200줄 내외입니다. 불필요한 내용이 많아지면 오히려 AI 성능이 떨어지고 중요한 규칙이 무시될 수 있습니다. "꼭 지켜야 할 핵심 규칙"만 남기고, 부가적인 설명은 과감히 덜어내세요.

Q2. 루트 폴더와 개별 폴더 CLAUDE.md를 동시에 쓰면 어떻게 되나요?
두 파일 모두 적용되며, 개별 폴더의 지침이 더 우선됩니다. 예를 들어 루트에서는 "Python 코드는 f-string 사용"이라고 정해두고, 특정 하위 폴더에서만 "이 폴더는 % 포맷 사용"으로 덮어쓸 수 있습니다. 회사 전체 규칙과 부서별 예외 규정을 함께 운영할 때 유용합니다.

Q3. CLAUDE.md와 일반 프롬프트는 무엇이 다른가요?
CLAUDE.md는 세션 시작 시 자동 로딩되는 기본 행동 지침이고, 일반 프롬프트는 해당 대화에서만 적용되는 1회성 지시입니다. "매번 반복해야 하는 규칙"은 CLAUDE.md에, "이번 작업만의 특수 요구사항"은 프롬프트에 넣는 것이 정석입니다.

Q4. CLAUDE.md 내용을 AI가 무시할 때는 어떻게 하나요?
세 가지를 점검하세요. 첫째, 파일이 너무 길어서 중요한 규칙이 묻혔는지 확인합니다. 둘째, 모호한 표현 대신 "절대 ~하지 말 것", "반드시 ~할 것" 같은 명령형으로 다시 작성합니다. 셋째, 작업 직전 프롬프트에 "CLAUDE.md의 규칙을 반드시 준수해줘"라고 명시적으로 한 번 더 환기시킵니다.

Q5. 팀원들과 CLAUDE.md를 공유해서 써도 되나요?
오히려 공유하는 것이 정석입니다. 프로젝트 폴더 안에 CLAUDE.md를 두고 Git으로 함께 관리하면, 팀원 모두가 동일한 AI 행동 지침으로 작업할 수 있습니다. 코드 컨벤션을 문서가 아닌 'AI가 강제하는 룰'로 만드는 효과가 있어, 신규 합류자도 첫날부터 팀 표준에 맞춰 작업할 수 있습니다.

오늘 당장 해볼 수 있는 3가지 액션

1. 지금 진행 중인 프로젝트 폴더에서 /init을 실행해 CLAUDE.md 파일을 만들어 보세요. 1분도 걸리지 않습니다.
2. 반복해서 입력하던 지시 3개를 떠올려 CLAUDE.md에 적어두세요. "한국어로 답변", "원본 수정 금지" 같은 한 줄짜리 규칙으로 충분합니다.
3. 카파시 가이드라인(Method 1 또는 3)을 한 프로젝트에 적용해 보세요. AI 코딩 품질의 체감 차이를 직접 느낄 수 있습니다.

여러분의 CLAUDE.md에는 어떤 규칙을 넣고 싶으신가요?

매번 반복해서 입력하던 AI 지시가 있다면 댓글로 공유해주세요. 가장 많이 언급되는 규칙을 모아 "실무자가 검증한 CLAUDE.md 템플릿 모음"으로 다음 포스팅에서 정리해드리겠습니다. 이웃님들의 현장 경험이 최고의 콘텐츠입니다!

---

강호종 AI 길라잡이 강사

생성형 AI 활용 업무 효율화 전문강사 · 디지털융합교육원 지도강사 젠스파크 AI 전문강사 · (사)한국AINFT협회 이사
저서: 『생성형 AI 활용 업무혁신』(2026) · 『이것이 GEO마케팅이다』(2026) 외
📞 010-9912-9934 · 📧 art386@naver.com · blog.naver.com/art386 · aiart386.tistory.com

---

#CLAUDEmd #ClaudeCode #클로드코드 #AI프로젝트설정 #AI코딩가이드 #AndrejKarpathy #카파시가이드라인 #AI코딩룰 #프롬프트엔지니어링 #AI업무자동화 #바이브코딩 #VibeCoding #개발자AI #AI협업 #강호종강사 #AI길라잡이 #2026AI트렌드 #AX전환 #생성형AI #ClaudeSkills