원문 제목: Karpathy의 CLAUDE.md는 GitHub에서 8.2만 개의 스타를 받아 1위를 차지했습니다. 대부분의 개발자들은 아직 읽지 않았습니다.

원문 저자: Dep

편집자 주: Claude Code를 사용하는 많은 사람들이 마주한 가장 큰 문제는 모델이 충분히 강력하지 않다는 것이 아니라, 매번 처음부터 시작해야 한다는 것입니다.

프로젝트 배경, 기술 스택, 코드 규칙, 수정해서는 안 되는 부분, 이전에 시도한 해결책 등을 Claude에 반복해서 알려주어야 합니다. 이러한 정보들이 고정되지 않으면 Claude는 추측에 의존하게 되어 잘못된 파일 수정, 필요 없는 리팩토링, 현재 프로젝트에 부합하지 않는 도구 권장 등의 결과를 낳을 수 있습니다.

본문에서 소개하는 CLAUDE.md는 Claude Code를 위한 사용 설명서입니다. 이 파일을 프로젝트 루트 디렉토리에 두기만 하면 Claude가 실행될 때마다 자동으로 읽습니다. 이를 통해 Claude에 미리 알려줄 수 있습니다: 어떻게 대답할지, 어떻게 코드를 작성할지, 꼭 먼저 물어봐야 하는 때, 자체적으로 실행하면 안 되는 작업, 프로젝트에서 어떤 기술 스택을 사용하며, 이전에 어떤 중요한 결정을 한 것인지 등을.

간단히 말해, CLAUDE.md의 역할은 다음과 같습니다: 반복적 설명 감소, 모델이 벗어나는 것 제한, AI 프로그래밍을 더 안정적이고 쉽게 제어할 수 있게 함.

Claude Code를 사용 중이라면, 우선 Karpathy가 요약한 4가지 규칙부터 시작해보세요: 모르면 먼저 물어보기, 가장 간단한 해결책부터 시작하기, 관련 없는 코드에 손 대지 않기, 불확실성 명확히 표시하기. 이 몇 가지를 CLAUDE.md에 작성한 후, 자신의 프로젝트에 맞게 점진적으로 보완하면 사용 경험이 크게 향상됩니다.

원문은 아래와 같습니다:

CLAUDE.md라는 파일이 GitHub 트렌딩에서 1위에 올랐습니다.

8.2만 개의 스타, 7800회의 포크.

이 일은 Andrej Karpathy로부터 시작되었습니다. 그는 이전에 테슬라 AI 책임자이자 OpenAI의 창립 멤버 중 한 명이었습니다. 그는 Claude Code를 무력화시킬 4가지 행동을 요약하고 이를 파일에 작성했습니다.

이후 한 개발자가 이 4가지 규칙을 기반으로 확장하고 이 파일을 공개했고, 그 결과 빠르게 유명세를 얻었습니다.

이유는 매우 명확합니다. 정확성이 65%에서 94%로 향상되었습니다.

그러나 대부분의 매일 Claude Code를 사용하는 개발자는 실제로이 설정을 한 적이 없습니다. 그들은 매번 새로운 세션을 시작하여 동일한 컨텍스트를 재해석하고, 불필요한 범위 변경을 정리하고, 요청하지 않은 리팩터링을 롤백합니다.

다음은 전체 파일입니다.

대부분의 개발자가 놓치는 설정

Claude Code를 열 때마다, 그것은 기본적으로 아무것도 모르고 있습니다.

그것은 당신의 기술 스택을 모르고, 당신의 코딩 규약을 모르고, 당신의 프로젝트 배경을 모르며, 당신이 시도해 온 것을 모릅니다. 심지어 세 번의 세션 전에 명확히 하지 말아야 할 것을 이미 결정한 것도 모릅니다.

그래서 그것은 추측할 뿐입니다. 그리고 한 번 추측을 시작하면, 원치 않는 코드를 리팩터링하고, 기존 아키텍처를 깨뜨릴 가능성이 있는 프레임워크를 추천하며, 확인되지 않은 상태에서 파일을 삭제하고, 이전 결정을 뒤엎을 수 있습니다.

