kknaks.dev

개요

AI 코드 어시스턴트가 등장하면서 개발 속도는 빨라졌지만, 새로운 문제도 생겼습니다. AI는 너무 빠르고 자신감 있게 코드를 작성해서, 사용자의 의도와 다른 방향으로 구현하거나, 불필요하게 복잡한 코드를 작성하거나, 요청하지 않은 부분까지 변경하는 경우가 많았습니다. 이 문제를 해결하기 위해 OpenAI의 공동 창업자이자 Tesla의 AI 디렉터인 안드레 카파시(Andrej Karpathy)가 제시한 4가지 원칙을 정리한 것이 CLAUDE.md 파일입니다. 단 65줄의 마크다운 파일이지만 이것이 깃헙에서 10만 개 이상의 스타를 받은 이유는, AI 어시스턴트와의 협업 방식 자체를 근본적으로 개선했기 때문입니다. 이 문서에서는 그 4가지 원칙이 무엇이고, 왜 효과적인지, 그리고 실제로 프로젝트에 어떻게 적용하는지를 배웁니다.

배경 / 사전 지식

AI 코드 어시스턴트: Claude, ChatGPT 같은 대규모 언어 모델 기반의 도구로, 개발자의 요청에 따라 코드를 생성해주는 기술입니다. 능력이 뛰어나지만, 사용자의 의도를 100% 정확히 파악하지는 못하고 상황에 따라 다양한 해석을 할 수 있습니다.

CLAUDE.md: 프로젝트 루트에 위치하는 마크다운 파일로, AI 어시스턴트에게 주는 가이드라인이자 프롬프트입니다. 깃 저장소에 함께 추가되어 AI와 대화할 때마다 자동으로 컨텍스트에 로드되어 일관된 협업 방식을 유지합니다.

안드레 카파시의 3가지 AI 고질병:

잘못된 과정: AI가 묻지도 않고 가정해서 작업하는 것
코드 부풀림: 간단한 문제를 복잡하게 해결하거나, 더 이상 사용하지 않는 코드를 방치하는 것
무분별한 수정: 요청하지 않은 부분까지 변경하고, 주석이나 형식을 임의로 바꾸는 것

카파시는 이 문제의 해결책으로 "명령하지 말고 성공 기준을 주고 지켜보라"는 원칙을 제시했습니다.

핵심 개념

원칙 1: Think Before Coding (코딩하기 전에 생각하기)

정의: AI가 가정하지 말고, 혼란스러운 부분을 숨기지 말며, 여러 선택지가 있을 때 모두 제시하는 원칙입니다.

작동 원리: 예를 들어 "로그인 기능을 추가해 줘"라는 요청이 들어왔을 때, 이 원칙이 없으면 AI는 즉시 JWT 기반 인증 코드 200줄을 작성합니다. 하지만 프로젝트가 다른 인증 방식을 사용하고 있다면 이 코드는 모두 버려져야 합니다.

Think Before Coding 원칙이 적용되면, AI는 다음과 같이 물어봅니다: "인증 방식이 몇 가지가 있습니다. JWT, 세션, OAuth 중 어느 것으로 할까요? 각각의 장단점은..." 이렇게 되면 개발자는 프로젝트의 맥락에 맞는 선택을 할 수 있고, AI도 그에 맞는 코드를 작성합니다.

주요 지침:

실행하기 전에 가정한 내용을 명확히 밝히기
여러 해석이 가능하면 선택하지 말고 모두 제시하기
더 간단한 방법이 있으면 언급하기
필요하면 반박하고, 이해 안 되는 부분이 있으면 멈추고 질문하기

원칙 2: Simplicity First (단순함을 최우선으로)

정의: 문제를 해결하는 데 필요한 최소한의 코드만 작성하고, 요청하지 않은 기능이나 미래에 필요할 수 있는 추상화는 추가하지 않는 원칙입니다.

작동 원리: "두 숫자를 더하는 함수를 만들어 줘"라는 요청에서 Simplicity First 원칙이 없으면 다음과 같이 됩니다:

interface Calculator {
  int calculate(int a, int b);
}

class AdderCalculator implements Calculator {
  @Override
  public int calculate(int a, int b) {
    return a + b;
  }
}

Calculator calc = new AdderCalculator();
int result = calc.calculate(2, 3);

하지만 우리가 원하는 것은:

int add(int a, int b) {
  return a + b;
}

