콘텐츠로 이동

카파시 4원칙을 내 CLAUDE.md에 대 보다: 하네스 엔지니어링의 4가지 핵심 원칙

AI 코딩 에이전트에게 주는 규칙 파일 가운데 가장 널리 퍼진 것은 아마 65줄짜리 CLAUDE.md 하나일 것입니다. 안드레이 카파시(Andrej Karpathy)가 2026년 1월 X에 올린 LLM 코딩의 함정에 대한 관찰을, 다음 날 개발자 포레스트 챙(Forrest Chang)이 네 가지 원칙으로 정리해 공개한 파일입니다. 이 글은 그 4원칙을 요약하는 대신, 제가 직접 운영하는 프로젝트의 CLAUDE.md 7개를 펼쳐 놓고 각 원칙이 실제로 어떤 규칙이 되었는지, 그리고 어디가 비어 있는지를 대조한 기록입니다.

이 글의 기준

2026년 5월에 올린 같은 주제의 글은 유튜브 영상 한 편을 요약한 것이었습니다. 2026-10-24에 원본 저장소의 CLAUDE.md를 직접 읽고, 블로그·위키·앱 프로젝트의 CLAUDE.md와 줄 단위로 대조해 전면 다시 썼습니다. 파일의 줄 수와 크기는 2026-10-24에 잰 값입니다. 하네스 엔지니어링 전반은 하네스 엔지니어링 실무 메모에서 다룹니다.

1. 원본부터 바로잡기: 카파시가 쓴 파일이 아니다

먼저 출처입니다. 저장소 이름이 andrej-karpathy-skills라서 카파시가 직접 쓴 파일로 오해하기 쉽습니다. 저장소 설명은 "카파시의 LLM 코딩 함정 관찰에서 파생된(derived from) CLAUDE.md 파일 하나"이고, 작성자는 포레스트 챙입니다. 카파시의 X 게시물은 2026-01-26, 저장소는 2026-01-27에 만들어졌고, 2026-10-24 현재 저장소는 multica-ai 조직 아래로 옮겨져 있습니다.

이 오해는 제 주변에서도 실제로 일어났습니다. 2026-07-17 이 블로그의 기존 글 50편을 사실 검수 에이전트로 전수 점검했을 때 "카파시 스킬 저작자 오귀속"이 정정 목록에 올랐습니다. 이번에 글을 다시 쓰며 대조해 보니 제 위키의 용어 설명에도 "카파시가 자신의 CLAUDE.md에서 정리"라는 문장이 남아 있었습니다.

교훈: 원칙을 가져다 쓰기 전에 원문을 직접 읽습니다. 요약을 거칠수록 출처와 숫자가 조금씩 바뀝니다.

원문의 4원칙은 각각 굵은 한 줄로 요약되어 있습니다.

원칙 원문 요약 줄 뜻
Think Before Coding Don't assume. Don't hide confusion. Surface tradeoffs. 가정하지 말고, 헷갈리면 드러내고, 선택지를 보여라
Simplicity First Minimum code that solves the problem. Nothing speculative. 문제를 푸는 최소한의 코드, 추측성 기능 금지
Surgical Changes Touch only what you must. Clean up only your own mess. 필요한 곳만 건드리고, 내가 만든 흔적만 치워라
Goal-Driven Execution Define success criteria. Loop until verified. 성공 기준을 정하고, 검증될 때까지 반복하라

2. Think Before Coding — "가정하지 마라"를 위험 지점의 이름으로

제 CLAUDE.md 어디에도 "가정하지 마라"라는 일반 문장은 없습니다. 대신 이 프로젝트에서 가정이 특히 위험한 지점을 이름으로 적어 두었습니다.

