CLAUDE.md: 코딩 에이전트를 단순하게 강화하는 파일

훌륭한 CLAUDE.md는 모델을 더 똑똑하게 만들지 않습니다. 오히려 에이전트가 리포지토리에 들어올 때마다 모호함을 줄입니다.

이 단순한 메커니즘이 2026년 가장 눈에 띄는 에이전트 프로젝트 중 하나가 된 이유를 설명합니다. 4가지 평문 코딩 규칙을 중심으로 한 리포지토리가 91,000개의 GitHub 스타를 기록했습니다. 이 규칙은 에이전트에게 가정을 드러내고, 단순한 구현을 우선하며, 변경을 외과적으로 제한하고, 검증 가능한 성공을 정의하도록 지시합니다. 이 중 어느 것도 새로운 소프트웨어 엔지니어링이 아니지만, 모든 작업 전에 문맥에 집어넣는 것은 확실히 유용합니다.

바이럴 헤드라인은 한 파일이 91,000개의 GitHub 스타를 받았다고 말했습니다. 2026년 8월 2일 현재 이 리포지토리는 forrestchang에서 multica-ai로 옮겨졌고, 플러그인과 에디터 규칙으로 성장했으며, GitHub API에 따르면 198,529개의 스타에 도달했습니다.^[1] 이 숫자는 계속 변할 것입니다. 지속적인 교훈은 단순하고 지속적인 지시가 에이전트 동작을 어떻게 바꾸는가입니다.

TL;DR

• CLAUDE.md는 Claude Code가 문맥으로 읽어 들이는 Markdown 파일입니다.^[2]
• 바이럴 리포지토리는 일반적인 에이전트 실패를 4가지 규칙으로 축약했습니다. 코딩 전 사고, 단순함 우선, 외과적 변경, 목표 지향 실행입니다.^[3]
• 파일은 거의 모든 세션에서 필요한 사실과 규칙을 포함할 때 가장 잘 작동합니다. 명령, 아키텍처, 규약, 경계, 검증입니다.
• CLAUDE.md는 문맥이며, 강제는 아닙니다. 기술적으로 차단해야 하는 작업에는 권한이나 훅을 사용하세요.^[2]
• 작업 고유 절차는 스킬로, 파일 고유 지침은 .claude/rules/로 옮기세요. 모든 것을 전역으로 로드하면 문맥을 낭비합니다.
• 유용한 파일은 유지 가능한 정도로 짧고, 테스트 가능한 정도로 구체적이며, 에이전트가 실수를 반복할 때마다 개정됩니다.

What is CLAUDE.md?

CLAUDE.md는 Claude Code의 프로젝트 지침 파일입니다. 보통 리포지토리 루트에 커밋되는 평범한 Markdown 파일이며, 에이전트에게 다음과 같은 지속적인 문맥을 제공합니다:

• how to install, test, build, and format the project;
• the parts of the architecture that are not obvious from filenames;
• naming and code-style conventions;
• which generated files should not be edited manually;
• which checks must pass before a task is complete;
• repository-specific safety boundaries.

Claude Code는 세션을 시작할 때 이 파일을 읽습니다. Anthropic은 이를 두 가지 메모리 메커니즘 중 하나로 설명합니다. 사람이 CLAUDE.md 지침을 작성하는 반면, Claude의 자동 메모리는 수정 과정에서 배운 패턴을 저장합니다.^[2]

That sounds like configuration, but Anthropic makes an important distinction. These instructions enter the model's context; they are not hard controls. If "never deploy production" must be guaranteed, a PreToolUse hook or permission boundary is the appropriate layer. A sentence in Markdown can guide behavior. It cannot provide a security guarantee.

Why the four-rule file went viral

현재 multica-ai/andrej-karpathy-skills로 불리는 리포지토리는 그 지침이 코딩 모델의 실패 양상에 대한 Andrej Karpathy의 공개 관찰에서 나왔다고 밝힙니다.^[3] 이 인기는 지나치게 복잡하게 해석하기 쉽습니다. 각 규칙은 익숙한 불만을 에이전트가 실제로 수행할 수 있는 행동으로 연결합니다.

이 규칙들은 TypeScript나 데이터베이스 설계, 디버깅을 가르치지 않습니다. 모델이 불확실성과 작업 범위를 대하는 방식을 정할 뿐입니다. 그래서 리포지토리를 옮겨도 그대로 쓸 수 있습니다.

이 단순함은 협업 측면에서도 이점이 있습니다. 팀은 네 가지 원칙을 2분이면 읽고, 그중 하나에 이의를 제기하고, 고치고, 그 변경을 Git에서 리뷰할 수 있습니다. 따로 관리해야 할 숨겨진 프롬프트 플랫폼이 없습니다.

The four principles, translated into project behavior

1. Think before coding

