AI와 코딩하다 보면 이런 일 겪어보셨을 겁니다. 버튼 하나 색깔만 바꿔달라고 했는데, 결과를 보니 옆에 있던 멀쩡한 함수까지 “더 깔끔하게” 정리해놨습니다. 시키지도 않은 예외처리가 잔뜩 붙어 있고, 50줄이면 끝날 일이 200줄이 되어 돌아옵니다.
문제는 그게 틀린 코드가 아니라는 점입니다. 돌아가긴 합니다. 그래서 그냥 넘어가고 싶어지는데, 다음에 그 파일을 열면 내가 쓰지 않은 코드가 절반이라 손을 못 댑니다. 그때부터 프로젝트가 무거워지기 시작해요.
저는 이걸 매 세션 채팅으로 막고 있었습니다. “필요한 것만 고쳐줘”, “다른 파일은 건드리지 마”, “간단하게 가자”. 그런데 세션을 새로 열면 AI는 그 말을 기억하지 못합니다. 어제 한 잔소리를 오늘 또 하고 있는 저를 발견하고 나서야 깨달았습니다. 매번 말로 할 게 아니라, 파일로 만들어두면 되는구나.
그게 CLAUDE.md입니다.
CLAUDE.md가 뭔가
프로젝트 폴더 맨 위에 두는 AI에게 주는 규칙서입니다. 핵심은 Claude Code가 세션을 시작할 때 이 파일을 자동으로 읽는다는 것입니다. 제가 매번 붙여넣지 않아도, 새 대화를 열 때마다 AI가 알아서 이 규칙을 안고 시작합니다.
시험 볼 때 채점 기준을 미리 알려주는 것과 같습니다. “풀이 과정 반드시 쓸 것”이라고 칠판에 적어두면 학생마다 제각각 풀지 않죠. 기준을 안 알려주고 나중에 감점하면 그건 학생 탓이 아닙니다. AI에게 규칙 없이 던져놓고 “왜 이렇게 했냐”고 하는 것도 마찬가지로 불공평해요.
뭘 적어야 하나 — 카파시의 60줄을 훔쳤습니다
막상 파일을 만들려니 뭘 적을지 막막했습니다. “잘 좀 해줘”를 적을 순 없으니까요. 그래서 맨땅에서 시작하지 않고 안드레 카파시(전 테슬라 AI 디렉터)의 60줄짜리 CLAUDE.md를 가져왔습니다. 그가 “LLM이 코딩할 때 반복적으로 빠지는 함정”을 관찰해 정리한 원칙인데, 읽어보니 제가 겪던 짜증과 하나하나 정확히 맞아떨어졌습니다. 저만 겪는 일이 아니라 AI 코딩의 구조적인 버릇이었던 겁니다.
출처: multica-ai/andrej-karpathy-skills (MIT 라이선스)
제 프로젝트에 실제로 적용한 행동 4원칙 원문입니다. 가공 없이 그대로 옮깁니다.
1. **Think Before Coding — 코딩 전에 생각하라.** 가정을 명시한다. 불확실하면 묻는다.
해석이 여러 개면 조용히 하나 고르지 말고 제시한다. 더 단순한 길이 있으면 말하고, 필요하면 반박한다.
2. **Simplicity First — 문제를 푸는 최소 코드. 추측성 구현 금지.** 요청 안 한 기능·추상화·"유연성"·
불가능한 시나리오용 예외처리를 넣지 않는다. 200줄이 50줄로 되면 다시 쓴다.
"시니어가 보면 과하다 하겠는가?" → 그렇다면 단순화.
3. **Surgical Changes — 건드려야 할 것만. 네가 만든 것만 치운다.** 인접 코드·주석·포맷을 "개선"하지 않는다.
안 망가진 걸 리팩터하지 않는다. 무관한 데드코드는 **지적만 하고 지우지 않는다**.
4. **Goal-Driven Execution — 검증 가능한 성공기준을 정하고 루프.** "버그 수정"→"재현 테스트 작성 후 통과",
"리팩터"→"전후 테스트 통과 보장"으로 바꾼다.
리팩터(refactor): 겉으로 보이는 동작은 그대로 두고, 코드 속 구조만 정리하는 것. 좋은 일처럼 들리지만 시키지도 않았는데 하다가 멀쩡한 걸 깨뜨리는 게 문제입니다.
각 원칙이 앞서 말한 제 짜증에 어떻게 대응하는지 짚어보겠습니다.
2번 Simplicity First가 “50줄이면 될 걸 200줄로” 문제를 막습니다. 특히 “요청 안 한 기능·유연성·불가능한 시나리오용 예외처리를 넣지 않는다” 가 핵심이에요. AI는 친절해서 “나중에 필요할 수도 있으니까” 하며 미리 만들어둡니다. 그 마음은 고마운데, 그 코드는 대부분 안 쓰이고 유지보수 대상만 됩니다.
3번 Surgical Changes가 “멀쩡한 코드까지 개선” 문제를 막습니다. “무관한 데드코드는 지적만 하고 지우지 않는다” — 이 한 줄이 특히 좋습니다. 안 쓰는 코드를 발견하면 알려주긴 하되 제 허락 없이 지우진 않는다는 거죠. 판단은 제가 합니다.
1번은 AI가 애매한 요청을 자기 마음대로 해석하고 진행하는 걸 막고, 4번은 “고쳤어요”라고 말만 하는 대신 진짜 고쳐졌는지 확인하게 만듭니다.
원칙 말고 더 넣을 것
카파시의 4원칙은 어느 프로젝트에나 통하는 일반 규칙입니다. 여기에 내 프로젝트만의 사정을 얹어야 진짜 쓸모가 생깁니다.
제가 겪은 예를 들면, 저는 Windows에서 PowerShell을 씁니다. 그런데 AI는 기본적으로 리눅스/맥 환경을 가정해서 자꾸 그쪽 명령어를 줬습니다. 그때마다 “나 윈도우야”라고 알려주는 게 또 반복 잔소리가 됐죠. 개발 환경을 파일에 박아뒀더니 그 문제가 사라졌습니다.
이런 식으로 제가 넣은 것들입니다.
| 항목 | 왜 필요한가 |
|---|---|
| 이 프로젝트가 뭔가 (2~3줄) | 맥락을 알아야 엉뚱한 제안을 안 함. “이건 개인용 도구다” 한 줄이면 AI가 엔터프라이즈급 설계를 들이밀지 않음 |
| 개발 환경 (OS·셸·언어) | Windows인데 리눅스 명령을 받는 일 방지 |
| 코딩 스타일 | “주석은 ‘왜’를 적는다. ‘무엇’은 코드가 말하게” 같은 취향 |
| 작업 방식 | 승인 없이 코드 고치지 않기 등 |
표에 적힌 항목보다 중요한 건 선정 기준입니다. 제 기준은 단순합니다. “이 말을 두 번 이상 했는가?” 두 번 했으면 세 번째도 하게 됩니다. 그럼 파일에 넣습니다.
이 기준이 좋은 이유는 미리 고민하지 않아도 된다는 점입니다. “AI가 실수할 만한 걸 다 적어두자”고 마음먹으면 시작부터 막혀요. 뭘 실수할지 제가 어떻게 압니까. 반면 이 기준은 실제로 겪은 것만 쌓입니다. 두 번 말했다는 건 그게 진짜 반복되는 문제라는 증거고, 겪지도 않은 문제는 애초에 후보에 오르지 않죠. 그래서 파일이 제 프로젝트에 딱 맞게 자랍니다. 남의 CLAUDE.md를 통째로 베끼면 안 되는 이유도 같습니다. 그건 그 사람이 겪은 문제 목록이지 제 것이 아니거든요.
딱 하나 지킬 것: 짧게
가장 중요한 조언입니다. CLAUDE.md는 길어지면 안 됩니다.
이유가 있습니다. 이 파일은 매 세션 AI가 읽는데, AI가 한 번에 읽고 기억할 수 있는 양에는 한계가 있습니다. 파일이 300줄이 되면 정작 중요한 “요청 안 한 기능 넣지 마라”가 잡다한 규칙들 사이에 묻혀버립니다. 유인물이 20장이면 아무도 안 읽는 것과 같아요.
카파시가 60줄로 끝낸 데는 이유가 있습니다. 제 파일 맨 위에도 “짧게 유지한다” 라고 못 박아 뒀습니다. 규칙을 더 넣고 싶은 유혹이 생길 때마다 그 문장이 저를 막아줍니다.
그래서 뭘 하면 되나
새 프로젝트를 시작한다면 이 순서가 가장 빠릅니다.
| 단계 | 할 일 |
|---|---|
| 1 | 프로젝트 루트에 CLAUDE.md 파일 생성 |
| 2 | 위 행동 4원칙을 그대로 복사해 넣기 (출처 표기) |
| 3 | 이 프로젝트가 뭔지 2~3줄 + 개발 환경(OS/셸) 추가 |
| 4 | 쓰면서 “또 이 잔소리 하네” 싶은 게 생기면 그때 한 줄씩 추가 |
| 5 | 60~80줄 넘어가면 덜어내기 |
표를 이렇게 읽으시면 됩니다. 2~3번은 지금 5분이면 끝납니다. 4~5번은 앞으로 계속 다듬어가는 부분이고요. 처음부터 완벽한 규칙서를 쓰려 하면 시작을 못 합니다. 4원칙만 넣고 시작해도 효과의 절반은 이미 챙기는 셈이에요.
한 문장으로 요약하면: 같은 잔소리를 두 번 했다면, 그건 CLAUDE.md에 들어갈 문장이다.
저는 이제 새 프로젝트를 열면 코드보다 이 파일을 먼저 만듭니다. 5분 투자로 앞으로 수십 번의 “아니, 그거 말고…”를 아끼기 때문입니다. 무엇보다 좋은 건 AI를 탓하는 일이 줄었다는 겁니다. 규칙을 안 알려주고 잘하기를 바라는 건 애초에 무리한 요구였으니까요.