파일 실제 문장 막으려는 가정
사용자 전역 CLAUDE.md 계정이 위와 다르게 보이면 바꾸기 전에 묻는다 스토어·클라우드 계정을 짐작해서 바꾸기
운동 기록 앱 각 문서 하단의 "열린 결정"은 임의로 확정하지 말고 사용자(또는 advisor)에게 확인 미정인 제품 결정을 에이전트가 확정하기
모닝 브리핑 앱 외부 API 스펙은 구현 전에 공식 문서로 확인한다. TASK.md 내용과 다르면 문서를 따르고 보고한다 기억에 의존한 API 사용법
뉴스 앱 "RSS 경로가 있을 것이다" 추측으로 템플릿을 채우지 않는다 — 반드시 실제 fetch로 검증 확인하지 않은 피드 주소

원문의 "불확실하면 물어라(If uncertain, ask)"는 맞는 말이지만, 에이전트는 자기가 불확실하다는 사실을 모를 때가 많습니다. 계정, 열린 결정, 외부 API처럼 어디서 멈춰야 하는지를 미리 짚어 주면 질문이 필요한 순간이 분명해집니다.

교훈: 원칙 한 줄을 "이 프로젝트에서 짐작하면 사고가 나는 곳" 목록으로 번역합니다.

3. Simplicity First — CLAUDE.md 자신에게 가장 먼저 적용해야 했다

코드에 대한 단순함 규칙은 제 파일에도 들어 있습니다. 운동 기록 앱은 "다른 상태관리 컨테이너는 도입하지 않는다", 모닝 브리핑 앱은 "새 의존성 추가 시 이유를 progress.md에 한 줄로 남긴다"라고 적었습니다. 사용자 설정에는 같은 방향의 ponytail 플러그인도 켜 두었습니다.

그런데 대조하다 보니 원칙을 가장 안 지킨 것은 CLAUDE.md 파일 자신이었습니다.

파일 줄 수 크기 비고
원본(andrej-karpathy-skills) 65 2.4KB 4원칙과 판단 기준만
사용자 전역 28 2.0KB 계정·번들 ID 등 공통 규칙
모닝 브리핑 앱 62 5.5KB 개발 루프·아키텍처·법적 가드
블로그 158 11.4KB 역할 분리·콘텐츠 규약·명령어
위키 186 10.0KB 디렉터리 구조·작성 표준
운동 기록 앱 147 29.3KB 앞부분 약 14.8KB가 버전별 출시 현황
뉴스 앱 517 29.1KB
블로그 자동화 데몬 635 26.5KB 로드맵·레거시 안내·사고 사례까지 포함

제 위키의 CLAUDE.md 작성 원칙에는 "500줄 이하 유지, 일반적 코딩 가이드는 줄이고 이 프로젝트 고유의 함정에 집중"이라고 적혀 있습니다. 두 파일이 그 선을 넘었고, 운동 기록 앱은 줄 수는 적어도 크기의 절반가량이 매 세션 읽을 필요가 없는 출시 현황입니다. 현황은 BACKLOG나 CHANGELOG로 옮기고 CLAUDE.md에는 규칙만 남기는 것이 다음 정리 과제입니다.

교훈: CLAUDE.md는 매 세션 맨 먼저 읽히는 파일입니다. 여기에 쌓인 상태 기록은 그대로 컨텍스트 비용이 됩니다.

4. Surgical Changes — 경계를 파일과 디렉터리 이름으로

원문은 "인접한 코드·주석·서식을 개선하지 마라", "모든 변경된 줄은 사용자 요청으로 거슬러 올라갈 수 있어야 한다"라고 말합니다. 제 파일에서는 이 원칙이 건드려도 되는 범위의 이름이 되었습니다.

  • 모닝 브리핑 앱: "계획한 범위만 구현한다. 범위 밖 리팩터링 금지." 그리고 "완료 기준, prompts/ 디렉터리 파일, 이 CLAUDE.md를 스스로 수정하지 않는다. 변경이 필요하면 제안만 한다."
  • 블로그: "이 repo에서 손대는 건 여전히 이 repo뿐", 작업 지시서의 [범위 경계] 칸("건드리지 말 것")
  • 위키: "raw/는 불변이다"
  • 운동 기록 앱: "DB 스키마는 컬럼 추가만 허용(삭제·타입 변경 금지)"

