🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

CLAUDE.md는 단순한 취향 파일이 아니라, Claude Code가 반복적으로 저지르는 실수 유형을 줄이기 위한 행동 규칙 세트이며, 원문은 Karpathy식 4개 규칙에 8개를 추가해 에이전트형 코딩 환경의 병목을 보완해야 한다고 주장한다.

📌 핵심 요약

• 원문은 Karpathy의 문제 제기에서 출발한 4개 CLAUDE.md 규칙이 Claude의 코드 작성 실수를 줄이는 데 효과가 있었다고 설명한다.
• 하지만 2026년 5월 기준 Claude Code 생태계는 단순 코드 작성보다 에이전트 조율, 장기 작업, 훅 연쇄, 스킬 충돌 같은 문제가 더 커졌다고 본다.
• 저자는 30개 코드베이스를 6주간 테스트하며 기존 4개 규칙에 8개 규칙을 추가해야 한다고 주장한다.
• 핵심 병목은 모델이 모호한 지시를 평균내거나, 비언어적 결정을 맡거나, 검증 없이 성공처럼 보이는 결과를 내는 데 있다.
• CLAUDE.md는 200줄을 넘기지 않는 짧고 구체적인 행동 계약이어야 하며, 실제로 겪은 실패 모드에 대응해야 한다는 것이 원문의 결론이다.

🧩 주요 포인트

1. Karpathy식 4개 규칙은 조용한 가정, 과잉 설계, 불필요한 수정, 약한 성공 기준을 줄이는 데 초점을 둔다.
2. Claude Code가 에이전트형 작업으로 확장되면서 토큰 예산, 체크포인트, 충돌 표면화, 실패 가시화 같은 새 규칙이 필요해졌다.
3. CLAUDE.md가 너무 길어지면 중요한 규칙이 묻히고, 원문은 200줄 이후 준수율이 급격히 떨어진다고 주장한다.
4. 테스트 통과만으로는 충분하지 않으며, 테스트가 실제 의도를 검증하는지까지 봐야 한다.
5. 모든 규칙을 무조건 복사하기보다, 자신의 코드베이스에서 실제로 반복되는 실패 유형에 맞춰 줄이는 것이 더 낫다고 말한다.

🧠 상세 정리

1. 병목은 “코드를 못 쓰는 것”이 아니라 반복되는 행동 실패다

원문이 다루는 핵심 병목은 Claude가 코드를 생성하는 능력 자체보다, 작업 중 반복적으로 발생하는 행동 패턴의 실패다. 예컨대 말없이 가정하고 진행하거나, 간단한 문제를 과도하게 복잡하게 만들거나, 건드리지 않아도 되는 주변 코드를 함께 바꾸는 식이다.

Karpathy가 지적한 문제는 이러한 실패를 4개 규칙으로 압축했다. 생각하고 코딩하기, 단순함 우선, 외과적 변경, 목표 중심 실행이 그것이다. 원문은 이 규칙들이 Claude Code 세션에서 흔한 실수 상당 부분을 줄이는 “바닥” 역할을 한다고 본다.

2. CLAUDE.md는 취향 모음이 아니라 행동 계약이다

저자는 CLAUDE.md를 개발자의 모든 선호를 모아둔 덤프 파일로 쓰는 방식을 경계한다. 너무 많은 규칙과 취향을 넣으면 모델이 핵심을 놓치고, 세션마다 일관성도 떨어진다는 것이다.

원문에서 제시하는 관점은 명확하다. CLAUDE.md의 각 규칙은 “어떤 실수를 막는가?”라는 질문에 답해야 한다. 즉, 문서는 모델에게 좋은 사람이 되라고 말하는 선언문이 아니라, 관찰된 실패 모드를 줄이기 위한 짧고 실행 가능한 행동 계약이어야 한다.

3. 기존 4개 규칙은 코드 작성 순간에는 강하지만 장기 작업에는 약하다

Karpathy식 4개 규칙은 Claude가 코드를 쓰는 바로 그 순간의 품질을 높이는 데 초점이 있다. 하지만 원문은 2026년 5월의 Claude Code 사용 환경이 더 복잡해졌다고 설명한다. 이제는 한 번의 코드 작성이 아니라 여러 단계의 리팩터링, 세션을 넘나드는 디버깅, 여러 코드베이스 간 패턴 선택, 훅과 스킬의 충돌이 문제가 된다.

이 지점에서 기존 규칙은 침묵한다. 토큰 사용량을 어디서 끊을지, 중간 체크포인트를 언제 둘지, 파이프라인 실패를 어떻게 드러낼지에 대한 기준이 없기 때문이다. 그래서 저자는 기존 규칙을 대체하는 것이 아니라, 그 빈칸을 메우는 8개 규칙을 추가했다고 설명한다.

4. 모델에게 맡기면 안 되는 결정이 있다

추가 규칙 중 하나는 “모델에게 비언어적 작업을 시키지 말라”는 것이다. 원문은 API 재시도 여부, 메시지 라우팅, 에스컬레이션 판단처럼 결정론적 코드로 처리해야 할 일을 모델에게 맡기면 결과가 흔들린다고 지적한다.

이 병목은 모델이 매번 다른 문맥을 읽고 다른 결정을 내릴 수 있다는 데 있다. 저자는 503 응답에서 재시도 여부를 Claude가 결정하게 했던 코드가 처음에는 잘 작동했지만, 이후 요청 본문을 판단 문맥으로 읽으면서 불안정해졌다고 설명한다. 따라서 정책성 판단은 프롬프트가 아니라 명시적 로직으로 고정해야 한다는 주장이다.

5. 토큰 예산과 체크포인트는 장기 에이전트 작업의 안전장치다