원본 지침은 에이전트에게 가정을 명시하고, 해석이 갈릴 때는 여러 갈래를 제시하고, 불필요한 복잡성에는 반론을 제기하고, 정말로 헷갈릴 때는 멈추라고 요구합니다.^[3]

Project-specific wording makes it stronger:

Before changing an API contract, identify every in-repo consumer and state
whether the change is backward compatible. If product behavior is ambiguous,
stop and ask; do not choose a behavior silently.

일반 원칙은 태도를 정합니다. 거기에 붙인 구체적인 조항은 잘못된 가정이 비싼 대가를 치르는 지점이 어디인지 에이전트에게 알려 줍니다.

2. Simplicity first

"Do not overengineer" is directionally useful but difficult to verify. Add the repository's local definition of simple:

Prefer an existing utility over a new abstraction. Do not introduce a service,
factory, or configuration flag for one call site. Implement only the requested
behavior; list optional follow-ups instead of building them.

이렇게 하면 모델의 예측 가능한 경향 하나가 줄어듭니다. 지금 눈앞의 문제 대신 앞으로 생길 법한 문제군을 미리 풀려는 경향입니다.

3. Surgical changes

에이전트는 코드를 폭넓게 읽기 때문에 주변의 정리할 거리가 눈에 들어옵니다. 그렇다고 해서 하나의 작업이 모든 정리를 허가한 것은 아닙니다.

Every changed line must trace to the request. Preserve surrounding formatting
and naming. Remove imports made unused by your edit, but report unrelated dead
code instead of deleting it.

작은 diff는 리뷰하고, 테스트하고, 되돌리고, 담당자를 정하기가 더 쉽습니다. 에이전트가 용도를 이해하지 못한 코드를 망가뜨릴 가능성도 줄어듭니다.

4. Goal-driven execution

An instruction such as "make it work" leaves the end state undefined. Translate the task into a result the agent can check:

For bug fixes, reproduce the failure with a test before changing production
code. Run the narrowest relevant checks during iteration and the required
project checks before completion. Report commands and outcomes.

자율성이 쓸모를 발휘하는 지점이 바로 여기입니다. 성공 여부를 관찰할 수 있으면, 에이전트는 그럴듯해 보이는 첫 수정에서 멈추지 않고 실패를 놓고 반복할 수 있습니다.

CLAUDE.md에 무엇을 넣을까

Anthropic은 Claude가 모든 세션에서 보유해야 할 사실을 CLAUDE.md에 놓고, 더 많은 단계나 좁은 절차를 더 대상화된 메커니즘으로 옮길 것을 권장합니다.^[2] 유용한 테스트는 "거의 모든 작업의 온보딩 중에 이것을 반복합니까"입니다.

이것을 루트 파일에 넣으세요

• 1단락의 프로젝트 및 아키텍처 설명
• 패키지 매니저와 정규 설치, 개발, 테스트, 타입 확인, 빌드 명령
• 디렉토리 소유권 및 생성 파일 경계
• 언어 또는 패키지 전체에 적용되는 규칙
• 완료의 정의
• 높은 빈도의 실수와 그 수정
• 더 깊은 지시를 찾는 곳

이것을 다른 곳에 넣으세요

간결한 CLAUDE.md 템플릿

이것을 시작점으로 복사한 다음 대괄호 안의 모든 것을 교체하세요. 프로젝트를 제약하지 않는 섹션을 삭제하세요.

# 프로젝트 지시

## 프로젝트

[1단락: 이 리포지토리가 제공하는 것, 주 런타임, 가장
중요한 아키텍처 경계.]

## 명령

- 설치: `[명령]`
- 개발: `[명령]`
- 집중된 테스트: `[파일 또는 패턴이 있는 명령]`
- 전체 테스트: `[명령]`
- 타입 확인: `[명령]`
- 빌드: `[명령]`

## 편집 전

- 제안된 변경 전에 가장 가까운 기존 구현 및 테스트를 읽으세요.
- 공개 동작, 데이터, 보안 또는 호환성에 영향하는 가정을 표명하세요.
- 요청이 여러 실질적으로 다른 해석을 가지면, 물어보세요.

## 범위

- 요청된 동작만 구현하세요.
- 새로운 추상화보다 기존 패턴과 유틸리티를 선호하세요.
- Diff를 외과적으로 유지하세요. 필요하지 않으면 인접 코드를 리팩토링하지 마세요.
- 변경에 의해 생성된 데드 코드만 제거하세요.

## 프로젝트 경계

- `[경로]`는 생성되었습니다. 대신 `[소스 경로 또는 명령]`을 변경하세요.
- `[패키지]`는 `[책임]`을 소유합니다. `[다른 패키지]`에 중복하지 마세요.
- 로그 또는 피클스처에 `[시크릿 또는 개인 데이터 카테고리]`를 노출하지 마세요.

