CLAUDE.md 코딩 원칙 4가지, 65줄 파일로 AI 실수 줄이기

CLAUDE.md 코딩 원칙 네 가지를 담은 65줄짜리 파일이 무엇을 막으려고 만들어졌는지, 원칙마다 AI에게 실제로 어떤 행동을 시키는지 정리했습니다. Claude Code에 플러그인으로 넣는 방법과 프로젝트의 CLAUDE.md에 붙이는 방법, Cursor에서 쓰는 법까지 함께 담았습니다.

65줄 CLAUDE.md는 어떤 파일인가

깃허브 저장소 andrej-karpathy-skills는 마크다운 파일 하나가 핵심인 저장소입니다. 저장소 설명은 "Claude Code의 행동을 고치기 위한 단일 CLAUDE.md 파일"이고, 그 CLAUDE.md는 정확히 65줄입니다. 별(관심 표시)은 2026년 10월 기준 약 22만 개이고, README에 라이선스는 MIT로 적혀 있습니다. 처음 올린 계정은 forrestchang였고, 지금은 multica-ai 계정으로 옮겨졌습니다. 옛 주소로 들어가도 새 주소로 넘어갑니다.

CLAUDE.md는 Claude Code가 작업을 시작할 때마다 먼저 읽는 지침 파일입니다. 여기에 원칙을 적어 두면 매번 프롬프트로 같은 말을 반복하지 않아도 됩니다. 내용이 짧고 형식이 단순해서 Cursor, Codex 같은 다른 AI 코딩 도구에도 옮겨 쓰기 쉽습니다.

출발점이 된 네 가지 문제

저장소 이름에 들어간 안드레이 카파시(OpenAI 공동 창업자, 전 테슬라 AI 디렉터)는 2026년 1월 X에 AI 코딩 에이전트를 써 보며 겪은 한계를 정리한 글을 올렸습니다. 이 파일은 그 글에서 짚은 문제를 바탕으로 다른 개발자가 만든 것이고, 카파시가 직접 쓴 파일은 아닙니다. 짚은 문제는 이렇습니다.

• 막히는 부분이 있어도 묻지 않고 그냥 코딩한다
• 그 과정에서 사용자 대신 잘못된 가정을 하고, 확인하지 않은 채 그 가정 위에 코드를 쌓는다
• 필요 이상으로 복잡하게 짜거나, 이해하지 못한 옆 코드와 주석까지 고친다
• 100줄이면 될 일을 1,000줄 넘는 구조로 부풀린다

여기에 사용자 쪽 문제도 하나 붙습니다. 목표를 알려 주지 않고 그저 "개발해 줘"라고만 요청하는 경우가 많다는 점입니다. 네 원칙은 이 문제들을 하나씩 막도록 짜여 있습니다.

1원칙 Think Before Coding: 애매하면 먼저 묻는다

AI에게 성급하게 코딩하지 말고 먼저 생각하라고 지시하는 원칙입니다. 파일의 문장은 "가정하지 말 것, 헷갈림을 숨기지 말 것, 선택지를 드러낼 것"입니다. 구체적으로는 네 가지를 시킵니다.

• 가정을 분명히 말하고, 확실하지 않으면 묻는다
• 해석이 여러 가지면 혼자 하나를 고르지 말고 모두 보여 준다
• 더 단순한 방법이 있으면 그렇다고 말하고, 필요하면 반대한다
• 무엇이 불분명한지 말하고 멈춘다

예를 들어 "로그인 기능을 추가해 줘"라고 하면, AI는 JWT(서명된 토큰으로 로그인 상태를 증명하는 방식), OAuth(구글⁠·카카오 같은 외부 계정으로 로그인하는 방식), 세션 기반 인증 가운데 하나를 혼자 골라 구현해 버리기 쉽습니다. 이 원칙이 들어가면 AI가 선택지를 먼저 설명하고, 사용자가 고른 방식으로 구현합니다.

2원칙 Simplicity First: 필요한 만큼만 짠다

