클로드 바이브코딩 기초반/한국이러닝 블로그가이드 →

클로드코드

CLAUDE.md란 — 매일 새로 출근하는 신입에게 주는 매뉴얼 한 장

오일기 · 한국이러닝인재개발원 원장 · 2026-09-23

새 대화의 Claude는 지난 대화의 규칙을 모릅니다. 폴더에 규칙 파일 한 장을 두면 대화를 열 때마다 먼저 읽고 일합니다. 뭘 적고 뭘 빼는지.

"폰에서도 보기 좋게 해줘" — 요청할 때마다 또. "계산 방식은 건드리지 마" — 어제 말했는데 오늘 또. 새 대화의 Claude는 지난 대화의 규칙을 모르고 시작합니다. 매일 새로 출근하는 신입입니다.

CLAUDE.md는 그 신입에게 주는 매뉴얼 한 장입니다. 폴더 맨 위에 두면 Claude Code가 대화를 시작할 때마다 먼저 읽고 일합니다.

정체

그냥 .md 텍스트 파일입니다. 메모장으로 열립니다. 직접 고쳐도 됩니다. 규칙은 강제가 아니라 참고입니다. 짧고 구체적일수록 잘 지킵니다. 프로젝트 폴더의 CLAUDE.md는 그 프로젝트에만, 내 계정 폴더(~/.claude/CLAUDE.md)의 것은 모든 프로젝트에 적용됩니다. 처음엔 프로젝트 폴더 한 장이면 됩니다.

만드는 법 두 가지

첫 서비스에서는 말로 만드는 쪽을 권합니다. 내 서비스 규칙을 내가 불러 주는 게 핵심이라서요.

무엇을 적나 — 여섯 줄

항목 예시 (견적 계산기)
서비스 한 줄 단가·수량·원가율·할인율 → 부가세 포함 견적과 남는 돈
꼭 지킬 것 폰 화면 우선 · 설명은 쉬운 한국어
건드리지 말 것 계산 규칙은 내 확인 없이 바꾸지 않는다
이번 버전에서 안 하는 것 로그인 · 결제 · DB · API 키
작업 순서 계획 먼저 → 내 확인 → 수정 → 확인 후 GitHub에 올리기
되풀이된 실수 (같은 실수가 2번 나오면 여기에 한 줄씩)

30줄이면 충분합니다.

무엇을 빼나

공식 문서의 기준이 명확합니다. "이 줄을 빼면 Claude가 실수할까?" 아니면 지웁니다. Claude가 코드를 읽으면 알 수 있는 것, 누구나 아는 상식("깔끔하게 짜라"), 자주 바뀌는 정보, 긴 설명은 뺍니다. 길어질수록 정작 중요한 규칙이 묻힙니다. 규칙을 넣었는데도 계속 안 지키면 파일이 너무 길거나 문장이 애매한 것입니다. 그 줄만 "IMPORTANT"를 붙이거나 다른 줄을 줄입니다.

비밀 숫자·고객 정보는 적지 않습니다. 이 파일도 GitHub에 함께 올라갑니다.

확인하는 법

만든 뒤 새 대화를 엽니다. 지난 대화를 모르는 신입이 출근한 상태입니다. 규칙 얘기 없이 "결과 아래에 안내 문구 하나 추가해줘"라고만 보냅니다. 폰 화면·계산 규칙을 알아서 지키면 매뉴얼을 읽고 일한 것입니다.

자라는 파일

같은 실수가 두 번 나오면 한 줄 추가합니다. 공식 문서도 "두 번째 할 때" 적으라고 합니다.

Claude에게 이렇게 보내세요
방금 네가 부가세를 할인 전 금액에 붙였어.
이 실수가 다시 안 나오게
CLAUDE.md에 규칙 한 줄로 추가해줘.
추가할 문장을 먼저 보여주고,
내가 좋다고 하면 저장해줘.

대화 중에 #으로 시작하는 한 줄을 보내면 바로 CLAUDE.md에 적어 주는 단축 방법도 있습니다. 말로 두 번 고칠 일을 파일 한 줄로 끝냅니다.

지침·Skill과의 관계

긴 작업 순서를 CLAUDE.md에 넣으면 다른 일에도 끼어듭니다. 그건 Skill로 뺍니다. 규칙은 CLAUDE.md, 절차는 Skill.

더 깊게 — 가이드 16장 · CLAUDE.md와 계속 쓸 수 있는 구조
4주 동안 직접 만들어 보고 싶다면클로드 바이브코딩 기초반 — 매주 화요일 3시간, 문정역 교육센터. 정원 10명, 막힌 화면을 같이 봅니다.일정·수강료 보기 →

같이 읽기