## 스타일

- [포매터 기본값과 다르거나 놓치기 쉬운 2~5가지 규칙.]
- 명시적 규칙이 없으면 주변 파일에 맞추세요.

## 검증

- 버그 수정의 경우, 수정 전에 실패하는 테스트를 추가 또는 업데이트하세요.
- 반복 중에 가장 좁은 관련 확인을 실행하세요.
- 완료 전에 실행하세요: `[필수 명령]`.
- 변경된 파일, 실행된 명령, 결과, 검증되지 않은 위험을 보고하세요.

## 더 깊은 지시

- API 작업: `.claude/rules/api.md`
- 데이터베이스 변경: `[스킬 또는 문서화 경로]`
- 릴리스: `[스킬 또는 문서화 경로]`

템플릿은 의도적으로 단순합니다. CLAUDE.md는 동기 부여 매니페스토처럼 읽히지 않아야 합니다. 에이전트가 별도로 추측해야 할 추측을 줄여야 합니다.

Claude Code가 여러 지시 파일을 로드하는 방법

Claude Code는 현재 작업 디렉토리에서 위로 디렉토리 트리를 걷고, 찾은 CLAUDE.md 및 CLAUDE.local.md 파일을 로드합니다. 실행 디렉토리에 가까운 지시는 문맥에서 나중에 나타납니다. 작업 디렉토리 아래의 중첩 파일은 Claude가 그 하위 디렉토리의 파일을 읽을 때 로드됩니다.^[2]

모노레포의 경우 유용한 계층을 허용합니다.

repo/
├── CLAUDE.md                 # 조직 전체 프로젝트 사실
├── .claude/
│   └── rules/
│       ├── testing.md        # 범위 없는 공유 규칙
│       └── api.md            # paths: packages/api/**
├── packages/
│   ├── web/
│   │   └── CLAUDE.md         # Web 고유 아키텍처 및 확인
│   └── worker/
│       └── CLAUDE.md         # Worker 런타임 제약
└── CLAUDE.local.md           # 개발자 전용 로컬 노트

파일은 엄격한 설정 오버라이드가 아니라 문맥으로 연결됩니다. 모순되는 규칙은 불일관한 동작을 생산할 수 있습니다. 정기적으로 계층을 검토하고 오래된 지시를 제거하세요.

실제 실패에서 파일 개선하는 방법

1일차의 모든 가능한 실수를 예측하려 하지 마세요. 작게 시작하고 반복된 마찰을 백로그로 사용하세요.

1. 실패를 기록하세요. 에이전트가 무엇을 했고, 무엇을 예상했나요?
2. 올바른 레이어를 찾으세요. 이것은 보편적 지시, 경로 범위 규칙, 작업 절차, 또는 하드 보안 제어인가요?
3. 관찰 가능한 규칙을 쓰세요. "주의하세요"를 행동과 조건으로 바꾸세요.
4. 비슷한 작업에서 테스트하세요. 동작이 개선되지만 사소한 작업을 차단하지는 않나요?
5. 오래된 규칙을 삭제하세요. 문맥에는 비용이 있습니다. 오래된 지시는 지시가 없는 것보다 나쁠 수 있습니다.

Anthropic의 실용적 트리거는 기억할 가치가 있습니다. Claude가 같은 실수를 두 번째로 했을 때, 코드 검토가 에이전트가 있어야 할 지식을 발견했을 때, 또는 세션 전체에서 같은 수정을 반복했을 때 무언가를 추가하세요.^[2]

피할 5가지 CLAUDE.md 실수

지시 대신 열망을 쓰기

"훌륭하고 견고한 코드를 쓰세요"는 새로운 정보를 주지 않습니다. "packages/api의 변경 후 pnpm test --filter api를 실행하세요"는 따를 수 있고 확인할 수 있습니다.

거대한 일반 규칙집 복사하기

공개 템플릿은 아이디어를 제공할 수 있지만, 무조건부의 모든 라인은 문맥을 소비하고 프로젝트와 충돌할 수 있습니다. 도움이 되면 4가지 광범위한 동작 원칙을 유지하되, 일반적 기술 조언을 로컬 사실로 바꾸세요.

에이전트가 저렴하게 발견할 수 있는 사실 부호화하기

거의 모든 디렉토리를 나열할 필요는 없습니다. 파일명이 드러내지 않는 경계를 설명하세요. 예를 들어, 어느 패키지가 인증을 소유하는지, 또는 어느 소스가 체크인된 클라이언트를 생성하는지 같은 것입니다.

지시를 보안 제어로 취급하기

"시크릿을 읽지 마세요" 또는 "배포하지 마세요"를 유일한 보호로 의존하지 마세요. 하드 경계의 경우 범위가 지정된 자격 증명, 권한, 샌드박스, 훅을 사용하세요.

파일을 검토하지 않기

