CLAUDE.md 작성법 — 카파시 65줄을 프로젝트에 맞게 변형하는 5단계

Claude Code 출력이 매번 1,000줄로 부풀어 나오는 경험이 있다면, 원인은 모델이 아니라 CLAUDE.md가 비어 있거나 원본 그대로라서일 가능성이 큽니다. 4가지 원칙을 프로젝트 언어로 다시 쓰지 않으면 모델은 "일반적인 베스트 프랙티스"로 답을 채우고, 한국어·본업 컨벤션·금지 패턴은 전부 무시됩니다.

 

Claude Code를 본업에 매일 붙여 쓰는 풀스택 입장에서, 카파시 원본을 내 프로젝트(claude-code-blog-builder)에 맞게 변형해본 실전 절차를 정리했습니다. 이 순서대로 가면 30분 안에 프로젝트용 룰 파일이 끝납니다.

지난 글에서 카파시 CLAUDE.md 4가지 원칙을 정리했습니다. 발행 시점(5월) GitHub 스타 10만이었는데 한 달 만에 17.5만(175k)까지 올라왔습니다. 이번엔 그 원본을 프로젝트에 맞게 어떻게 변형해야 실제 작동하는지, 5단계로 풀어봅니다.

왜 카파시 원본 그대로 쓰면 안 되는가

원본은 카파시가 자기 학습용으로 쓰는 파이썬·연구 코드 환경을 가정합니다. 프로젝트가 React·Spring·.NET 풀스택이거나, 한국어 답변이 필요하거나, 회사 코드 컨벤션이 따로 있다면 원본 4원칙만으로는 매칭이 안 됩니다.

원본 가정	프로젝트 현실	그대로 쓰면
영어 답변	한국어 PR·문서	영어 출력 그대로
단일 파일 스크립트	모노레포·멀티 모듈	잘못된 파일에 패치
Python·연구 코드	TypeScript·Spring·풀스택	패턴이 본업과 어긋남
카파시 개인 컨벤션	회사·팀 컨벤션	리뷰에서 다 되돌림

표 행을 한 줄로 풀면, 원본은 "최소 변형 + 신중한 코딩" 철학만 담고 있지 프로젝트의 컨텍스트는 0 입니다. 4원칙을 환경 언어로 다시 쓰는 작업이 필수입니다.

원본 4원칙 — 한 줄 요약

지난 글 /566에서 자세히 다뤘으니 여기는 핵심만 짚습니다.

1. Think Before Coding — 코드 치기 전에 의도·전제·실패 케이스를 먼저 글로 적게 시킨다.

2. Simplicity First — 최소 변경. 추측으로 기능 추가하지 말 것.

3. Surgical Changes — 기존 코드 스타일 유지. 리팩토링 자체 목적으로 하지 말 것.

4. Goal-Driven Execution — 요청 범위 밖으로 나가지 말 것. 멋대로 확장 금지.

원본 전체 코드는 forrestchang/andrej-karpathy-skills 레포에서 직접 확인할 수 있습니다. 한 달 만에 10만 스타에서 175k까지 올라온 이유가 4원칙 자체보다 "AI 룰 파일을 어떻게 짧게 쓰는가"라는 메타 가이드 역할이라는 점, 짚고 갑니다.

5단계 작성법 — 30분 안에 프로젝트용으로

순서대로 가면 끝납니다. 각 단계에 프로젝트 정보를 채워 넣으면 됩니다.

1단계 — 프로젝트 컨텍스트 정의 (5분)

파일 맨 위 3~5줄에 넣는 메타 정보입니다. 모델이 "이게 어떤 프로젝트인가"를 가장 먼저 보고 답변 톤·기술 선택을 정합니다.

# Project Name (한 줄 소개)

이 프로젝트는 {목적}입니다. 기술 스택은 {스택}, 구조는 {모노레포/단일 등}.
제약: {Windows 11 환경}, {Node 24+}, {외부 의존성 0 원칙} 등.
답변은 한국어로, 코드 예시는 영문 식별자 + 한국어 주석으로.

claude-code-blog-builder에서 실제로 쓰는 컨텍스트는 위 3줄입니다. "외부 의존성 0"이라는 한 줄이 있어서 모델이 매번 npm 패키지를 추가하려는 시도를 멈춥니다.

2단계 — 4원칙을 프로젝트 언어로 재작성 (10분)

원본을 그대로 복붙하지 말고, 프로젝트의 구체 상황 1~2개를 예시로 넣습니다. 예시가 있어야 모델이 "이 원칙이 여기서는 어떻게 적용되는지" 매핑합니다.

## 4가지 원칙

1. **Think Before Coding** — 새 스크립트 추가 전, 기존 scripts/ 폴더에 비슷한 게 있는지 먼저 확인.
   있으면 그 패턴 따라가고, 없으면 왜 새로 만드는지 한 줄 적기.

2. **Simplicity First** — package.json 의존성 추가 금지. Node 24 내장 fetch·fs로 다 처리.
   외부 라이브러리가 꼭 필요하면 사용자에게 먼저 물어볼 것.