CLAUDE.md는 프로젝트 루트 디렉토리에있는 일반 텍스트 파일입니다. Claude Code는 각 세션을 시작할 때 자동으로이를 읽습니다.

한 번의 설정이고 반복하지 않아도되며, 세 가지 비용이 많이 드는 오류를 수정할 수 있습니다.

기본 설정: 매주 375 달러를 지불하며 자신을 반복적으로 설명합니다.

평범한 개발자는 매일 약 30 분을 Claude에게 다시 설명해야합니다.

기술 스택, 코딩 규약, 프로젝트 배경, 시도 한 방법 등 - 이러한 정보는 한 번에 작성하고 Claude가 자동으로 각 세션마다 읽지 않으면 세션 간에 유지되지 않습니다.

개발자의 시간당 임금이 150 달러로 계산하면:

· 매일 30 분은 75 달러입니다.

· 주당 375 달러입니다.

· 5 인 팀의 경우 주당 숨겨진 비용은 $1875입니다.

다음 7 가지 규칙은 CLAUDE.md 파일 맨 위에 위치해야합니다.

→ 시끄러운 부분 제거

대답할 때 "좋은 질문", "물론 가능합니다", "문제 없어요"와 같은 시작 발언은 사용하지 마세요. 직접적인 대답을 제공하세요. 인사말 없이, 질문을 재진술하지 마세요.

→ 과제에 맞는 대답 길이 제시

답변의 길이는 과제의 복잡성에 부합해야 합니다. 간단한 질문에는 직접적이고 간결한 답변을; 복잡한 과제에는 완전하고 상세한 설명을 제공하세요. 답변을 재진술하거나 결론을 다시 반복하여 내용을 늘리지 마세요.

→ 실행 전에 방안 제시

중요한 과제를 시작하기 전에, 선택 가능한 2~3가지 경로를 제시하고, 제가 선택한 후 진행하도록 합니다.

→ 불확실성에 대해 손실이 발생하기 전, 불확실성을 인정하세요

어떤 사실, 데이터, 날짜 또는 기술적 정보에 불확실하다면, 인용하기 전에 명확히 언급하세요. 합리적으로 보이는 정보로 지식 공백을 메우지 마세요. 확신할 수 없는 경우 즉시 불확실하다고 말하세요.

→ 내가 누구이며, 무엇을 알고 있는지

나에 관해: [이름] / 역할: [귀하의 역할] / 배경: [도메인]

내 전문 분야: [알고 있는 내용]

공부 중인 내용: [지식 갭]

이러한 정보에 따라 각 답변의 깊이를 조정하세요. 이미 알고 있는 내용을 과도하게 설명하지 마세요. 필요한 배경 정보를 건너뛰지 마세요.

→ 현재 프로젝트 맥락

저는 현재 [프로젝트 이름]을 수행 중이며 / 목표는 [구체적 결과]이고 / 사용자는 [누구인지]이며 / 기술 스택 배경은 [관련 제약 사항]이며 / 피해야 할 것은 [목록]입니다.

이러한 맥락을 모든 작업에 적용하세요. 맥락과 일치하지 않는 요구 사항이 있는 경우 실행하기 전에 지적하세요.

→ 당신의 표현 스타일 잠금

나의 작성 스타일은: [당신의 표현 스타일 설명]

문장 길이: [기호]

자주 사용하는 단어: [예시]

사용하지 않을 단어: [예시]

서식: [프로사 또는 구조물]

당신이 나를 대신하여 어떠한 내용을 작성할 때는, 엄격히 이 스타일을 준수해야 하며, 본인의 표현 방식을 기본적으로 사용하지 마세요.

매일 컨텍스트를 설명하는 데 소요되는 시간: 30 분

개발자 시급 기준 150 미국 달러: 하루에 75 미국 달러

주당: 개발자 당 375 미국 달러

5 인 팀: 주당 1875 미국 달러

이 부분의 CLAUDE.md 설정 시간: 총 45 분

피해야 할 오류: CLAUDE.md를 처음부터 쓰지 마십시오. 먼저 아래 프롬프트를 사용한 후 결과물을 편집하십시오:

나에 대해 당신에게 말했던 내면, 내 프로젝트, 그리고 내가 일하길 희망하는 방식을 기반으로 나를 위한 완전한 CLAUDE.md 파일을 작성해주십시오. 내용은 다음을 포함해야 합니다: 내가 누구인지, 내 기술적 배경, 내 의사 소통 선호도 및 각 세션에서 지켜야 하는 기본 행동. 구체적이고 플레인 텍스트로, 500 단어 이내로.

행동 제한: 당신이 승인하지 않은 그 "$150 시급" 변경 사항들

당신은 Claude에게 함수를 고치도록 했습니다.

결과적으로 그는 세 개의 파일을 리팩토링하고, 변수 이름을 변경하고, 가져오기를 재구성했으며, 당신이 신경 쓰여 만든 주석을 다시 작성했습니다.

그러나 이 모든 것은 당신의 승인을 거치지 않았습니다.

이러한 불필요한 변경 사항을 검토하고 롤백하는 데는 1시간이 소요될 수 있으며, 즉 150 미국 달러입니다. 매주 세 번 발생하면, 450 미국 달러입니다. 5 인 팀의 경우, 주당 2250 미국 달러가 필요하여 승인되지 않은 변경 사항을 정리합니다.

다음의 7 가지 규칙은 CLAUDE.md의 행동 제한 부분에 넣어야 합니다.

→ 범위 엄격히 제어

현재 작업에 직접적으로 관련된 파일, 함수 및 코드 라인만 수정하세요. 명시적으로 수정해 달라고 지시하지 않은 내용을 리팩토링하거나, 이름을 바꾸거나, 재구성하거나, 재서식화하거나 또는 "최적화"하지 마세요.

다른 곳을 수정해야 한다고 판단되면, 맨 뒤에 메모로 설명하세요. 그 부분에 절대 손대지 마세요.

→ 중요한 변경 사항 전에 확인

이미 만들어 둔 내용에 중대한 수정을 가하기 전에, 섹션을 다시 쓰거나 단락을 삭제하거나, 구조를 리팩토링하거나, 어조를 변화시키는 것을 포함하여, 무엇을 변경할 계획인지와 왜 변경하는지를 명확히 설명한 후에 멈추고 확인을 받으신 후 계속하십시오.

→ 파괴적인 작업 전에 확인 필요

어떤 파일도 삭제하거나 기존 코드를 덮어쓰거나 데이터베이스 레코드를 삭제하거나 의존성을 제거하기 전에 멈추고, 어떤 콘텐츠가 영향을 받을지 구체적으로 나열하고, 나로부터 명확히 확인을 요청해야 합니다. 내가 현재 메시지에서 "예"라고 말할 때만 진행할 수 있습니다.

"이전에 언급한 적이 있다"는 확인과 동일하지 않습니다.

→ 프로덕션 환경 작업은 강제 일시 중지해아 합니다

다음 작업은 현재 세션에서 명확한 확인을 받아야 하며, 예외는 없습니다:

· 어떤 환경으로 배포하거나 푸쉬하기

· 마이그레이션 실행 또는 데이터베이스 구조 변경

· 외부 API 호출 전송

· 불가역적인 부작용이 있는 명령 실행

· 반드시 현재 메시지에서 "예"라고 말해야 합니다.

→ 언제나 변경 내용을 표시해야 합니다

어떤 코딩 작업을 완료한 후에는 끝에 다음을 포함해야 합니다:

수정된 파일: 수정된 모든 파일 나열

수정된 내용: 각 파일에 대해 한 문장으로 설명

의도적으로 수정되지 않은 파일

후속 처리해야 할 사항

→ 명확한 확인 없이 내 대신 행동하면 안 됩니다

현재 메시지에서 명확한 확인을 받지 않은 경우, 나를 대신하여 어떤 콘텐츠를 보내거나 게시하거나 공유하거나 일정을 잡을 수 없습니다. 이메일, 캘린더 초대, 문서 공유 또는 현재 대화 외부에서 발생하는 작업을 포함합니다. 현재 메시지에서 "예"라고 말해야 합니다.