명령은 변경되고, 패키지는 이동하며, 오래된 예외는 기본 동작이 됩니다. 소유권을 할당하고 코드처럼 CLAUDE.md를 검토하세요.

그것이 작동하고 있는지 아는 방법

한 데모가 인상적인지 여부로 파일을 판단하지 마세요. 팀이 이미 검토하는 작업을 계측하세요.

• 완료된 작업당 중앙값 변경 라인
• 접촉된 관련 없는 파일
• 리포지토리 규약 위반으로 인한 검토 의견
• 첫 통과 테스트 성공
• 주장된 완료 후 다시 열린 작업
• 지속적 문맥이 되어야 하는 반복된 명확화

바이럴 리포지토리는 같은 결과 수준의 테스트를 시사합니다. 더 적은 불필요한 diff 변경, 과도한 복잡성으로 인한 더 적은 재작업, 실수 후가 아닌 구현 전 명확화입니다.^[3]

FAQ

CLAUDE.md는 어디에 가야 하나요?

팀 공유 프로젝트 지시의 경우, ./CLAUDE.md 또는 ./.claude/CLAUDE.md에 놓고 커밋하세요. 프로젝트 전체의 개인 지시에는 ~/.claude/CLAUDE.md를 사용하고, 한 프로젝트의 개인 노트에는 CLAUDE.local.md를 사용하세요.^[2]

CLAUDE.md는 Cursor 또는 다른 코딩 에이전트와 작동하나요?

CLAUDE.md는 Claude Code 규약입니다. 바이럴 리포지토리는 또한 Cursor 규칙과 플러그인을 제공하는 반면, 다른 에이전트는 AGENTS.md 또는 제품 고유의 규칙 디렉토리 같은 파일을 사용할 수 있습니다. 정규 소스를 유지하고 모든 도구가 같은 파일을 로드한다고 가정하지 않고 의도적으로 적응시키세요.

CLAUDE.md는 얼마나 길어야 하나요?

보편적 라인 수는 없습니다. 거의 모든 세션에서 가치 있는 정보를 포함해야 합니다. 섹션이 한 디렉토리 또는 한 워크플로우에만 적용되면, 경로 범위 규칙 또는 스킬로 옮기세요.

CLAUDE.md가 파괴적 명령을 멈출 수 있나요?

Claude에 실행하지 말라고 지시할 수 있지만, Anthropic은 파일을 설정이 아닌 문맥으로 명시적으로 설명합니다. 신뢰할 수 있는 예방의 경우 권한 또는 훅을 사용하세요.^[2]

첫 파일을 어떻게 만드나요?

Claude Code에서 /init을 실행하여 스타터 CLAUDE.md를 생성하거나 Markdown 파일을 수동으로 만드세요. 그러면 /context를 실행하여 로드되었는지 확인하고, /memory를 실행하여 메모리 파일을 검사 또는 편집하세요.^[4]

파일이 단순한 이유는 문제가 반복되기 때문입니다

코딩 에이전트는 버그를 고치기 전에 500라인 헌법을 필요로 하지 않습니다. 추측할 수 없는 몇 가지 프로젝트 사실, 요청된 변경 주변의 명확한 경계, 완료와 확신을 구분하는 확인이 필요합니다.

그 이유가 4가지 통상적 규칙이 멀리 왔습니다. 개발자가 거의 매일 보는 실패를 다루고, 전체 팀이 편집할 수 있는 형식으로 존재하며, 에이전트가 결정하기 시작하기 전에 로드됩니다. 거기서 시작하세요. 프로젝트 지식은 실제 실패를 방지할 때만 추가하고, 프롬프트 밖에서 중요 경계를 강제하세요.

도구 자체가 처음이라면, 더 광범위한 Claude Code 사용 가이드에서 시작하세요. 설치가 완료되고 다음 질문이 에이전트가 리포지토리에 들어올 때마다 알아야 할 것일 때 이 글을 사용하세요.

References

1. GitHub REST API. multica-ai/andrej-karpathy-skills repository metadata. Retrieved August 2, 2026. api.github.com
2. Anthropic. How Claude remembers your project. Claude Code Docs. Retrieved August 2026. code.claude.com
3. multica-ai. Karpathy-Inspired Claude Code Guidelines. GitHub. Retrieved August 2026. github.com
4. Anthropic. Claude Code commands. Retrieved August 2026. code.claude.com
5. Sumit Pandey. A Single CLAUDE.md File Went Viral. The Reason Is Embarrassingly Simple. Towards Deep Learning, May 2026. towardsdeeplearning.com

Further reading

• reAPI. How to use Claude Code. reapi.ai/blog/how-to-use-claude-code
• reAPI. How to get a Claude API key. reapi.ai/blog/how-to-get-claude-api-key
• reAPI. Claude model catalog. reapi.ai/models