65줄의 CLAUDE.md가 AI 코딩을 바꾼다: Karpathy-inspired 가이드라인을 읽고 내 경험과 겹쳐본 기록

AI · ML

65줄의 CLAUDE.md가 AI 코딩을 바꾼다: Karpathy-inspired 가이드라인을 읽고 내 경험과 겹쳐본 기록

Kun Woo Kim 2026. 5. 14. 11:01

728x90

GitHub 스타 10만 개를 넘긴 andrej-karpathy-skills 저장소의 CLAUDE.md.
단 65줄의 마크다운 파일이 왜 그렇게 화제가 됐을까.
Claude Code를 메인 코딩 에이전트로 쓰는 입장에서, 이 문서가 짚은 문제들이 너무 익숙해서 정리해두기로 했다.

CLAUDE.md가 던진 메시지

OpenAI 창립 멤버이자 전 Tesla AI Director였던 Andrej Karpathy는 LLM 코딩 에이전트가 자주 보이는 실패 패턴을 지적해왔다. 그 관찰에서 영감을 받아 만들어진 GitHub 저장소 andrej-karpathy-skills의 CLAUDE.md는 Claude Code가 작업할 때 참고할 수 있는 4가지 행동 원칙을 담고 있다.

길이는 단 65줄. 화려한 기법도, 새로운 알고리즘도 없다. 그런데 이 저장소는 GitHub에서 10만 개가 넘는 스타를 받으며 큰 화제가 됐다.

이유는 단순하다. AI 코딩 에이전트를 써본 사람이라면 누구나 겪은 답답함을 정확히 짚었기 때문이다.

이 가이드라인이 겨냥하는 문제는 크게 네 가지다.

확인 없는 가정: 모호한 부분이 있어도 묻지 않고 자의적으로 판단한다.
과도한 복잡성: 간단한 일에 불필요한 추상화와 미래 대비용 코드를 붙인다.
무관한 변경: 요청과 상관없는 코드, 주석, 포맷까지 건드린다.
검증 없는 완료 선언: 성공 기준이나 테스트 없이 "수정했다"고 말한다.

이 문제들을 줄이기 위해 CLAUDE.md는 네 가지 원칙을 제시한다.

CLAUDE.md의 4가지 원칙

제1원칙: Think Before Coding

성급하게 타이핑하지 말고, 모르면 물어보라.

요청이 애매할 때 AI가 멋대로 판단하고 구현하는 것을 줄인다. "로그인 기능 추가해줘"라는 요청에 AI가 JWT, 세션, OAuth 중 하나를 임의로 골라 구현해버리는 대신, 옵션의 장단점을 설명하고 사용자에게 선택을 요청하도록 유도한다.

제2원칙: Simplicity First

과설계(Over-engineering)를 피하고, 필요한 만큼만 작성하라.

AI는 종종 간단한 함수로 끝날 일을 추상 클래스로 빼고, "미래에 확장 가능하도록" 인터페이스를 만들고, "혹시 모를" 에러 핸들링을 잔뜩 추가한다. 똑똑해 보이는 코드가 아니라, 지금 당장 필요한 만큼의 단순한 코드를 작성하라는 원칙이다.

제3원칙: Surgical Changes

요청받은 부분만, 최소한의 범위로 수정하라.

버그 하나 고치라고 했더니 주변 코드의 포맷, import 순서, 변수명, 주석까지 모두 바꿔놓으면 코드 리뷰가 지옥이 된다. 마치 외과 수술처럼 딱 필요한 부분만 수정하도록 유도한다.

제4원칙: Goal-Driven Execution

스스로 검증 가능한 목표를 세우고 실행하라.

"버그 고쳐줘"라는 모호한 요청에 코드를 눈대중으로 고치고 끝내는 일을 줄인다. 버그를 재현하는 테스트 작성 → Red 확인 → 수정 → Green 확인이라는 명확한 검증 루프를 기본 행동으로 유도한다.

내가 Claude Code를 쓰면서 겪은 사례들

이 원칙들을 읽으면서 "이건 내 얘기다" 싶었던 경험들이 떠올랐다. 하나씩 풀어본다.

사례 1: 묻지 않고 폭주하는 AI (제1원칙 위반)