복잡한 애플리케이션에서는 인터페이스가 필요할 수 있지만, 대부분의 경우 단순한 함수로 충분합니다. 이 원칙을 따르면 코드는 읽기 쉽고, 토큰 사용량도 줄어들며, 유지보수도 간단해집니다.

주요 지침:

요청한 기능만 구현하기, 추가 기능 없음
재사용 코드에는 추상화가 필요 없음
요청하지 않은 유연성이나 설정 가능성 추가 금지
200줄을 50줄로 줄일 수 있으면 다시 쓰기
시니어 개발자가 "이거 복잡한데"라고 생각할 것 같으면 단순화하기

원칙 3: Surgical Changes (정밀한 변경)

정의: 꼭 필요한 것만 수정하고, 요청받지 않은 부분은 절대 건드리지 않는 원칙입니다. 마치 수술처럼 정밀하게 필요한 부분만 손대야 합니다.

작동 원리: "이 함수의 버그를 고쳐 줘"라는 요청에 대해, Surgical Changes가 없으면 AI는 버그를 고칠 뿐만 아니라 주변 코드의 주석 스타일을 바꾸거나, 사용되지 않는 임포트를 정리하거나, 함수 이름을 리팩토링합니다. 이렇게 되면 리뷰 범위가 너무 커지고, 예상치 못한 부작용이 생길 수 있습니다.

Surgical Changes 원칙이 적용되면:

버그가 있는 줄만 수정합니다.
근처 코드의 형식, 주석, 스타일은 건드리지 않습니다.
존재하지 않는 코드는 지우지 않고 개발자에게 알립니다.
모든 변경이 사용자의 요청과 직접 연결되는지 확인합니다.

주요 지침:

변경된 모든 줄이 사용자의 요청에 직접 연결되는가?
기존 코드를 편집할 때 근처 코드, 주석, 형식을 개선하지 말 것
정당한 것을 굳이 리팩토링하지 말 것
관련 없는 사용되지 않은 코드를 발견해도 삭제하지 말고 알리기
요청하지 않은 파일은 생성하지 않기

원칙 4: Goal-Driven Execution (목표 중심 실행)

정의: 작업을 명령("버그를 수정해")이 아닌 검증 가능한 목표("이 버그를 재현하는 테스트를 작성하고 통과시켜")로 표현하고, 각 단계마다 검증하는 원칙입니다. 카파시가 말한 "성공 기준을 주고 지켜보라"는 조언을 코드 레벨로 구현한 것입니다.

작동 원리: 정렬 함수에 버그가 있다고 해봅시다.

Goal-Driven이 없는 경우:

개발자: "이 정렬 함수의 버그를 고쳐 줘"
AI: "인덱스 부분이 잘못된 것 같습니다. 수정했습니다. 완료."
실제 결과: 버그가 그대로 있음

Goal-Driven이 적용된 경우:

Step 1 - 테스트 작성: 버그를 재현하는 실패 케이스 테스트 작성
Step 2 - 검증: 실제로 테스트가 실패하는지 확인
Step 3 - 수정: 코드 수정
Step 4 - 검증: 수정된 코드가 테스트를 통과하는지 확인
Step 5 - 회귀 확인: 기존의 모든 테스트도 통과하는지 확인

주요 지침:

성공 기준을 명확히 정의하기
과제를 검증 가능한 목표로 전환하기
예) "버그를 수정해" → "버그를 재현하는 테스트를 작성하고 통과시켜"
예) "리팩토링 해 줘" → "리팩토링 전후로 모든 테스트가 통과하는지 확인해"
여러 단계의 작업은 각 단계마다 검증 포인트 추가하기

작동 원리

왜 CLAUDE.md가 효과적인가?

AI는 근본적으로 문제가 아닙니다. 실제로 AI는 너무 잘 짭니다. 너무 빠르고, 너무 자신감 있게 짭니다. 문제는 AI의 능력이 부족한 것이 아니라, 브레이크가 없다는 것입니다.

CLAUDE.md는 다음과 같이 작동합니다:

파일 로드: 깃 저장소의 CLAUDE.md가 AI와의 대화마다 자동으로 컨텍스트에 포함됩니다.
지침 적용: AI가 코드를 생성할 때마다 이 4가지 원칙을 따릅니다.
협업 개선: 개발자의 의도를 더 정확히 이해하고, 더 적절한 코드를 제시합니다.
낭비 감소: 불필요한 코드를 미리 걸러내므로, 리뷰와 수정 시간이 줄어듭니다.

각 원칙의 효과

