CLAUDE.md 작성법: Claude Code가 흔들리지 않는 실전 템플릿
짧은 템플릿, 세 가지 실무 사례, 실행 가능한 검사기로 Claude Code의 반복 실수를 줄이는 CLAUDE.md 작성법을 설명합니다.
같은 리뷰 의견이 세 번째 반복됐습니다. Claude Code는 기능 자체는 고쳤지만 저장소의 테스트 명령을 빼먹었고, 작업 범위에 없던 마이그레이션까지 수정했으며, 모바일 화면 확인도 하지 않았습니다. 세션을 시작할 때마다 더 긴 프롬프트를 붙여 넣는 방식으로는 이런 운영 문제가 사라지지 않습니다.
필요한 것은 회사 설명을 전부 담은 문서가 아니라, 작업 전에 읽을 짧고 지속적인 판단 기준입니다. CLAUDE.md에는 이 저장소를 어떻게 실행하는지, 어디까지 수정해도 되는지, 완료 전에 무엇을 검증해야 하는지를 적습니다. README 전체를 복사하거나 일회성 요청을 계속 쌓는 파일이 아닙니다.
이 글에서는 처음 만드는 사람도 바로 적용할 수 있도록 파일의 범위, 사람과 Claude Code의 역할 분담, 복사해 쓸 수 있는 템플릿, 실제로 실행되는 Node.js 검사기까지 순서대로 다룹니다.
먼저 알아둘 핵심
쓸모 있는 CLAUDE.md에는 대부분의 작업에 반복해서 적용되는 명령, 수정 경계, 리뷰 통과 조건이 들어갑니다. 다음 다섯 가지를 기준으로 내용을 줄이십시오.
- CLAUDE.md는 Claude Code에 주는 지속적인 지침이지 접근 제어 장치가 아닙니다.
- 팀 공통 규칙은 저장소 루트에, 개인 메모는
CLAUDE.local.md에, 특정 경로 규칙은.claude/rules/에 둡니다. - 대략 200줄 미만을 목표로 합니다. 배경 설명보다 파일 경로, 명령, 통과 조건을 우선합니다.
- 보안상 반드시 막아야 하는 동작은 글로만 경고하지 말고 permissions와 hooks로 차단합니다.
- 새 규칙을 추가한 뒤에는 실제 작은 작업으로 결과가 달라지는지 확인합니다.
첫날부터 완벽한 문서를 만들 필요는 없습니다. 최근 세 번의 풀 리퀘스트에서 반복된 리뷰 의견을 모은 뒤, 다음 작업에서도 필요한 결정만 남기는 편이 낫습니다.
Claude Code에 맡길 범위와 사람이 판단할 범위
저장소 지침과 권한 경계는 서로 다른 문제를 해결합니다. Claude Code에는 기존 코드 조사, 지정된 범위의 수정, 명시된 검사 실행, 변경 요약을 맡길 수 있습니다. 제품 정책, 운영 환경 배포, 고객·비용·개인정보·법적 의무와 관련된 결정은 사람이 책임져야 합니다.
| 판단 단계 | Claude Code에 맡길 일 | 사람이 판단할 일 |
|---|---|---|
| 조사 | 관련 파일, 기존 패턴, 테스트 찾기 | 고객 정보나 계약 데이터를 조사해도 되는지 |
| 구현 | 지정 범위 안의 코드와 테스트 변경 | 가격, 권한, 법무, 고객 공개 정책 변경 |
| 검증 | lint, 타입 검사, 테스트, 빌드 실행 | 인수 조건 충족 여부와 배포 승인 |
| 유지관리 | 변경 파일과 미해결 위험 보고 | 지침을 저장소의 영구 규칙으로 만들지 여부 |
CLAUDE.md는 “이 순서로 확인하라”는 안내입니다. git push --force, 운영 DB 접근, 비밀정보 파일 읽기를 물리적으로 막아 주지는 않습니다. 이런 동작은 permission deny 규칙이나 PreToolUse hook으로 차단해야 합니다. 두 계층을 나누는 방법은 Claude Code 권한 설정 가이드에서 더 자세히 확인할 수 있습니다.
작성 전에 파일의 적용 범위를 정하기
파일을 어디에 두느냐에 따라 지침이 적용되는 작업이 달라집니다. 루트 CLAUDE.md는 팀 공통 규칙, ~/.claude/CLAUDE.md는 사용자 전역 규칙, CLAUDE.local.md는 Git에 올리지 않을 장비별 메모에 적합합니다. 큰 모노레포에서는 중첩 파일과 경로별 규칙으로 불필요한 지침이 모든 작업에 따라오지 않게 합니다.
repo/
CLAUDE.md # 팀이 공유하는 짧은 규칙
CLAUDE.local.md # 개인 메모; .gitignore에 추가
.claude/
rules/
api.md # API 파일에만 필요한 규칙
packages/
admin/
CLAUDE.md # 이 하위 트리를 읽을 때 추가되는 지침
Claude Code는 시작할 때 현재 디렉터리와 상위 디렉터리에서 적용 가능한 파일을 읽습니다. 하위 디렉터리의 CLAUDE.md는 그 아래 파일을 읽을 때 로드됩니다. 따라서 결제 패키지 전용 규칙은 루트에 몰아넣지 말고 결제 코드 가까이에 두는 것이 맞습니다.
@docs/project-map.md 같은 import는 문서를 정리하는 데 도움이 되지만 컨텍스트를 절약하지는 않습니다. 가져온 파일도 시작 시 로드됩니다. 항상 필요한 판단만 루트 파일에 남기고, 긴 상세 자료는 필요할 때 읽을 경로로 안내하십시오. Windows에서 Claude Code가 직접 읽는 파일은 CLAUDE.md이므로 AGENTS.md도 함께 사용하려면 심볼릭 링크보다 @AGENTS.md처럼 명시적으로 가져오는 편이 안정적입니다.
이 CLAUDE.md 템플릿으로 시작하기
명령과 변경 규칙은 한 화면에서 파악할 수 있을 정도가 좋습니다. 아래 템플릿은 “좋은 코드를 작성하라”처럼 확인할 수 없는 문장을 피하고, 경로·검사 명령·수정 금지 범위·최종 보고 항목을 구체적으로 적습니다.
# Project Instructions
## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- Database schema: prisma/schema.prisma
- Tests: Vitest for units, Playwright for checkout
## Commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test
- Lint: npm run lint
- Build: npm run build
## Change rules
- Follow nearby code before adding a new abstraction.
- Do not change auth, billing, or migrations unless the task names them.
- When an API handler changes, update validation and tests together.
- Never place secrets in code, fixtures, logs, or screenshots.
## Review checklist
- Run the checks related to the changed files.
- Test an error path as well as the happy path.
- Report changed files, commands run, and skipped checks.
팀이 한국어로 일한다면 지침도 한국어로 작성해도 됩니다. 중요한 것은 언어가 아니라 검증 가능성입니다. “적절히 테스트” 대신 npm test, “기존 아키텍처 준수” 대신 “API 응답은 src/lib/api-response.ts를 사용”이라고 쓰면 리뷰어마다 판단이 달라지는 일을 줄일 수 있습니다.
세 가지 실무 사용 사례
아래 사례는 입력, 결과물, 사람의 검토를 분리합니다. 장기 규칙으로 추가하기 전 작은 작업에 먼저 적용해, 실제 행동과 결과가 바뀌는지 확인하십시오.
사용 사례 1: 제작사의 반복 리뷰 지적 줄이기
웹 제작사는 고객 저장소마다 CSS 이름 규칙, 이미지 크기, 지원 브라우저가 다를 수 있습니다. 회사 전체 지침을 매 프로젝트에 복사하면 정작 중요한 조건을 찾기 어려워집니다. 해당 고객과 저장소에서 매번 지킬 세 가지에서 다섯 가지 조건만 남깁니다.
입력: 최근 세 건의 리뷰 스레드, 작업 대상 파일, 기존 lint와 build 명령.
출력: 재사용한 컴포넌트, 변경 페이지, 실행한 검사, 아직 확인하지 못한 브라우저 조건이 포함된 차이 보고서.
사람의 검토: 디자인 의도, 이미지 사용 권리, CTA 문구, 최종 모바일 레이아웃. 문서 길이 대신 규칙 도입 전후 각 열 건에서 리뷰 반려 횟수가 줄었는지 비교합니다.
사용 사례 2: SaaS 문의 폼을 안전하게 수정하기
폼의 화면만 정상이어도 서버 검증, 알림 메일, 오류 처리가 빠질 수 있습니다. 폼을 수정할 때 함께 확인해야 할 파일과 테스트를 프로젝트 지침에 명시하면 부분 수정으로 끝나는 실수를 줄일 수 있습니다.
입력: 폼 컴포넌트, 입력 스키마, API 핸들러, 이메일 템플릿, 기존 테스트.
출력: 정상 입력과 잘못된 입력 테스트, 사용자에게 보이는 오류 메시지, 변경한 설정 목록. 최종 보고에는 개인정보가 로그에 기록되지 않았다는 확인도 포함합니다.
사람의 검토: 수집할 개인정보의 필요성, 보관 기간, 알림 수신자, 운영 배포. 전환율뿐 아니라 제출 실패 수와 고객 지원 시간도 함께 봅니다.
사용 사례 3: 콘텐츠 사이트의 불완전한 배포 막기
MDX 본문이 정확해도 description, 내부 링크, 대표 이미지, 모바일 코드 블록이 빠지면 검색 유입과 광고 수익에 영향을 줍니다. 짧은 게시 체크리스트는 작업 완료를 눈으로 확인할 수 있는 기준이 됩니다.
입력: MDX 파일, frontmatter 스키마, 내부 링크 대상, build 명령, 운영 URL.
출력: description 글자 수, 깨진 링크 결과, 코드 블록 검사, 빌드 상태, 브라우저로 확인한 URL 목록.
사람의 검토: 사실 정확성, 검색 의도, 광고 배치, 읽기 편의성, 공개 승인. PV 하나만 보지 말고 검색 클릭, 실제 읽기에 가까운 참여, CTA 클릭을 주 단위로 확인합니다.
실행 가능한 코드로 CLAUDE.md 검사하기
아래 Node.js 스크립트는 줄 수, 필수 제목 세 개, 신호가 강한 몇 가지 비밀정보 패턴을 검사합니다. check-claude-md.mjs로 저장하고 Node.js 20 이상에서 실행하십시오.
import { readFile } from "node:fs/promises";
const filePath = process.argv[2] ?? "CLAUDE.md";
const text = await readFile(filePath, "utf8");
const lines = text.split(/\r?\n/);
const lineCount = text.endsWith("\n") ? lines.length - 1 : lines.length;
// Pass localized H2 names as the third argument, separated by "|".
const requiredHeadings = (
process.argv[3] ?? "Commands|Change rules|Review checklist"
)
.split("|")
.map((heading) => heading.trim())
.filter(Boolean);
const h2Headings = new Set();
let fenceMarker = null;
for (const line of lines) {
const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
if (fenceMatch) {
const marker = fenceMatch[1];
if (fenceMarker === null) fenceMarker = marker;
else if (marker[0] === fenceMarker[0] && marker.length >= fenceMarker.length) fenceMarker = null;
continue;
}
if (fenceMarker !== null) continue;
const heading = line.match(/^##\s+(.+?)\s*$/)?.[1];
if (heading) h2Headings.add(heading);
}
const secretPatterns = [
["AWS access key", /AKIA[0-9A-Z]{16}/],
["GitHub token", /gh[pousr]_[A-Za-z0-9]{20,}/],
["assigned secret", /\b(api[_-]?key|password|token)\s*[:=]\s*["'][^"'\n]{8,}["']/i],
];
const failures = [];
if (lineCount > 200) failures.push(`too many lines: ${lineCount} (max 200)`);
if (requiredHeadings.length === 0) failures.push("required heading list is empty");
for (const heading of requiredHeadings) {
if (!h2Headings.has(heading)) failures.push(`missing h2: ${heading}`);
}
for (const [label, pattern] of secretPatterns) {
if (pattern.test(text)) failures.push(`possible secret: ${label}`);
}
if (failures.length > 0) {
console.table(failures.map((problem) => ({ problem })));
process.exitCode = 1;
} else {
console.log(`CLAUDE.md check passed: ${lineCount} lines`);
}
로컬과 CI에서 같은 명령을 사용할 수 있습니다.
node check-claude-md.mjs CLAUDE.md
# 한국어 H2 제목을 사용할 때
node check-claude-md.mjs CLAUDE.md "명령어|변경 규칙|검토 체크리스트"
이 코드는 완전한 비밀정보 스캐너가 아닙니다. GitHub secret scanning 또는 전용 스캐너와 함께 사용해야 합니다. 실제 자격 증명을 발견했다면 현재 줄만 지우지 말고, 필요한 경우 이력에서도 제거한 뒤 즉시 폐기하십시오.
자주 생기는 함정: 문서 비대화, 모호한 지침, 권한과 지침의 혼동
함정 1: 리뷰가 끝날 때마다 규칙이 늘어납니다. 재발 여부를 확인하지 않고 모든 의견을 영구 규칙으로 바꾸기 때문입니다. 같은 결정이 반복될 때만 후보로 삼고, 새 규칙을 더하기 전에 오래된 명령을 삭제하며, 패키지 전용 내용은 해당 패키지로 옮깁니다.
함정 2: 통과 조건이 없습니다. “품질을 높인다” 또는 “기존 디자인을 따른다”는 문장만으로는 결과를 판정할 수 없습니다. 대상 경로, 실행 명령, 기대 종료 코드, 확인할 화면 너비, 테스트 이름 중 하나 이상을 넣어야 합니다.
함정 3: 보안을 문장에 의존합니다. “운영 DB를 건드리지 않는다”는 경고는 물리적인 장벽이 아닙니다. 위험한 명령 패턴은 permission deny에 넣고, 반드시 중단해야 하는 동작은 PreToolUse hook으로 막습니다. CLAUDE.md에는 금지 이유와 승인된 대체 절차를 남깁니다.
함정 4: import가 숨은 지식 창고가 됩니다. 다른 파일에 넣으면 컨텍스트 비용이 사라진다고 오해하기 쉽지만, import된 내용도 시작할 때 로드됩니다. 루트에는 짧은 판단 규칙만 두고 긴 자료는 필요할 때 읽을 경로나 URL로 안내하십시오.
문서가 현실과 어긋나지 않게 유지하기
CLAUDE.md 변경도 코드 변경처럼 다룹니다. diff를 읽고, 검사기를 실행하고, 대표적인 작은 작업 하나로 검증합니다. 더 이상 존재하지 않는 명령·경로·아키텍처를 설명하는 규칙은 삭제합니다.
매달 다음 네 질문만 확인해도 문서 부패를 줄일 수 있습니다.
- 어떤 리뷰 의견이 두 번 이상 나왔는가?
- 어떤 지침이 무시됐거나 사람마다 다르게 해석됐는가?
- 어떤 명령이나 경로가 오래됐는가?
- 어떤 경고를 permission이나 hook으로 강제해야 하는가?
토큰 수나 문서 길이는 성과 지표가 아닙니다. 리뷰 반려 횟수, 병합 전에 발견한 검사 실패 수, 저장소 기본을 다시 설명하는 데 쓴 시간을 추적하십시오. 수치가 나아지지 않는 규칙은 다시 쓰거나 삭제하는 편이 낫습니다.
자주 묻는 질문
CLAUDE.md는 몇 줄까지 작성해야 하나요?
엄격한 내용 제한은 없지만 공식 문서는 200줄 미만을 목표로 하라고 안내합니다. 약 100줄로 시작하면 프로젝트 지도, 명령, 수정 경계, 리뷰 기준을 담을 여유가 있습니다. 특정 패키지에만 필요한 내용은 중첩 파일이나 .claude/rules/로 옮깁니다.
/compact 뒤에도 지침이 유지되나요?
루트 CLAUDE.md는 압축 뒤 컨텍스트에 다시 주입됩니다. 중첩 파일과 경로 범위 규칙은 Claude가 일치하는 파일을 읽을 때 다시 로드됩니다. 계속 필요한 판단은 압축될 수 있는 대화에만 두지 말고 파일에 남기십시오.
Auto memory와 무엇이 다른가요?
CLAUDE.md는 사람이 작성하고 관리하며 공유하는 지침입니다. Auto memory는 Claude Code가 디버깅 과정의 발견이나 개인 선호처럼 로컬에서 학습한 내용을 기록하는 메모입니다. 팀 공통 명령과 경계는 CLAUDE.md에, 개인적인 발견은 사람이 팀 규칙으로 승격하기 전까지 auto memory에 둡니다.
첫 번째 버전에는 무엇을 넣어야 하나요?
설치·테스트·빌드 명령, 수정하면 안 되는 영역 목록, 완료 시 보고할 항목부터 시작하십시오. 실제 작업을 한 번 실행한 뒤 관찰 가능한 재작업을 만든 누락된 결정만 추가합니다.
프로젝트 전용 운영 템플릿 만들기
CLAUDE.md만 작성한다고 안정적인 흐름이 완성되지는 않습니다. permissions, 테스트, 인수인계, 리뷰가 같은 기준을 사용해야 합니다. ClaudeCodeLab 교재 목록에는 이 요소를 프로젝트 전용 운영 템플릿으로 정리하는 체크리스트와 실습이 모여 있습니다.
실제로 테스트한 결과
2026년 7월 22일, 이 글의 check-claude-md.mjs를 두 개의 임시 fixture에 실행했습니다. 필수 제목이 들어 있는 10줄 유효 샘플은 종료 코드 0과 통과 메시지를 반환했습니다. 제목 하나를 빼고 테스트용 token을 넣은 실패 샘플은 종료 코드 1을 반환했으며, 누락된 제목 한 건과 일치한 비밀정보 패턴 두 건을 합쳐 정확히 세 건을 보고했습니다.
또한 JavaScript 문법, 공식 출처 URL, 내부 링크, frontmatter, 마지막 결과 섹션, 주요 상업용 CTA가 하나뿐인지 확인했습니다. 먼저 자신의 CLAUDE.md에 검사기를 실행하고 첫 번째 지적부터 고치십시오. 제품 동작은 Claude Code 공식 문서의 memory, context window, settings, hooks와 교차 확인했습니다.
관련 글
Claude Code로 신규 엔지니어 온보딩을 2주로 줄이는 실전 가이드
CLAUDE.md, 권한, CI, 첫 PR 체크리스트와 리뷰 템플릿으로 안전하게 온보딩을 단축합니다.
Claude Code 개인 개발 로드맵: 첫 30분부터 부업 수익화까지
Claude Code로 학습, 주말 프로젝트, Obsidian 기록, 배포 전 점검, 수익화 동선까지 현실적으로 진행하는 방법.
Claude Code를 팀에 도입하기 전에 만드는 '위험 대장'의 속살
Claude Code를 개인 실험으로 끝내지 않고 팀에 도입하기 위해, 권한·CI·배포 사고를 막는 위험 대장 만드는 법을 실제 예시와 코드로 설명합니다.
무료 PDF: Claude Code 치트시트
이메일을 입력하면 명령, 리뷰 습관, 안전한 워크플로를 정리한 PDF를 받을 수 있습니다.
개인정보를 안전하게 관리하며 스팸을 보내지 않습니다.
작성자 소개
Masa
Claude Code 실무 워크플로와 팀 도입을 검증하는 엔지니어입니다.