과설계를 막는 원칙입니다. AI 코딩 에이전트는 간단한 함수로 끝날 일을 추상 클래스로 만들고, 확장 가능한 구조로 만들고, 나중에 필요할 것 같은 기능까지 넣는 경향이 있습니다. 그러면 요청하지 않은 기능 때문에 유지보수 비용만 늘고, 불필요하게 추상화된 코드는 사람이 읽기 더 어려워집니다.

파일은 이렇게 금지합니다.

• 요청하지 않은 기능은 넣지 않는다
• 한 번만 쓰는 코드에 추상화를 만들지 않는다
• 요청받지 않은 "유연성"이나 설정 항목을 넣지 않는다
• 일어날 수 없는 상황에 대한 오류 처리를 쓰지 않는다
• 200줄을 50줄로 줄일 수 있으면 다시 쓴다

판단 기준도 한 줄로 들어 있습니다. "시니어 엔지니어가 보면 과하다고 할까? 그렇다면 단순하게." 똑똑해 보이는 코드보다 문제를 푸는 최소한의 코드를 쓰게 하는 것이 목표입니다.

3원칙 Surgical Changes: 고칠 곳만 고친다

수술하듯 필요한 부분만 손대라는 원칙입니다. 버그 하나를 고치라고 했는데 AI가 옆 코드를 리팩터링하고, 주석과 포맷을 바꾸고, 기존 코드 스타일까지 제 마음대로 바꾸는 일이 흔합니다.

문제는 검토하는 사람의 피로입니다. 겨우 이해해 둔 코드가 또 크게 바뀌면, 어떤 변경이 버그 수정이고 어떤 변경이 AI가 임의로 손댄 것인지 가려내기 어렵습니다. 그게 쌓이면 코드는 돌아가는데 어떻게 돌아가는지 개발자가 설명하지 못하는 상태가 되고, 코드의 주도권이 AI에게 넘어갑니다.

파일의 지시는 이렇습니다.

• 옆 코드, 주석, 포맷을 "개선"하지 않는다
• 망가지지 않은 것은 리팩터링하지 않는다
• 내 취향과 달라도 기존 스타일을 따른다
• 관련 없는 죽은 코드를 발견하면 지우지 말고 알리기만 한다
• 내 변경 때문에 안 쓰이게 된 import·변수⁠·함수만 정리한다

점검 문장은 "바뀐 모든 줄이 사용자의 요청으로 곧바로 이어지는가"입니다. 사람이 이해할 수 있는 속도와 범위에 AI의 변경을 맞추려는 원칙입니다.

4원칙 Goal-Driven Execution: 성공 기준을 테스트로 세운다

목표를 세우고 그 목표를 향해 실행하게 하는 원칙입니다. 많은 사용자가 "개발해 줘, 고쳐 줘, 개선해 줘"처럼 목표 없이 요청하고, AI는 멈춰서 확인하는 대신 제멋대로 해석해 달려갑니다. 이 원칙은 모호한 요청을 받으면 곧바로 코딩하지 말고, 스스로 검증할 수 있는 목표로 바꿔서 실행하라고 시킵니다.

파일이 드는 바꿔 쓰기 예는 세 가지입니다.

"버그 고쳐 줘"를 받았을 때의 차이를 보면 분명합니다. 원칙이 없으면 AI는 코드를 대충 훑고, 그럴듯한 부분을 고친 뒤 "완료했습니다"라고 보고합니다. 원칙이 있으면 순서가 이렇게 바뀝니다.

1. 버그를 재현하는 테스트를 작성한다
2. 그 테스트를 실행한다
3. 테스트가 실패하는 것을 확인한다
4. 코드를 수정한다
5. 다시 테스트하고 결과를 확인해 최종 코드를 완성한다