| 문제 | 원칙 | 효과 | |------|------|------| | AI가 가정해서 잘못 구현 | Think Before Coding | 여러 선택지를 명시적으로 제시 → 개발자가 올바른 선택 가능 | | 불필요한 복잡한 코드 | Simplicity First | 최소한의 코드만 → 이해하기 쉽고, 토큰 절약 | | 요청하지 않은 변경 | Surgical Changes | 필요한 것만 → 리뷰 범위 축소, 부작용 감소 | | 검증 없는 작업 | Goal-Driven Execution | 목표 중심 검증 → 실제로 동작하는 코드 |

코드 예시

예시 1: Think Before Coding

나쁜 예시 (가정하고 진행):

개발자: "캐시 기능을 추가해 줘"
AI: (바로 Redis 기반 캐시 200줄 작성)

좋은 예시 (여러 선택지 제시):

개발자: "캐시 기능을 추가해 줘"

AI: "캐시 구현 방식이 몇 가지 있습니다:

1. In-Memory Cache: 간단, 빠르지만 프로세스 재시작 시 손실
   - 장점: 구현 간단, 외부 의존성 없음
   - 단점: 서버 여러 개면 동기화 문제
   
2. Redis: 빠르고 안정적, 분산 캐싱 가능
   - 장점: 높은 성능, 여러 서버에서 공유 가능
   - 단점: 외부 서비스 필요, 설정 복잡
   
3. Memcached: Redis보다 간단, 텍스트 기반
   - 장점: 가볍고 빠름
   - 단점: 기능 제한적

어느 방식을 선호하시나요? 아니면 프로젝트의 현재 상황을 알려주시면 추천할 수 있습니다."

의미: 개발자가 선택할 수 있는 여지를 주고, 각 선택의 트레이드오프를 명확히 함으로써 낭비를 방지합니다.

예시 2: Simplicity First

나쁜 예시 (과도한 설계):

// 두 숫자를 더하는 함수
public interface Operation {
    int execute(int a, int b);
}

public class AddOperation implements Operation {
    @Override
    public int execute(int a, int b) {
        return a + b;
    }
}

public class Calculator {
    private Operation operation;
    
    public Calculator(Operation op) {
        this.operation = op;
    }
    
    public int calculate(int a, int b) {
        return operation.execute(a, b);
    }
}

Calculator calc = new Calculator(new AddOperation());
int result = calc.calculate(2, 3);

좋은 예시 (단순함):

public int add(int a, int b) {
    return a + b;  // 단순하고 명확함
}

int result = add(2, 3);

의미: 인터페이스, 구현체, 팩토리 패턴은 나중에 정말 필요할 때 추가합니다. 지금은 문제를 해결하는 가장 간단한 방법으로 충분합니다.

예시 3: Surgical Changes

나쁜 예시 (과도한 변경):

// 버그 수정 요청: isEmpty() 함수가 null을 제대로 처리 못함

- // Check if list is empty
+ // Check whether the list is empty
  public boolean isEmpty() {
-   return this.list == null || list.size() == 0;
+   return Objects.isNull(this.list) || this.list.isEmpty();
  }

요청은 버그 수정이었는데, 주석, null 체크 방식, 빈 확인 방식까지 모두 변경되었습니다.

좋은 예시 (필요한 것만):

// 버그 수정 요청: isEmpty() 함수가 null을 제대로 처리 못함
  public boolean isEmpty() {
-   return this.list == null || list.size() == 0;
+   return this.list == null || this.list.isEmpty();
  }

list.size() == 0 을 list.isEmpty()로만 변경했습니다. 나머지는 건드리지 않습니다.

의미: 요청받은 버그만 수정합니다. 주석, 스타일, 다른 부분의 개선은 하지 않습니다.

예시 4: Goal-Driven Execution

나쁜 예시 (검증 없음):

개발자: "이 정렬 함수의 버그를 고쳐 줘"
AI: "인덱스가 문제인 것 같습니다. 수정했습니다."
(실제로는 버그가 그대로 있을 수도 있음)

좋은 예시 (검증 포함):

개발자: "다음 테스트를 통과하도록 정렬 함수를 수정해 줘:
- [3, 1, 2] → [1, 2, 3]
- [5, 5, 5] → [5, 5, 5]
- [] → []
모든 기존 테스트도 통과하는지 확인해 줘."

