Claude용 .md(예: CLAUDE.md) = “작업 계약서”
.md 파일은 “설명서”가 아니라, AI가 따라야 할 **작업 계약서**로 쓰는 게 핵심입니다.
대화가 길어져도 결과가 흔들리지 않게 하려면, 처음에 **목표 / 제약 / 출력 형태**를 고정해야 합니다.
1) 목표(무엇을/왜)
- 무엇을 만들지(기능/페이지/규칙) 한 문장으로 시작합니다.
- 왜 필요한지(성능/유지보수/접근성/리스크)를 같이 적습니다.
예)
- “이 PR은 about 페이지의 블로그 동선을 velog 스타일로 개선한다. 유지보수 가능한 컴포넌트 구조가 목표다.”
2) 스코프(포함/제외)
여기서 프로젝트가 흔들리는 걸 막습니다.
포함/제외를 **명시적으로** 써서 AI가 범위를 확장하지 못하게 하세요.
예)
- 포함: “/about/threads 목록/디테일 UI만”
- 제외: “SEO 메타 개선 / 전역 레이아웃 리팩토링”
3) 품질 기준(성능/접근성/검증)
추상 문장(“좋은 코드로 해주세요”)은 금지에 가깝습니다.
대신 측정 가능한 체크 항목을 붙입니다.
예)
- 성능: “불필요한 클라이언트 컴포넌트 추가 금지”
- 접근성: “interactive 요소 aria-label/role 확인”
- 품질: “빌드 통과, 린트 에러 0, 모바일 320px 레이아웃 유지”
4) 코드 규칙(폴더/네이밍/스타일)
프로젝트 룰을 고정하면 AI의 추측이 줄어듭니다.
코드 규칙은 길어질수록 오히려 효율이 떨어지니 “자주 틀리는 것” 위주로만요.
예)
- 파일 경로를 항상 명시(예:
app/about/threads/page.tsx) - 컴포넌트 네이밍:
PascalCase, 훅:useXxx - 변경 범위 최소화: “기존 API/props 유지”
5) 산출물(어떤 파일/어떤 포맷)
AI가 가장 자주 틀리는 지점은 “출력 형태”입니다.
그래서 반드시 **예시**를 넣어주세요.
예)
- “최종 응답은 반드시 다음 헤딩만 사용: ## Summary / ## Test plan / ## Files changed”
- “코드 변경은 patch 단위로 제공(파일 경로 포함)”
출력 형태를 계약처럼 고정하면 리워크가 급격히 줄어듭니다.
업무 상황별 스위치(규칙 분리)
매번 같은 규칙을 덕지덕지 붙이면 과제가 과밀해집니다.
상황별로 rules를 분리하고, 필요할 때만 포함시키면 됩니다.
예)
RULES.dev.md: 빠른 프로토타이핑(테스트/린트는 최소)RULES.release.md: 테스트/린트 필수, 회귀 리스크 검토RULES.refactor.md: 동작 동일, 인터페이스 유지 우선
불확실성 처리 규칙(“모르는 건 물어봐” 대신)
“모르는 건 물어봐”는 너무 느슨합니다.
AI가 멈추지 않고 진행하려면, 불확실성이 들어올 때 **어떻게 처리할지** 룰을 적어야 해요.
예)
- 외부 API 스펙이 없으면: “mock을 만들고, 타입은
unknown -> zod로 좁힌다” - 마이그레이션이면: “feature flag로 단계 배포한다”
- 의존성 버전이 불명확하면: “기존 버전 유지 또는 대체안 제시(장단점 포함)”
마지막 체크리스트(커밋 전 검증 자동화)
마지막으로 “검증 항목”을 고정하세요. AI가 스스로 되짚게 만드는 순간 품질이 안정화됩니다.
예)
- 빌드 통과
- 린트 에러 0
- 접근성(aria-label) 확인
- 모바일 레이아웃
- 빈 상태(Empty) 동작 확인
작게 시작하는 1문장(효과 빠르게)
아래 한 문장만 먼저 추가해도 체감이 큽니다.
“이 프로젝트에서는 (a) 파일 경로를 항상 명시하고, (b) 변경은 최소화하며, (c) 최종 결과는 내가 바로 붙여넣을 수 있게 제공한다.”
이게 왜 강하냐면, AI가 알아서 '대충' 추측할 여지를 없애기 때문입니다.