React 컴포넌트의 상태 관리를 손봐달라고 요청한 적이 있다. "이 사이드바 상태가 새로고침할 때마다 초기화되는데, 유지되게 해줘"라고 던졌다. 의도는 가벼웠다 — 어떤 방식이 좋을지 의논하면서 결정하고 싶었다.

Claude Code는 묻지 않았다. 곧바로 Zustand에 persist 미들웨어를 붙이고, localStorage에 저장하는 코드를 만들어냈다. 동작은 했다. 하지만 그 프로젝트는 Next.js App Router 기반이었고, localStorage 값이 초기 UI 렌더링에 관여할 경우 서버 렌더 결과와 클라이언트 첫 렌더 결과가 달라져 hydration mismatch가 발생할 수 있다. AI는 그걸 신경 쓰지 않았다.

내가 원했던 답변은 이거였다. "사이드바 상태는 클라이언트에서만 필요한가요, 아니면 서버 SSR에서도 알아야 하나요? 전자라면 localStorage 같은 클라이언트 저장소를 쓸 수 있고, 후자라면 cookie처럼 서버에서 읽을 수 있는 상태 저장 방식이 더 적합합니다." 이 한 줄을 묻지 않고 직진한 결과, 코드를 받고 나서 "아 이거 SSR에서 깨질 텐데" 하고 다시 갈아엎어야 했다.

CLAUDE.md의 1원칙이 정확히 짚는 지점이다. 모르면 묻는다는 단순한 규칙이, 한 시간짜리 삽질을 막아준다.

사례 2: 추상화 중독 (제2원칙 위반)

간단한 유틸 함수 하나가 필요했다. "객체에서 특정 키들만 골라서 새 객체로 만들어줘." 한 줄이면 끝날 일이다.

const pick = <T, K extends keyof T>(obj: T, keys: K[]): Pick<T, K> =>
  Object.fromEntries(keys.map(k => [k, obj[k]])) as Pick<T, K>;

Claude Code가 만든 코드는 다음과 같았다.

interface Picker<T> {
  pick<K extends keyof T>(keys: K[]): Pick<T, K>;
  omit<K extends keyof T>(keys: K[]): Omit<T, K>;
}

class ObjectPicker<T extends Record<string, unknown>> implements Picker<T> {
  constructor(private readonly source: T) {}

  pick<K extends keyof T>(keys: K[]): Pick<T, K> {
    return keys.reduce(/* ... */);
  }

  omit<K extends keyof T>(keys: K[]): Omit<T, K> {
    /* ... */
  }

  static from<T extends Record<string, unknown>>(obj: T): ObjectPicker<T> {
    return new ObjectPicker(obj);
  }
}

요청하지도 않은 omit이 따라왔고, 클래스로 감쌌고, 정적 팩토리 메서드까지 붙었다. 한 번 쓰고 말 함수에 빌더 패턴이 들어갈 이유가 없다. AI는 "혹시 모르니까"라는 명목으로 미래의 가상 요구사항에 대비한다. 그 대비가 지금의 가독성과 유지보수성을 갉아먹는다는 게 함정이다.

사례 3: 외과 수술이 아니라 전신 마취 (제3원칙 위반)

useEffect의 의존성 배열에 빠진 값을 하나 추가해달라고 했다. 정말 그것만 필요했다.

Claude Code가 반환한 diff는 30줄이 넘었다. 의존성 추가는 한 줄이었지만, 같은 파일의 다른 함수들이 화살표 함수에서 일반 함수로 바뀌어 있었고, import 순서가 알파벳 순으로 재정렬되었고, 주석 스타일이 //에서 /** */로 통일되었고, 사용하지 않는 import 두 개가 제거되어 있었다.

각각의 변경은 모두 "더 나은" 것일 수 있다. 하지만 PR 리뷰어 입장에서는 "의존성 배열 하나 고친다더니 왜 이걸 다 건드렸지?"가 된다. 진짜 변경이 무관한 변경 사이에 묻혀서, 리뷰에 들이는 시간이 5배가 된다.

의도하지 않은 변경은 친절이 아니라 잡음이다. CLAUDE.md의 3원칙은 이 잡음을 막는다.

사례 4: 테스트 없이 "고쳤다"고 우기는 AI (제4원칙 위반)

폼 유효성 검사 로직에 버그가 있었다. 이메일 형식이 잘못됐는데도 통과되는 케이스가 있다고 알려줬다. Claude Code는 정규식을 수정하고 "수정되었습니다"라고 답했다.