3. **Surgical Changes** — quality-check.js 수정 시 기존 7항목 구조 유지. 새 검사 추가는 OK,
   기존 항목 시그니처 변경은 금지.

4. **Goal-Driven Execution** — 사용자가 "A만 고쳐달라"고 하면 A만. B·C 같이 보이는 이슈도
   별도 PR로 분리해 제안만 할 것.

핵심은 원본의 추상 문구를 "프로젝트의 구체 파일·폴더·금지 행동"으로 바꾸는 것입니다. 프로젝트에서 이 4원칙을 다시 쓴 뒤로 임의 npm install 시도가 거의 사라졌습니다.

3단계 — 금지 패턴 명시 (5분)

"이거 하지 마"를 명시적으로 적습니다. 카파시 원본은 "신중하라"만 있지 금지 목록은 없습니다. 프로젝트에서 자주 일어나는 실수 패턴을 5개 정도 적는 게 가장 효과적이었습니다.

## 하지 말 것 (DO NOT)

- `npm install` 으로 외부 의존성 추가 (Node 내장 fetch·fs만 사용)
- `try/catch` 로 에러 삼키고 빈 배열 반환 (반드시 process.exit(1))
- 매직 넘버 인라인 (상수는 파일 상단에 const)
- 한국어 변수명 (영문 카멜케이스만)
- 출력 메시지에 이모지 남발 (✅ ❌ ⚠️ 외 금지)

4단계 — 도메인 용어집 추가 (5분)

프로젝트에만 있는 고유 단어를 정의합니다. 예: blog-writer라는 게 "Claude Code 에이전트 이름"인지 "사람 작가"인지 모델이 매번 혼동됩니다. 용어집 한 번 적어두면 안 헷갈립니다.

## 용어집

- `blog-writer` — `.claude/agents/blog-writer.md` 에 정의된 에이전트
- `brand-facts` — `knowledge/brand-facts.md` (Single Source of Truth)
- `자격 훅` — 도입부 3번째 줄에 적혀있는 "왜 내가 이 글을 쓰는가" 라인
- `시리즈 박스` — 마무리 직전에 들어가는 시리즈 흐름 리스트

5단계 — 출력 형식 강제 (5분)

Claude는 기본적으로 풀 설명+코드를 다 풀어줍니다. 본업 코드에 붙여 쓸 땐 형식이 강제돼야 마찰이 없습니다. 이 한 단원이 카파시 원본에 빠진 부분이고, 환경에 가장 큰 차이를 만드는 부분이었습니다.

## 출력 형식

- 코드 패치는 unified diff 형식 (`---`, `+++`, `@@`)
- 응답 본문은 800자 이내. 길어지면 "더 자세히 원하면 알려주세요"로 끊기
- 새 파일 생성 시 `path/to/file.ext` 절대 경로로 명시
- 단계별 실행은 1) 2) 3) 번호 매기기
- 영어 코드 + 한국어 설명 분리

 

프로젝트 유형별 변형 예시 3가지

5단계 흐름은 같지만, 프로젝트 유형에 따라 넣는 내용이 달라집니다. 자주 묻는 3가지 유형을 매트릭스로 정리했습니다.

항목	웹 풀스택 (React+Spring)	데이터 분석 (Python+pandas)	모바일 앱 (Flutter/React Native)
1단계 컨텍스트	"Java 17 + Spring Boot 3.x, 프론트 React 18+TS"	"Python 3.12 + pandas 2.x, Jupyter 우선"	"Flutter 3.x / Dart, iOS 17+ Android 14+"
2단계 핵심 룰	"DTO 패턴 유지, JPA Lazy 기본"	"DataFrame 컬럼명 snake_case 통일"	"플랫폼 분기는 Platform.isIOS 패턴"
3단계 금지	"@Autowired 필드 주입 금지"	"for loop 금지, vectorize 우선"	"setState 남발 금지, Provider 쓰기"
4단계 용어집	"Repository = JPA 인터페이스"	"df = DataFrame, sr = Series"	"Widget tree, Hot reload"
5단계 출력	"메서드 단위 패치, 테스트 코드 동시 제공"	"코드 + 실행 결과 head() 같이"	"위젯 트리 ASCII + 코드"

표는 한눈에 보는 매트릭스고, 본문에 풀어쓰면 같은 말 반복이라 생략합니다. 어느 유형인지 골라 그 행만 따라 5단계 채우면 됩니다.

한국 개발자가 자주 빼먹는 5가지

카파시 원본은 영어권 기준이라 한국 환경에서 매번 새는 부분이 있습니다. 이 5가지를 안 넣으면 30분쯤 작업한 뒤에 답답해집니다.

1. 한국어 답변 강제 — "Respond in Korean unless code identifiers" 한 줄. 안 넣으면 갑자기 영어로 답변 돌아옵니다.

2. 인코딩·줄바꿈 — "Files must be UTF-8 LF" 한 줄. Windows 환경에서 CRLF 섞이면 git diff가 깨집니다.

