클로드를 똑똑하게 만드는 65줄, CLAUDE.md 한글 정리

CLAUDE.md는 Claude Code가 프로젝트 폴더에서 세션을 시작할 때 자동으로 읽는 파일입니다. 여기 적힌 내용은 그 프로젝트의 모든 대화에서 기본 전제가 되기 때문에, 매번 같은 지침을 다시 말할 필요가 없습니다.

2026년 1월, 안드레이 카파시는 AI 코딩 에이전트에 대한 불만을 공개적으로 밝혔습니다. 모델이 멋대로 가정하고 확인 없이 밀어붙이며, 헷갈리는 부분을 드러내지 않고, 트레이드오프를 제시하지 않고, 반박해야 할 때 반박하지 않는다는 것이었습니다.

한 개발자가 이 관찰을 CLAUDE.md 안에 그대로 넣을 수 있는 네 가지 원칙, 65줄짜리 파일 하나로 정리했고 깃허브에서 별 22만 개 이상을 받았습니다. 실행되는 코드는 한 줄도 없고, 전부 Claude에게 주는 행동 지침입니다.

네 가지 원칙

1. 코딩 전에 생각하기 (Think Before Coding)

“넘겨짚지 말 것. 헷갈리는 걸 숨기지 말 것. 트레이드오프를 드러낼 것.”

가장 흔한 실패 패턴을 겨냥합니다. 애매한 요청이 들어오면 모델은 해석 하나를 조용히 고르고 그대로 달립니다.

• 전제를 말로 꺼내놓기
• 확실하지 않으면 추측하지 말고 묻기
• 해석이 여러 개면 하나를 몰래 고르지 말고 전부 제시하기
• 더 단순한 방법이 있으면 말하기. 필요하면 반박하기
• 막히면 멈추고, 뭐가 불분명한지 이름 붙여서 묻기

2. 단순함 우선 (Simplicity First)

“문제를 푸는 최소한의 코드. 추측성 작업 금지.”

• 요청하지 않은 기능 추가 금지
• 한 번만 쓸 코드에 추상화 만들지 말 것
• 요청하지 않은 유연성, 확장성 금지
• 200줄을 썼는데 50줄로 되면 다시 쓸 것

판단 기준은 이렇습니다. 숙련된 개발자가 이거 보고 과하다고 할까? 그렇다면 단순하게 만들면 됩니다.

3. 수술하듯 고치기 (Surgical Changes)

“꼭 필요한 것만 건드릴 것. 내가 어지른 것만 치울 것.”

시킨 일과 상관없는 코드나 주석까지 손대버리는 문제를 막습니다. 바뀐 모든 줄이 요청과 연결돼야 합니다.

4. 목표 기반 실행 (Goal-Driven Execution)

“무엇을 하라고 말하지 말고, 성공 기준을 주고 지켜볼 것.”

카파시의 관찰 중 하나가 이것입니다. LLM은 명확한 목표가 주어지면 그걸 만족할 때까지 반복하는 데 매우 뛰어나다는 것입니다. 방법을 하나하나 지시하는 것보다 “이게 되면 끝”을 정해주는 쪽이 결과가 좋습니다.

그대로 쓰는 법 (30초)

네 가지를 직접 문장으로 다듬을 필요는 없습니다. 아래 표를 그대로 복사해서 CLAUDE.md에 붙여넣기만 해도, 매번 같은 지침을 새로 설명하지 않고 다음 세션부터 바로 적용됩니다.

1. 1.프로젝트 폴더를 엽니다.
2. 2.폴더 맨 위에 CLAUDE.md라는 파일을 만듭니다.
3. 3.아래 네 가지 원칙을 붙여넣습니다.
4. 4.끝입니다. 다음 세션부터 자동으로 읽습니다.

이걸 더 잘 쓰는 방법

있는 그대로 복사하는 것보다 형태를 빌려오는 게 낫습니다. 가장 잘 쓰는 사람들은 이 네 가지를 그대로 두지 않고 자기 프로젝트의 규칙으로 번역합니다.

길이도 주의해야 합니다. CLAUDE.md는 매 세션 시작할 때 로드됩니다. 200줄이 넘어가면 컨텍스트를 더 먹고 오히려 지시 준수율이 떨어지므로 짧게 유지하는 것이 좋습니다.

“클로드가 말을 안 듣는 게 아니라, 기준을 준 적이 없는 겁니다. 파일 하나, 65줄, 코드 없음. 지금 가장 가성비 좋은 세팅입니다.”