→ 코드를 작성하기 전에 생각하세요

아키텍처 결정, 복잡한 문제 디버깅 또는 간단하지 않은 기능 개발과 관련된 작업의 경우, 절차적으로 문제를 분석하고 코드를 작성하세요. 추론 과정을 보여주고, 불확실한 부분을 지적한 후에 실행해야 합니다.

주간으로 불필요한 범위 변경 롤백: 150 달러

주간 수동 diff 확인: 75 달러

개발자 별 행위 관련 낭비: 225 달러 / 주

5명의 팀: 1125 달러 / 주

CLAUDE.md 행위 부분 설정 시간: 30 분

기억과 기술 스택: Claude Code가 정말 신뢰할 수 있도록 설정하기

Claude는 다른 세션 간에 모든 것을 잊어버립니다.

당신이 내린 모든 결정, 실패한 모든 계획, Prisma 대신 Drizzle을 선택했던 6개월 전, 그리고 특정 고객 요구 사항에서의 제약 조건 —— 모두가 잊혀질 것입니다.

그리고 그 후, 예전에 이미 제외한 계획을 다시 제안할 것입니다.

이 부분은 Claude에게 현재 "진정한 기억"에 가장 가까운 메커니즘을 제공하고, 동시에 당신의 기술 스택을 고정시켜 기존 아키텍처를 파괴할 수 있는 도구를 계속 추천하지 않도록 합니다.

→ MEMORY.md 의사 결정 로그

MEMORY.md라는 파일을 프로젝트에서 유지보수하십시오. 중요한 결정을 내릴 때마다 새로운 레코드를 추가하십시오:

·무엇을 결정했는가;

·왜 그런 결정을 내렸는가;

·무엇을 제외했고 왜 그것을 제외했는가.

각 세션 시작 시 MEMORY.md를 먼저 읽으십시오. 미리 알리지 않은 한 기존의 결정과 충돌하면 안 됩니다.

→ 세션 종료 요약

제가 "세션 종료", "정리", 또는 "여기까지 하죠"라고 말할 때, 해당 세션 요약을 MEMORY.md에 기록하십시오. 이 내용에는 다음이 포함되어야 합니다:

·무엇을 다뤘는지;

·무엇이 완료되었는지;

·아직 진행 중인 사항은 무엇인지;

·어떤 결정을 내렸는지;

·다음 세션에 우선 처리해야 할 사항.

→ ERRORS.md 실패 로그

ERRORS.md라는 파일을 유지하십시오. 특정 계획을 두 번 이상 시도했음에도 성공하지 못한 경우 다음을 기록하십시오:

·무엇이 효과가 없었는가;

·마지막으로 어떤 계획이 효과가 있었는가;

·다음에 주의해야 할 사항.

유사한 작업에 대한 제안을 하기 전에 ERRORS.md를 확인하십시오.

→ 영구적 사실 목록

다음 사실들은 이 프로젝트에 대해 항상 성립하며 각 세션에 절대적으로 적용되어야 합니다:

[당신의 영원한 제약, 아키텍처 의사결정 및 규칙]

만약 어떤 작업이 이러한 사실과 충돌하는 경우 실행하기 전에 지적하십시오.

→ 기술 스택 잠금

이 프로젝트의 기술 스택은 다음과 같으며, 항상 이러한 도구들을 사용합니다. 명시적으로 요청하지 않는 한 대체 제안을 하지 마십시오:

언어: [예: TypeScript]

프레임워크: [예: Next.js 14]

패키지 관리자: [예: pnpm]

데이터베이스: [예: Prisma를 사용한 PostgreSQL]

테스트: [예: Vitest]

스타일: [예: Tailwind CSS]

만약 어떤 도구가 적합하지 않다고 생각된다면 지적할 수 있습니다. 그러나 명시적으로 정의된 기술 스택을 사용해야 합니다.

→ 어려운 결정을 위한 확장 사고 활성화

시스템 아키텍처, 성능 균형, 데이터베이스 설계 또는 장기 기술 결정과 관련된 문제에 대해 확장 사고 모드를 사용하십시오.