원문은 장기 디버깅이나 다단계 리팩터링에서 토큰 예산이 없으면 세션이 쉽게 표류한다고 말한다. 같은 오류 메시지를 반복해서 다루면서 이미 거절한 수정안을 다시 제안하거나, 이전 시도 내용을 잊는 문제가 발생한다는 것이다.

체크포인트도 같은 맥락이다. 6단계 리팩터링에서 4단계가 잘못됐는데도 5단계와 6단계가 그 위에 쌓이면 되돌리는 비용이 커진다. 따라서 긴 작업은 중간 검증 지점을 두고, 잘못된 방향으로 더 진행하기 전에 멈추게 해야 한다.

6. 충돌을 평균내지 말고 드러내야 한다

Claude는 코드베이스 안에 두 가지 상충하는 패턴이 있을 때 둘 다 만족시키려는 경향이 있다고 원문은 설명한다. 그 결과 새로운 코드가 두 스타일을 섞어 더 혼란스러운 구조가 될 수 있다.

예시로는 명시적 try/catch 방식과 전역 에러 바운더리 방식이 공존하는 코드베이스에서 Claude가 둘을 모두 적용해 에러 핸들러를 중복시킨 사례가 제시된다. 저자는 이런 경우 모델이 중간값을 만들지 말고, 충돌을 사용자에게 표면화해야 한다고 본다.

7. 테스트는 필요하지만 “테스트 통과”가 최종 목표는 아니다

원문은 테스트를 선택 사항으로 보지 않는다. 그러나 더 중요한 점은 테스트가 실제 의도를 검증해야 한다는 것이다. Claude가 얕은 테스트를 많이 만들고, 그 테스트가 통과했다는 이유로 자신감을 갖는 상황을 문제로 본다.

저자가 든 사례에서는 인증 함수에 대한 테스트 12개가 모두 통과했지만, 실제 프로덕션 인증은 깨져 있었다. 테스트가 반환값의 존재만 확인했을 뿐, 올바른 값을 반환하는지는 검증하지 않았기 때문이다. 따라서 성공 기준은 “테스트가 있다”가 아니라 “테스트가 의미 있는 실패를 잡아낸다”에 가까워야 한다.

8. 관습은 새로움보다 우선한다

원문은 Claude가 더 좋아 보이는 새 패턴을 도입하더라도, 기존 코드베이스의 관습을 깨뜨리면 총비용이 커질 수 있다고 말한다. 특히 한 코드베이스 안에 두 가지 패턴이 공존하게 되면 유지보수와 테스트 방식이 흔들린다.

예시로는 클래스 컴포넌트 기반 코드베이스에 Claude가 React hooks를 도입한 사례가 나온다. 코드 자체는 작동했지만 기존 테스트 패턴은 componentDidMount를 전제로 하고 있었고, 결국 제거와 재작성에 시간이 들었다. 원문은 “더 나은 방식”보다 “이미 선택된 방식과의 일관성”을 우선해야 한다고 주장한다.

9. 실패는 조용히 숨지 말고 보이게 실패해야 한다

가장 비싼 실패는 실패처럼 보이지 않는 실패라는 것이 원문의 중요한 시사점이다. 함수가 작동하는 것처럼 보이지만 잘못된 데이터를 반환하거나, 마이그레이션이 완료된 것처럼 보이지만 일부 레코드를 건너뛰는 상황이 대표적이다.

저자는 데이터베이스 마이그레이션이 성공했다고 보고했지만 제약 조건 위반으로 14%의 레코드를 건너뛴 사례를 제시한다. 로그에는 남았지만 표면화되지 않았고, 문제는 11일 뒤 보고서 이상으로 발견됐다. 그래서 Claude에게도 실패를 삼키지 말고 즉시 드러내는 규칙이 필요하다고 본다.

🧾 핵심 주장 / 시사점

• CLAUDE.md의 가치는 많은 지시를 넣는 데 있지 않고, 반복되는 실패 모드를 짧은 행동 규칙으로 막는 데 있다.
• Karpathy식 4개 규칙은 여전히 기초이지만, 에이전트형 Claude Code 작업에는 추가 안전장치가 필요하다는 것이 원문의 주장이다.
• 토큰 예산, 체크포인트, 충돌 표면화, 실패 가시화는 장기·다단계 작업에서 특히 중요한 통제 장치로 제시된다.
• 테스트 통과, 작동하는 코드, 깔끔한 출력이 곧 성공을 의미하지 않으며, 실제 의도와 운영 결과까지 검증해야 한다.
• 최적의 CLAUDE.md는 보편 템플릿을 그대로 붙인 파일이 아니라, 각 코드베이스에서 실제로 발생한 실수에 맞춰 조정된 파일이다.

✅ 액션 아이템

• 현재 사용하는 CLAUDE.md가 200줄을 넘거나 취향 목록처럼 비대해졌는지 점검한다.
• Karpathy식 4개 규칙이 조용한 가정, 과잉 설계, 불필요한 변경, 약한 성공 기준을 충분히 막고 있는지 확인한다.
• 장기 작업을 자주 한다면 토큰 예산, 체크포인트, 실패 가시화 규칙을 CLAUDE.md에 추가할지 검토한다.
• 테스트 관련 지시가 단순히 “테스트를 실행하라”에 머물지 않고, 의미 있는 검증을 요구하는지 확인한다.

❓ 열린 질문

• 원문에서 제시한 실수율 감소 수치가 다른 팀과 코드베이스에서도 비슷하게 재현될 수 있을까?
• 12개 규칙 중 특정 코드베이스에는 불필요하거나 오히려 방해가 되는 규칙은 무엇일까?
• CLAUDE.md의 적정 길이와 규칙 수는 모델 성능 변화에 따라 계속 달라질까?