3. 변수명 영문 강제 + 주석은 한국어 — 혼용 시 코드 리뷰에서 매번 지적 들어옵니다.

4. 본업 컨벤션 명시 — 예: "Java는 동기, TypeScript는 async/await 우선" 같은 팀 룰. 안 넣으면 Claude가 자기 취향대로 섞습니다.

5. 한국어 자료 우선 검색 — "When searching, prefer Korean tech blogs (NIA, 토스, 카카오)" 한 줄. 안 넣으면 영어 stackoverflow만 인용합니다.

실패담 — 원본만 쓰다가 막힌 케이스

claude-code-blog-builder에 처음 룰 파일을 적을 때 카파시 원본 65줄을 거의 그대로 복붙했습니다. 결과는 두 가지 마찰이 동시에 터졌습니다.

 

첫째, 답변이 영어로 돌아왔습니다. 4원칙 안에 "한국어 답변" 조항이 없으니 모델이 자기 기본값(영어)으로 갔습니다. 1단계 컨텍스트 라인에 "답변은 한국어로" 한 줄 추가하니 다음 세션부터 정상화됐습니다.

 

둘째, 모델이 자꾸 외부 npm 패키지를 추가하려고 했습니다. 원본의 "Simplicity First"가 추상적이라 프로젝트의 "외부 의존성 0" 원칙과 매칭이 안 됐습니다. 2단계에서 "package.json 의존성 추가 금지, Node 24 내장 fetch·fs만 사용"으로 구체화한 뒤 이 시도가 멈췄습니다.

 

결론은 원본을 프로젝트 언어로 다시 쓰지 않으면 효과가 절반입니다. 30분 들여서 단계별로 채우는 게 매번 어긋난 답변 받아 수정하는 시간보다 훨씬 짧습니다.

Q&A — 자주 보는 질문 5개

Q. 파일 어디에 두나요?
A. 프로젝트 루트(./CLAUDE.md)와 사용자 홈(~/.claude/CLAUDE.md) 두 곳을 Claude Code가 자동으로 읽습니다. 프로젝트 전용 룰은 루트에, 모든 프로젝트 공통 룰(예: 한국어 답변 강제)은 홈에 두면 됩니다.

Q. AGENTS.md·CURSOR.md와 같이 쓰나요?
A. 원본 레포는 CLAUDE.md + CURSOR.md + .cursor/rules/karpathy-guidelines.mdc 세 파일을 같이 둡니다. Claude Code만 쓰면 한 파일로 충분하고, Cursor 병행이면 같은 내용을 두 파일에 복사해두면 됩니다. AGENTS.md는 표준화 진행 중이라 아직 옵션입니다.

Q. 한 줄에 다 못 담는 룰은 어떻게?
A. 한 룰당 1~3줄이 적정선입니다. 5줄 넘어가면 docs/ 폴더에 별도 파일로 빼고 "자세한 룰은 docs/coding-rules.md 참조"로 링크합니다. 룰 파일 자체가 100줄을 넘기면 모델이 다 읽고도 일부를 잊어버리기 시작합니다.

Q. Claude 외 다른 AI에도 작동하나요?
A. 파일명 자체는 Claude Code가 자동 로드하는 컨벤션이고, GitHub Copilot은 .github/copilot-instructions.md, Cursor는 .cursorrules를 봅니다. 내용 자체는 호환되니 한 파일 써두고 이름만 바꿔 복사하면 됩니다.

Q. 수정 빈도는 어느 정도가 적정한가요?
A. 처음 30분에 단계 끝낸 뒤로는 "모델이 같은 실수 두 번 반복할 때" 그 룰만 추가하는 게 가장 효율적이었습니다. 매주 손대면 룰이 늘어나 무거워지고, 한 달에 한 번 정도가 적정선이었습니다.

📚 Claude Code 시리즈 — 처음 쓰는 사람부터 자동화까지

1. 단 1달러도 내지 않고 Claude Code 사용하는 방법 — 입문
2. Claude Code 창시자·해커톤 우승자 꿀팁 7가지 — 팁
3. Claude Cowork 자동화 — 매일 아침 카톡 AI 브리핑 — 자동화
4. Claude Code 활용법 — 망치는 습관 3개·살리는 습관 7개 — 베스트 프랙티스
5. 카파시 CLAUDE.md — 65줄 파일 정리 — 사례 (시리즈 1편)
6. 👉 현재 글 — CLAUDE.md 작성법 — 카파시 65줄을 프로젝트에 맞게 변형하는 5단계

처음 보시는 분은 단 1달러도 내지 않고 Claude Code 사용하는 방법부터 보세요.

같은 환경이면 위 순서대로 따라가도 무리 없습니다. 카파시 원본을 그대로 쓰던 분이라면 5단계만 통과해도 답변 톤·금지 패턴·출력 형식이 프로젝트에 맞춰집니다. 블로그 다른 글도 한번 둘러봐 주세요.

설치 환경: Windows 11, Node.js v24, Claude Code, Claude Max 플랜