📋가이드

CLAUDE.md: AI 코딩 에러를 41%에서 11%로 줄인 12가지 규칙

카파시와 포레스트 창이 실험을 통해 만든 Claude AI 코딩 가이드라인, 실패 패턴을 막는 행동 계약

#Claude#AI코딩#프롬프트엔지니어링#개발가이드

CLAUDE.md란?

카파시(Andrej Karpathy)와 포레스트 창이 실험을 통해 만든 Claude AI의 코딩 실수를 줄이기 위한 12가지 규칙입니다. 실제로 에러율을 41%에서 11%로 대폭 감소시킨 것으로 확인되었습니다.

핵심 원칙

기조: 비자명한 작업에서는 속도보다 신중함을 우선시합니다.

12가지 규칙 요약

1. 코딩 전에 생각하기

▸가정을 명시적으로 말하기

▸불확실하면 추측 대신 질문하기

▸모호함이 있으면 여러 해석 제시

2. 단순함 우선

▸문제를 해결하는 최소한의 코드만 작성

▸요청받은 것 이상의 기능 추가 금지

3. 외과적 변경

▸반드시 필요한 것만 수정

▸망가지지 않은 것은 리팩토링 금지

4. 목표 중심 실행

▸성공 기준을 먼저 정의

▸확인될 때까지 반복

5. 판단이 필요한 작업에만 모델 사용

▸사용: 분류, 초안 작성, 요약, 추출

▸비사용: 라우팅, 재시도, 결정론적 변환

6. 토큰 예산 준수

▸작업당: 4,000 토큰

▸세션당: 30,000 토큰

▸초과 시 요약하고 새로 시작

7. 충돌은 드러내기

▸패턴 충돌 시 하나를 선택하고 이유 설명

▸충돌하는 패턴을 합치지 말 것

8. 쓰기 전에 읽기

▸코드 추가 전 관련 코드 먼저 확인

▸구조의 이유를 모르면 질문

9. 테스트는 의도 검증

▸무엇을 하는지가 아닌, 왜 중요한지 테스트

10. 체크포인트 남기기

▸중요한 단계마다 상황 요약

▸흐름을 잃으면 멈추고 정리

11. 코드베이스 관행 따르기

▸개인 취향보다 일관성 우선

▸문제가 있다면 명시적으로 제기

12. 크게 실패하기

▸불확실성을 숨기지 말고 드러내기

▸건너뛴 것이 있다면 명확히 표시

사용 방법

markdown

# 저장소 루트에 CLAUDE.md 파일 생성

1. 위 12가지 규칙 복사
2. 프로젝트 특화 규칙 추가 (스택, 테스트 명령어 등)
3. 전체 200줄 이내로 유지

핵심 포인트

CLAUDE.md는 단순한 가이드가 아닌 관찰된 실패 패턴을 막기 위한 행동 계약입니다. 200줄을 초과하면 준수율이 떨어지므로 간결함을 유지해야 합니다.

실전 팁

▸프로젝트 시작 시 CLAUDE.md를 Claude에게 먼저 제공

▸규칙 위반 시 명시적으로 지적

▸프로젝트별로 커스터마이징하되 핵심 12가지는 유지