AI:
1. 테스트 코드 먼저 작성
2. 현재 함수로 테스트 실행 → 실패 확인
3. 버그 원인 파악
4. 함수 수정
5. 테스트 다시 실행 → 통과 확인
6. 기존 테스트 전체 실행 → 모두 통과 확인
7. 완료 보고

의미: 단순히 "수정해"가 아니라 "이 조건들을 만족하도록"이라는 검증 가능한 목표를 제시하면, AI는 실제로 동작하는 코드를 만들고 증명할 수 있습니다.

함정·실수

함정 1: 원칙을 전부 적용할 필요는 없다고 생각

실수: "이건 단순한 요청이니까 Surgical Changes 원칙은 무시해도 되겠지"라고 생각하는 것.

문제: 한두 번은 괜찮을 수 있지만, 습관이 되면 AI의 변경 범위가 자꾸 넓어집니다.

회피법: 모든 요청에 대해 일관되게 원칙을 적용하세요. CLAUDE.md 파일에 넣으면 자동으로 적용되므로, 매번 명시할 필요가 없습니다.

함정 2: Think Before Coding을 "너무 많은 질문"으로 오해

실수: "그럼 모든 요청에 AI가 10가지 선택지를 제시할 건가?"라고 오해하는 것.

문제: Think Before Coding은 "혼란스러운 부분만" 명확히 하는 원칙입니다. 명확한 요청에는 바로 시작합니다.

회피법: CLAUDE.md의 표현을 정확히 이해하세요: "혼란스러운 점을 숨기지 말고", "더 간단한 방법이 있으면 언급해". 필요할 때만 질문합니다.

함정 3: Simplicity First를 "기능 제거"로 오해

실수: "그럼 확장 가능한 코드를 절대 못 쓰나?"라고 오해하는 것.

문제: Simplicity First는 "지금 불필요한 복잡함을 추가하지 말라"는 뜻입니다. 실제로 필요한 기능은 모두 포함합니다.

회피법: 요청을 명확히 하세요. "3개의 정렬 알고리즘을 지원하는 코드를 만들어 줘"라고 하면, 그것은 필요한 기능이므로 3개를 모두 구현합니다.

함정 4: Surgical Changes를 "기존 코드 개선 금지"로 오해

실수: "그럼 나쁜 코드는 절대 못 고치나?"라고 오해하는 것.

문제: Surgical Changes는 "요청하지 않은 부분은 건드리지 말라"는 뜻입니다. 개선를 원하면 명시적으로 요청하세요.

회피법: 명시적으로 요청하세요. "이 함수의 변수 이름을 더 명확하게 리팩토링해 줘"라고 하면, 그것이 목표가 되므로 리팩토링을 수행합니다.

함정 5: Goal-Driven Execution을 "테스트만 추가"로 오해

실수: "모든 작업에 테스트를 강제하려는 건가?"라고 오해하는 것.

문제: Goal-Driven Execution은 "검증 가능한 목표"를 뜻합니다. 테스트뿐만 아니라 "실행 후 서버가 포트 8000에서 시작되는지 확인", "API가 특정 응답을 반환하는지 확인" 등도 포함됩니다.

회피법: 검증 가능한 목표를 명시하세요. "로그인 페이지를 만들고, 사용자가 실제로 로그인/로그아웃할 수 있는지 수동으로 확인해 줘"도 좋은 목표입니다.

일반적인 함정

함정: CLAUDE.md를 만들면 바로 모든 게 해결될 것이라고 기대

회피법: CLAUDE.md는 "프롬프트"입니다. 여전히 명확한 요청과 충분한 컨텍스트를 제공해야 합니다. 예를 들어 "프론트엔드 수정해 줘"는 여전히 불명확합니다. "서로 다른 브라우저에서 로그인 폼이 깨지고 있어. 반응형 CSS를 수정해 줘"라고 해야 합니다.

베스트 프랙티스

1. CLAUDE.md 설치 방법

방법 1: 마켓플레이스 스킬 사용 (권장)

# 터미널에서:
gh marketplace install karpathy-guidelines

그 후 Claude Code에서 /karpathy-guidelines 명령어로 스킬 로드.

방법 2: 파일 직접 다운로드

전역 설치 (모든 프로젝트):

curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md -o ~/.claude/CLAUDE.md

프로젝트별 설치 (해당 프로젝트만):

curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md -o ./.claude/CLAUDE.md

방법 3: 수동 복사

깃헙 저장소에서 CLAUDE.md 파일 열기
Raw 버튼 클릭하여 원본 텍스트 복사
프로젝트의 .claude/CLAUDE.md 파일에 붙여넣기
저장

