CLAUDE.md (CLAUDE.md) — 쉬운 기술 사전

신입 직원이 첫날 아침 책상에서 발견하는 바인더를 떠올려 보세요. 회사 전체 규정집이 아니에요. 이 특정 직무에 관한 규칙이에요. 모든 것이 어디에 있는지, 여기서는 어떻게 일하는지, 건드리면 안 되는 부분이 어디인지.

CLAUDE.md는 그 바인더예요. 프로젝트를 위한. 평범한 텍스트 파일이에요(Markdown 형식, 특별한 것 없어요). 폴더에 넣어 두면, 사람이든 AI 에이전트든 그 폴더를 열 때마다 다른 무엇보다 이 파일을 먼저 읽어요. 매번 세션을 시작할 때 설명을 반복하지 않아도 돼요. 한 번 적어두면 파일이 대신 말해줘요.

대부분 놓치는 사실: 파일은 두 종류예요.

시스템 프롬프트는 AI가 어디서나 지니는 정체성이에요. CLAUDE.md는 그것을 좁혀줘요. 그리고 두 층위로 나뉘어요.

전역 CLAUDE.md: 모든 프로젝트에서 AI가 어떻게 행동했으면 하는지를 적어요. 나 개인의 운영 매뉴얼이에요. 특정 프로젝트 폴더가 아니라 홈 설정 폴더에 둬요.
프로젝트 CLAUDE.md: 이 코드베이스에 관한 규칙이에요. 프로젝트 폴더 안에 두고, 그 폴더를 여는 누구든(혹은 어떤 에이전트든) 함께 읽어요.

AI는 두 파일을 모두 읽고 쌓아요. 전역 규칙을 먼저 읽고, 그 위에 프로젝트 규칙을 얹어요. 충돌이 생기면 대개 더 구체적인 쪽(프로젝트)이 우선해요.

무엇을 어디에 넣을까요. 판단 기준은 간단해요. 무슨 작업을 하든 항상 적용되는 내용이면 전역이고, 이 프로젝트에만 해당하면 프로젝트 수준이에요.

전역 (나와 내 작업 방식):

"쉬운 말로 설명해줘. 나는 개발자가 아니야."
"애매하면 만들기 전에 물어봐. 추측하지 마."
"코드에 비밀값 넣지 마. 키는 항상 env 파일에."

프로젝트 (이 코드베이스):

"우리는 이 데이터베이스를 쓴다. 다른 걸 추가하지 마."
"브랜드 말투는 따뜻하고 인간적으로. 기업 말투 금지."
"완료라고 하기 전에 항상 테스트를 돌려."
"checkout 파일은 절대 건드리지 마."

알아두면 유용한 현실적인 이야기예요. 많은 분이 ~/.claude/CLAUDE.md에 전역 파일이 이미 있다고 생각해요. 대개는 없어요. 직접 만들어야 해요. 그리고 생태계는 조용히 도구에 종속되지 않는 파일명인 AGENTS.md로 표준화하는 추세예요. Claude, Codex 등 여러 도구가 각자의 파일을 요구하는 대신, 동일한 규칙서 하나를 함께 읽도록 하기 위해서예요. (제 전역 파일도 실제로 AGENTS.md예요. 같은 개념이고, 모든 도구가 하나의 파일을 읽어요.) 어떤 도구가 CLAUDE.md를 요구하는데 AGENTS.md만 있다면, 있는 파일을 가리켜 주면 돼요. 파일명은 그냥 레이블이에요. 내용이 중요해요.

복사해서 바로 쓸 수 있는 프로젝트 수준 CLAUDE.md 예시예요:

# CLAUDE.md

## 이게 뭔가

Shopify 소형 브랜드 스토어. 커스텀 테마 + 리뷰·이메일용 앱 두어 개.

## 어떻게 만들어졌나

- 테마: Liquid과 순수 JavaScript. React 없음.
- 이메일: Klaviyo. 목록 ID를 하드코딩하지 말고 env 파일에서 읽을 것.
- 이미지는 /assets에 있음. 200kb 이하로 유지.

## 우리가 일하는 방식

- 브랜드 말투는 따뜻하고 인간적으로. 기업 말투 금지. 느낌표 남발 금지.
- 모바일 우선. 트래픽 대부분이 모바일에서 온다.
- 라이브 테마를 건드리기 전에 항상 복제 테마에서 미리보기.

## 절대 건드리지 말 것

- checkout.liquid
- /vendor 안의 모든 것
- 라이브 테마 직접 수정 금지. 복제 후 사본 편집, 그다음에 배포.

그리고 전역 파일 (~/.claude/CLAUDE.md 또는 AGENTS.md로 저장):

# 전역 규칙 (모든 프로젝트에 적용)

- 쉬운 말로 설명해줘. 나는 개발자가 아니야.
- 애매하면 만들기 전에 물어봐. 추측하지 마.
- 변경은 작게. 내가 요청한 것만 건드려.
- 코드에 비밀값 넣지 마. API 키는 항상 env 파일에.
- 완료라고 하기 전에 실행해서 실제로 작동하는 것을 보여줘.

마지막 두 규칙이 낯익다면, 그럴 만해요. Andrej Karpathy(Tesla, OpenAI 출신)가 AI 코딩 에이전트가 어디서 잘못되는지에 관한 경험을 정리해 공개했고, 커뮤니티가 그것을 유명한 CLAUDE.md로 만들었어요. 추측하지 말 것, 단순하게 유지할 것, 최소한만 건드릴 것, '완료'의 기준을 명확히 할 것. 시작점으로 그대로 가져다 쓸 만해요. 원본 메모는 X 포스트에 있고, 커뮤니티가 복사해서 바로 쓸 수 있는 파일로 만든 것은 multica-ai/andrej-karpathy-skills(GitHub)에 있어요.

이 파일들과 수개월을 보내며 내린 솔직한 결론이에요. CLAUDE.md는 비개발자 빌더가 작성할 수 있는 것 중 레버리지가 가장 높은 한 가지예요. 오늘 입력하는 프롬프트가 아니에요. 에이전트가 매번 읽는 파일이에요. 제대로 써두면, 에이전트가 같은 실수를 반복하는 루프에서 벗어나요. 처음부터 그 일을 이미 아는 상태로 나타나요.