경계를 "필요한 곳만"이라는 형용사가 아니라 디렉터리·파일·작업 종류로 적으면, git diff --stat 한 번으로 지켜졌는지 확인할 수 있습니다. 블로그 저장소의 배포 전 검사(npm run check)가 frontmatter와 카테고리 규약 위반을 종료 코드 1로 막는 것도 같은 방향입니다.

교훈: 경계는 사람이 읽고 판단하는 문장보다 기계가 비교할 수 있는 이름일 때 강합니다.

5. Goal-Driven Execution — 루프에 상한과 금지 사항을 붙이다

원문은 "버그를 고쳐라"를 "재현 테스트를 쓰고 통과시켜라"로 바꾸고, 여러 단계 작업은 단계 → verify: 확인 방법 형태의 계획을 먼저 쓰라고 합니다. 제 파일 중 이 원칙을 가장 충실하게 옮긴 것은 모닝 브리핑 앱의 개발 루프입니다.

1. Plan: 무엇을 만들지, 어떤 파일을 건드릴지, 무엇으로 검증할지를 progress.md에 3~6줄로 기록
2. Implement: 계획한 범위만 구현
3. Verify: ./gradlew check / flutter analyze && flutter test 를 실제로 실행
4. Reflect: 실패하면 원인을 한 줄로 기록하고 3으로
5. 같은 작업 단위에서 수정-검증을 5회 반복해도 실패하면 중단하고 보고

원문에 없는 것이 두 가지 붙어 있습니다. 하나는 반복 상한(5회)이고, 다른 하나는 "테스트를 통과시키려고 테스트를 약화·삭제·skip 처리하지 않는다"는 금지 사항입니다. "검증될 때까지 반복하라"만 있으면 에이전트는 테스트 쪽을 고쳐서 검증을 통과시킬 수도 있고, 끝없이 돌 수도 있습니다. 위키의 CLAUDE.md는 같은 원칙을 페이지 작성 뒤의 셀프 체크로 옮겨, style-lint.sh와 build-site.sh 통과를 완료 조건으로 둡니다.

교훈: 목표 기반 실행에는 성공 기준과 함께 "언제 멈출지"와 "무엇을 고치면 안 되는지"가 따라와야 합니다.

💡 원스의 인사이트: 4원칙은 붙여 넣는 문서가 아니라 번역할 목록

대조해 보고 가장 놀란 점은, 제 CLAUDE.md 7개 중 어느 것도 4원칙을 그대로 붙여 넣지 않았는데 네 원칙이 모두 다른 모습으로 들어 있었다는 것입니다. 사고가 났던 자리마다 규칙이 하나씩 생겼고, 돌아보니 그 규칙들이 4원칙의 프로젝트별 번역이었습니다.

그래서 65줄 파일을 쓰는 방법으로 이렇게 권합니다. 처음에는 그대로 붙여 넣어도 좋습니다. 원문도 "프로젝트 고유 지침과 합쳐 쓰라"고 말합니다. 다만 에이전트가 같은 실수를 두 번 하면 해당 원칙 아래에 이 프로젝트의 고유명사(계정, 디렉터리, 명령어)로 된 규칙을 하나 더합니다. 그렇게 몇 달이 지나면 일반 원칙 문장은 지워도 될 만큼 구체적인 규칙이 남습니다. 그리고 원칙 2번을 파일 자신에게도 적용해, 현황과 일지는 다른 문서로 내보냅니다.

체크리스트 — 내 CLAUDE.md에 4원칙이 살아 있는가

  • [ ] 에이전트가 짐작하면 사고가 나는 지점(계정, 미정 결정, 외부 API)이 이름으로 적혀 있다
  • [ ] 새 의존성·새 추상화를 들일 때의 기준이 있다
  • [ ] CLAUDE.md에 상태 기록·일지가 쌓여 있지 않다(500줄 이하)
  • [ ] 수정하면 안 되는 파일·디렉터리가 이름으로 적혀 있다
  • [ ] 완료 기준이 실행 가능한 명령으로 적혀 있다
  • [ ] 반복 상한과 "테스트를 약화하지 않는다"는 금지 사항이 있다

참고 자료 및 출처