문제를 단계적으로 분석하고, 고려하지 않았을 수 있는 희생을 제안하고, 확장이 될 경우 성립되지 않을 수 있는 가정을 지적한 다음 권고사항을 제공하십시오.

→ 그 4가지 천재의 레드룰

Karpathy는 Claude Code가 실패하게 만드는 4가지 행동을 요약했습니다. 한 개발자가 이를 아래 4줄의 규칙으로 추려내었습니다. 결과적으로 코딩 정확도가 65%에서 94%로 향상되었습니다.

먼저 묻고, 가정하지 마십시오.
불분명한 부분이 있을 경우 첫 번째 줄 코드를 작성하기 전에 물어보십시오. 의도, 아키텍처 또는 요구 사항에 무성의한 가정을 하지 마십시오.

가장 간단한 솔루션을 먼저 구현하십시오.
항상 작동하는 가장 간단한 솔루션을 먼저 구현하십시오. 명시적으로 요청되지 않은 추상화 계층이나 유연성을 추가하지 마십시오.

관련 없는 코드에 손대지 마십시오.
해당 작업과 직접적으로 관련이 없는 파일이나 함수를 수정하지 마십시오. 최적화할 수 있다고 생각하더라도 그 부분을 건드리지 마십시오.

불확실성을 명확히 표시하십시오.
특정 솔루션이나 기술 세부사항에 대해 확신이 없는 경우 계속하기 전에 밝혀주십시오. 확신이 없는데도 자신감을 내비치는 것은 지식 결핍을 인정하는 것이 생성하는 피해보다 더 큽니다.

· 매주 잊어버린 결정과 잘못된 제안으로 인한 복구 비용: 개발자 당 300 달러

· 잘못된 기술 스택 권장 및 호환되지 않는 도구: 주당 75 달러

· 개발자 당 메모리 관련 낭비: 주당 375 달러

· 5 인 팀: 주당 1875 달러

· MEMORY.md + ERRORS.md + 기술 스택 설정 시간: 20 분

결론

전체 비용 계산은 다음과 같습니다:

· 매주 문맥 반복 설명: 375 달러

· 매주 허가되지 않은 변경 롤백: 225 달러

· 잊어버린 결정으로 인한 문제 처리: 375 달러

· 개발자 당 주당 총 낭비: 975 달러

5 인 개발 팀의 경우: 주당 4875 달러. 연간 253,500 달러

반면 CLAUDE.md 설정에는 총 2 시간만 소요됩니다.

단순히 Karpathy의 4 가지 규칙만으로도 코딩 정확도가 65%에서 94%로 개선되었습니다.

텍스트 파일 하나, 21 가지 규칙, 2시간 작업량만으로도 가능합니다.

이 설정을 완료한 개발자는 사실상 더 신뢰할 수 있는 Claude를 사용하고 있습니다: 결정을 기억하고 작업 범위를 제어하며 파괴적인 작업을 수행하기 전에 확인을 요청하며 기존 아키텍처를 파괴할 가능성이 있는 프레임워크를 권장하지 않습니다.

아직 설정하지 않은 사람들은 매주 975 달러를 반복해서 자신을 설명하느라 소비합니다.

참고: 먼저 Karpathy의 4 가지 규칙부터 시작하십시오. 딱 이 4 가지만 필요합니다. 이제 이를 프로젝트 루트 디렉토리에 CLAUDE.md라는 새 파일로 붙여넣기하면 됩니다. 2분만 소요됩니다. 그 후 매주 발견한 결함을 점진적으로 보완해 나가면 됩니다.

정보가 휩쓸려 사라지기 전에 먼저 저장해 두세요. 유용하다고 생각하면 실제로 필요로 하는 사람과 공유할 수도 있습니다.

[원문 링크]

BlockBeats 공식 커뮤니티에 참여하세요:

Telegram 구독 그룹：https://t.me/theblockbeats

Telegram 토론 그룹：https://t.me/BlockBeats_App

Twitter 공식 계정：https://twitter.com/BlockBeatsAsia