2. 효과적인 요청 작성 방법

4가지 원칙과 대응되는 요청 방식:

| 원칙 | 요청 방식 | |------|----------| | Think Before Coding | 애매한 점을 명시: "인증은 세션 기반으로 하고 있어" | | Simplicity First | 스코프 명확화: "로그인 폼만 만들어 줘, 백엔드는 나중에" | | Surgical Changes | 변경 범위 제한: "이 컴포넌트의 배경색만 변경해 줘" | | Goal-Driven Execution | 검증 기준 제시: "클릭 후 페이지가 새로고침되고 사용자명이 표시되어야 해" |

3. CLAUDE.md 커스터마이징

CLAUDE.md는 수정할 수 있습니다. 팀의 특성에 맞게 조정하세요:

예시: 보안 중심 팀

## Goal-Driven Execution
보안 검증을 필수로 추가하세요:
- SQL Injection 테스트
- XSS 공격 테스트
- 인증/인가 검증

예시: 성능 중심 팀

## Simplicity First
성능도 고려하세요:
- O(n²) 이상의 알고리즘 피하기
- 불필요한 데이터베이스 쿼리 피하기

4. 팀과 함께 사용하기

Git에 커밋: .claude/CLAUDE.md를 버전 관리에 포함시킵니다.
코드 리뷰 가이드로 활용: "이것은 Simplicity First 원칙을 위반한다"고 의견 제시 가능
문서화: 팀 위키나 README에 CLAUDE.md의 목적 설명
예제 공유: "이런 요청은 이렇게 하면 좋다"는 예제를 팀과 공유

5. AI와의 대화 개선

Before (원칙 없이):

"데이터베이스 쿼리 최적화해 줘"
→ AI가 여러 복잡한 변경사항 제시
→ 어떤 부분이 핵심인지 불명확
→ 코드 리뷰 시간 오래 걸림

After (원칙 적용):

"현재 /api/users 엔드포인트가 느려. 
 - 10개 사용자 조회가 3초 걸림 (목표: 0.5초)
 - N+1 쿼리 문제인 것 같아
 - 인덱스 추가는 하지 말고 조인으로만 최적화해 줘
 - 수정 후 /api/users?limit=10 호출 시간을 측정해서 보여 줘"
→ AI가 명확한 문제, 제약, 목표 이해
→ 필요한 것만 수정
→ 측정 결과로 검증
→ 효율적이고 신뢰할 수 있는 코드

참고

원본 GitHub 저장소:

forrestchang/andrej-karpathy-skills
현재 10만+ 스타, 계속 업데이트 중

안드레 카파시의 원본 X 게시물:

https://x.com/karpathy/status/2015883857489522876

관련 자료:

Claude 공식 문서: claude.ai/code
CLAUDE.md 마켓플레이스 스킬
영상에서 언급한 멤버십 가입 시 발표자료 PDF 제공

추가 학습:

원본 영상: castlestudio 채널의 "깃헙 스타 10만개 받은 65줄짜리 CLAUDE.md"
AI 정보공유 오픈카톡방: https://open.kakao.com/o/gK5uAeRh

The 4 Principles of Effective AI Collaboration: Behind GitHub's 100k-Star CLAUDE.md

Video

Study material

개요

배경 / 사전 지식

핵심 개념

원칙 1: Think Before Coding (코딩하기 전에 생각하기)

원칙 2: Simplicity First (단순함을 최우선으로)

원칙 3: Surgical Changes (정밀한 변경)

원칙 4: Goal-Driven Execution (목표 중심 실행)

작동 원리

왜 CLAUDE.md가 효과적인가?

각 원칙의 효과

코드 예시

예시 1: Think Before Coding

예시 2: Simplicity First

예시 3: Surgical Changes

예시 4: Goal-Driven Execution

함정·실수

함정 1: 원칙을 전부 적용할 필요는 없다고 생각

함정 2: Think Before Coding을 "너무 많은 질문"으로 오해

함정 3: Simplicity First를 "기능 제거"로 오해

함정 4: Surgical Changes를 "기존 코드 개선 금지"로 오해

함정 5: Goal-Driven Execution을 "테스트만 추가"로 오해

일반적인 함정

베스트 프랙티스

1. CLAUDE.md 설치 방법

2. 효과적인 요청 작성 방법

3. CLAUDE.md 커스터마이징

4. 팀과 함께 사용하기

5. AI와의 대화 개선

참고