이러면 AI가 버그가 실제로 있는지 먼저 확인하고, 고친 뒤 정말 해결됐는지까지 검증합니다. 여러 단계짜리 작업이라면 "1. [단계] → 확인: [점검 방법]" 형식으로 짧은 계획을 먼저 적게 합니다. 성공 기준이 분명하면 AI가 혼자 반복해 맞춰 갈 수 있고, "되게 해 줘" 같은 약한 기준이면 계속 되물어야 한다는 것이 이 원칙의 설명입니다.

내 프로젝트에 넣는 법

방법 1: Claude Code 플러그인으로 설치

모든 프로젝트에 적용하려면 플러그인이 편합니다. Claude Code 입력창에 차례로 넣습니다.

/plugin marketplace add multica-ai/andrej-karpathy-skills

/plugin install andrej-karpathy-skills@karpathy-skills

• 확인: /plugin 목록에 andrej-karpathy-skills가 설치됨으로 보입니다.

방법 2: 프로젝트의 CLAUDE.md에 붙이기

한 프로젝트에만 쓰려면 파일을 받아 프로젝트 맨 위 폴더에 둡니다. 터미널에서 그 폴더로 이동한 뒤 실행합니다.

CLAUDE.md가 아직 없는 새 프로젝트:

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

이미 CLAUDE.md가 있는 프로젝트(기존 내용 뒤에 덧붙이기):

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

• 주의: 첫 번째 명령(curl -o)은 같은 이름의 파일을 덮어씁니다. 기존 CLAUDE.md가 있으면 두 번째 명령을 씁니다.
• 확인: CLAUDE.md를 열면 맨 아래에 "## 4. Goal-Driven Execution" 구획이 보입니다.

Cursor에서 쓰기

저장소에는 Cursor용 규칙 파일 .cursor/rules/karpathy-guidelines.mdc가 함께 들어 있습니다. 이 파일을 내 프로젝트의 같은 위치에 복사하면 Cursor에서도 같은 원칙이 적용됩니다. Codex라면 같은 내용을 AGENTS.md에 붙여 넣으면 됩니다.

효과가 있는지 보는 법

저장소가 꼽는 신호는 네 가지입니다.

• 변경 내역(diff)에 요청하지 않은 수정이 줄었다
• 과하게 복잡해서 다시 짜는 일이 줄었다
• 실수한 뒤가 아니라 구현 전에 확인 질문이 나온다
• PR(합치기 요청)이 작고 깔끔해졌다

반대로 오타 하나, 한 줄짜리 수정까지 이 절차를 다 밟으면 느려집니다. 파일도 "속도보다 신중함 쪽으로 기울어 있으니, 사소한 작업은 판단해서 하라"고 스스로 적어 둡니다. 프로젝트 고유 규칙(타입스크립트 엄격 모드, API마다 테스트 필수 등)은 이 원칙 아래에 따로 구획을 만들어 덧붙입니다.

고삐라는 비유, 하네스로 보는 이 파일

이 파일이 크게 퍼진 이유는 AI에게 없던 능력을 넣어 줘서가 아닙니다. 성능 좋은 AI가 함부로 달리지 못하게 고삐를 채워, 개발자들이 매번 겪던 불편을 정확히 짚었기 때문입니다. AI는 코드를 못 짜는 게 아니라 너무 빨리, 너무 자신 있게 짭니다. 그래서 필요한 것은 더 많은 자유가 아니라 올바른 방향입니다.

하네스 엔지니어링(AI가 사람이 정한 규칙과 검사 안에서 일하게 환경을 짜는 방법)으로 보면, 이 파일은 고삐를 채우고, 경로를 정하고, 중간 검문소를 두고, 마지막에 테스트를 통과하게 만드는 장치입니다. 이렇게 되면 개발자의 일도 달라집니다. 코드를 한 줄씩 치는 시간은 줄고, AI가 일할 환경을 설계하고, 성공 기준을 정하고, 검증 루프를 붙이는 일이 늘어납니다.

네 원칙을 한 줄씩 줄이면 이렇습니다. 애매하면 묻는다. 필요한 만큼만 짠다. 고칠 곳만 고친다. 성공 기준을 테스트로 먼저 세운다.