수정된 정규식이 진짜로 그 케이스를 잡는지 확인하지 않았다. 내가 직접 테스트를 돌려보니 여전히 통과되고 있었다. AI는 "수정한 것 같다"는 자신감만 있을 뿐, "수정되었다"는 검증을 하지 않았다.

이후로는 이렇게 요청한다. "이 버그를 재현하는 테스트를 먼저 작성해줘. 그 테스트가 실패하는 것을 확인한 다음 수정해줘. 수정 후 테스트가 통과하는 것까지 확인해줘." 이 한 단락이 들어가면 AI의 정확도가 체감상 두 배는 올라간다.

"수정했다"와 "검증된 수정"은 완전히 다른 결과물이다. 4원칙이 짚는 게 정확히 이 차이다.

하네스 엔지니어링이라는 관점

CLAUDE.md가 화제가 된 진짜 이유는 65줄의 텍스트 자체가 아니라, 그 텍스트가 던지는 관점의 전환에 있다고 본다.

AI는 코딩을 못 하지 않는다. 오히려 너무 빠르고, 너무 자신 있게 짠다. 문제는 그 빠름과 자신감이 잘못된 방향으로 갈 때다. 그래서 필요한 건 더 똑똑한 AI가 아니라, AI가 폭주하지 않도록 잡아주는 고삐다.

이걸 영어로 "Harness Engineering"이라고 부른다. 말 그대로 마구(harness)를 채우는 일이다. 야생마는 빠르지만 어디로 갈지 모른다. 마구를 채우면 빠른 속도를 유지하면서도 원하는 방향으로 달리게 할 수 있다.

CLAUDE.md는 그 마구의 한 형태다. 4가지 원칙은 AI의 출력 방향을 좁히는 가드레일이다. "묻지 않고 직진하지 마라", "필요한 만큼만 짜라", "딱 거기만 고쳐라", "검증 가능한 목표로 일해라" — 이 가드레일이 AI를 더 똑똑하게 만드는 게 아니라, AI의 실수 확률을 낮춘다.

엄밀히 말하면 CLAUDE.md 하나가 하네스 엔지니어링의 전부는 아니다. 하네스 엔지니어링은 에이전트가 어떤 도구(MCP, hooks, skills)를 쓸 수 있는지, 어떤 컨텍스트를 읽는지, 어떤 테스트와 리뷰 루프를 통과해야 하는지까지 설계하는 더 넓은 개념이다. CLAUDE.md/AGENTS.md 같은 가이드라인 문서는 그중에서 가장 작고 즉시 적용 가능한 형태의 하네스라고 볼 수 있다. 진입 장벽이 낮고, 효과가 즉각적이고, 65줄짜리 마크다운으로도 큰 변화를 만든다는 점에서.

내가 Claude Code를 쓰면서 점진적으로 깨달은 것도 같은 방향이었다. 처음에는 프롬프트를 잘 쓰는 데 집중했다. 그러다가 컨텍스트를 잘 제공하는 데 집중했다. 그리고 지금은 AI가 일하는 환경 자체를 설계하는 데 시간을 쓴다. CLAUDE.md를 정성껏 작성하고, 검증 루프를 미리 설계하고, "이런 경우에는 반드시 물어봐달라"는 규칙을 명시한다.

이런 작업은 코드를 한 줄도 짜지 않는다. 그래도 결과물의 품질이 확연히 달라진다.

마무리: 딸깍이를 넘어서

AI 코딩 시대에 개발자의 역할이 줄어드는 게 아니라 바뀌고 있다. 한 줄 한 줄 타이핑하는 사람에서, AI가 일할 수 있는 환경을 설계하고 검증 루프를 붙이는 사람으로.

65줄짜리 CLAUDE.md가 GitHub에서 폭발적인 반응을 얻은 건, 단순히 그 내용이 유용해서가 아니라, AI 시대에 개발자가 해야 할 일의 본질을 압축해서 보여줬기 때문이라고 생각한다.

코드를 짜는 게 아니라, 코드가 짜질 환경을 설계하는 것. 답을 주는 게 아니라, 답이 검증될 루프를 만드는 것. 이게 다가오는 시대의 개발자상이다.

오늘부터 내 프로젝트의 CLAUDE.md를 다시 손봐야겠다.

728x90

저작자표시 비영리 변경금지 (새창열림)