클로드 코드(Claude Code) CLAUDE.md 세팅, 알려진 노하우들과 공식 문서 업데이트 정리

CLAUDE.md는 클로드 코드가 일반 세션에서 적용 경로에 따라 읽는 프로젝트 지침 파일입니다. 예를 들어 “날짜는 연-월-일로 적는다”처럼 반복해서 필요한 규칙을 저장합니다. .md는 제목과 목록을 기호로 쓰는 마크다운 파일 형식입니다.

정작 알기 어려운 것은 그다음입니다. 읽은 파일 목록은 확인할 수 있지만, 목록에 있다는 사실만으로 모든 금지 규칙을 지켰다고 판단할 수는 없습니다. 그래서 잘 쓴다는 사람들의 요령이 입에서 입으로 옮겨 다니고, 그 가운데 일부는 공식 문서와 어긋난 채로 굳어집니다.

어긋난 요령을 믿으면 문제가 생겼을 때 원인을 엉뚱한 곳에서 찾게 됩니다. 금지 규칙이 지켜지지 않았을 때 문장 표현을 계속 고치는 식입니다. 이 글에서는 규칙 파일에 남길 내용과 별도 설정이 필요한 동작을 나눠 봅니다. 본문의 사용 조건은 2026년 10월 4일 공식 문서를 기준으로 하며, 기존 화면과 가격 변경 사례는 2026년 8월 28일 자료로 보존했습니다.

처음이라면 규칙 세 줄로 확인하기

중요한 자료가 없는 연습 폴더에서 시작합니다. VS Code 같은 편집기로 폴더의 최상위 위치에 CLAUDE.md를 만들고 다음 내용을 저장합니다. 같은 이름의 파일이 이미 있다면 덮어쓰지 말고 새 연습 폴더를 만듭니다.

YYYY-MM-DD는 연도 네 자리, 월 두 자리, 일 두 자리를 쓰는 형식입니다. 예를 들어 2026년 10월 12일은 2026-10-12입니다. 파일 이름이 CLAUDE.md.txt가 되지 않았는지 확인합니다. 해당 폴더의 터미널에서 claude로 Claude Code를 실행한 뒤 대화 입력칸에 /context를 넣고 Memory files에 이 파일의 경로가 있는지 봅니다. /context는 PowerShell이나 맥 셸에 넣는 명령이 아닙니다.

이제 “2026년 10월 12일 독서 모임 안내를 두 문장으로 써 줘. 장소는 아직 정하지 않았어. 파일은 만들지 마.”라고 요청합니다. 날짜가 2026-10-12이고 장소를 지어내지 않았으면 이번 응답이 두 규칙에 맞는 것입니다. 요청 자체에도 날짜가 있으므로, 응답만으로 파일 로딩을 입증할 수는 없습니다. 앞서 확인한 파일 목록과 함께 봅니다. 예를 들면 “독서 모임은 2026-10-12에 열립니다. 장소는 미정입니다.”처럼 나올 수 있습니다.

틀렸다면 파일이 실제로 읽혔는지 먼저 보고, 상위 폴더나 다른 지침에 충돌하는 규칙이 있는지 확인합니다. 다음에는 “미정” 대신 “장소는 추후 안내”라고 쓰도록 파일의 해당 규칙을 바꿉니다. 저장하고 /exit로 종료한 뒤 같은 폴더의 터미널에서 claude로 새 세션을 열어 같은 요청을 반복합니다. 문장을 바꾸고 결과를 다시 확인하는 것이 첫 연습입니다.

CLAUDE.md 권장 길이는 200줄 미만입니다

위 화면은 클로드 코드 공식 문서의 지시문 작성 섹션입니다. Size 항목에 파일 하나당 200줄 미만을 목표로 하라고 적혀 있습니다. 300줄이 아닙니다.

클로드 코드 공식 문서가 권하는 CLAUDE.md 길이는 파일 하나당 200줄 미만입니다.

같은 문단에 이유도 붙어 있습니다. 파일이 길어질수록 컨텍스트, 즉 모델이 현재 답변을 만들 때 참고하는 문맥을 더 많이 차지하고 지시를 덜 따를 수 있다는 설명입니다. 이 권장은 200줄에서 파일을 자른다는 뜻이 아니라, 핵심 지시를 짧게 유지하라는 뜻입니다.

일반적인 로딩 경로에서 클로드 코드는 약 4.2MB인 4MiB까지의 CLAUDE.md를 통째로 읽어 들이고 그보다 큰 파일만 건너뜁니다. 1,000줄짜리 파일도 이 용량과 로딩 조건을 충족하면 전부 읽을 수 있습니다. 다만 벽에 붙인 안내문이 빽빽할수록 지나가는 사람이 절반만 읽고 마는 것처럼, 긴 파일은 중요한 규칙을 놓칠 가능성을 키웁니다. 200줄 미만이면 모든 규칙을 반드시 지킨다는 뜻도 아닙니다.

헷갈리기 쉬운 파일이 하나 더 있습니다. 자동 메모리 파일인 MEMORY.md에는 권고가 아니라 진짜 상한이 걸려 있어서, 첫 200줄 또는 25KB 가운데 먼저 닿는 쪽까지만 세션 시작 때 읽히고 그 뒤 내용은 시작 시 문맥에 포함되지 않습니다. 필요할 때 별도 파일 읽기로 확인하는 것과는 다릅니다. 200줄이라는 같은 숫자가 두 파일에 나오지만 한쪽은 권고이고 다른 쪽은 실제 한계입니다.

절대 금지 섹션이 막아 주지 못하는 이유

세팅 이야기에서 가장 자주 나오는 요령이 금지 항목을 따로 모아 선을 긋는 방식입니다. 방향은 나쁘지 않습니다. 구체적이고 짧은 문장이 잘 지켜진다는 공식 권고와도 맞습니다.

문제는 그 섹션에 기대하는 효과입니다. 훅이라는 말은 CLAUDE.md보다 상대적으로 낯설 수 있는데, 쉽게 말하면 정해진 시점에 클로드의 판단과 상관없이 실행되는 검사 명령입니다. 위 화면의 첫 문단이 이 대목을 분명하게 적고 있습니다. 클로드는 CLAUDE.md와 자동 메모리를 강제 설정이 아니라 참고 자료로 다루며, 어떤 동작을 클로드의 판단과 무관하게 막으려면 PreToolUse 훅을 쓰라는 내용입니다.

공식 문서는 CLAUDE.md를 강제 설정이 아니라 참고 자료로 규정합니다. 동작 차단은 해당 동작에 맞게 구성한 훅과 권한 설정으로 확인합니다.

문제 해결 섹션에는 이유까지 적혀 있습니다. CLAUDE.md 내용은 시스템 프롬프트의 일부가 아니라 시스템 프롬프트 뒤에 오는 사용자 메시지로 전달됩니다. 읽고 따르려 하지만 엄격한 준수가 보장되지는 않는다는 것이 문서의 표현입니다.

벽에 "이 문은 열지 마시오"라고 써 붙이는 것과 문에 잠금장치를 다는 것은 다릅니다. 안내문은 읽는 사람의 판단에 맡기고, 잠금장치는 판단과 상관없이 막습니다. CLAUDE.md를 안내문, 차단하도록 구성한 훅과 권한 설정을 잠금장치로 생각할 수 있습니다. 다만 자물쇠도 설치한 문에만 작동하듯, 설정한 도구와 경로 및 실행 모드 안에서 차단되는지 검증해야 합니다. 단순 알림용 훅은 작업을 막지 않습니다.

무엇을 어디에 두어야 하는지도 문서가 표로 정리해 두었습니다.

스타일 지침은 문장으로 쓰고, 실행을 반드시 제한해야 하는 동작은 권한이나 차단 검사로 설계합니다. 다른 도구나 경로로 같은 동작이 가능한지까지 확인합니다. 초보자가 처음부터 직접 보안 훅 코드를 작성해야 한다는 뜻은 아닙니다.

길어진 지시를 옮겨 두는 세 곳

길이를 줄일 때는 중복되거나 오래된 규칙부터 정리합니다. 필요한 내용이라면 매번 필요한지, 특정 작업에서만 필요한지에 따라 위치를 나눕니다. 옮길 곳은 세 군데이고 성격이 서로 다릅니다.

• 경로 규칙(.claude/rules/): 파일 종류나 폴더에 묶어 두는 지시입니다. paths 항목에 패턴을 적으면 클로드가 그 파일을 읽을 때만 규칙이 따라 들어옵니다.
• 스킬(skills): 절차를 담습니다. 일반적으로 호출할 때 본문을 읽습니다. 이름과 설명은 평소 목록에 포함될 수 있고 미리 불러오는 서브에이전트 설정 같은 예외도 있습니다.
• 훅(hooks): 앞 절에서 다룬 잠금장치입니다. 지원되는 시점에 실행할 검사를 연결하고 실패 시 차단하는지 확인합니다.

여기서 착각하기 쉬운 것이 @경로 가져오기입니다. CLAUDE.md를 여러 파일로 쪼개 불러오는 방식인데, 공식 문서는 이 방법이 정리에는 도움이 되지만 컨텍스트를 줄이지는 못한다고 적고 있습니다. 가져온 파일도 시작할 때 함께 읽히기 때문입니다. 서랍을 여러 개로 나눠도 전부 꺼내 놓는다면 책상 위는 그대로인 셈입니다.

스킬 문서의 설명이 이 차이를 잘 보여 줍니다. 스킬 본문을 필요할 때 불러오면 긴 참고 자료 전체를 매번 시작 문맥에 넣지 않아도 됩니다. 스킬 목록의 이름과 설명, 실제 호출한 본문과 도구 결과는 여전히 문맥과 사용량에 영향을 줍니다.

일반 세션에서는 스킬 본문을 호출할 때 읽습니다. 매번 필요하지 않은 긴 절차를 스킬로 분리하면 시작 시 넣는 문맥을 줄일 수 있습니다.

공식 문서는 CLAUDE.md에 무엇을 남길지도 정해 두었습니다. 빌드 명령, 규칙, 프로젝트 구조처럼 매 세션에 필요한 사실입니다. 여러 단계를 거치는 절차이거나 코드베이스의 일부에서만 쓰이는 내용은 스킬이나 경로 규칙으로 보내라고 안내합니다.

참고: 규칙 길이와 모델 비용은 따로 확인하기

비싼 모델이 늘 정답은 아니라는 이야기도 자주 오갑니다. 이 방향 자체는 공식 안내와 크게 다르지 않습니다. 다만 근거로 딸려 오는 숫자 하나가 이미 지난 정보가 되었습니다.

여러 정리 글이 소네트 5의 100만 토큰당 2달러와 10달러를 출시 기념 가격으로 소개하면서 9월 1일부터 3달러와 15달러로 오른다고 적어 두었습니다. 위 화면의 안내 상자가 그 대목을 뒤집습니다. 2달러와 10달러가 이제 표준 가격이 되었고 예정되어 있던 인상은 일어나지 않는다는 내용입니다.

다음 표는 2026년 8월 28일에 정리한 모델별 API 표준 단가 사례입니다. 월 구독료가 아니며 전체 모델 목록이나 현재 모델 선택 추천도 아닙니다. 실제 사용 전 현재 가격표를 확인합니다.

토큰은 모델이 글을 처리할 때 나누는 단위이고 입력은 보내는 내용, 출력은 답변입니다. 예를 들어 소네트 5 표준 단가로 입력 1,000토큰과 출력 1,000토큰이면 캐시나 다른 비용을 제외한 계산은 0.002달러 + 0.01달러 = 0.012달러입니다.

같은 화면 아래쪽에 가격 비교를 흔들 수 있는 안내가 하나 더 있습니다. 클로드 4.7 이후 모델은 새 토크나이저를 쓰는데, 같은 글의 토큰 수가 약 30% 늘 수 있으며 정확한 차이는 글과 작업에 달렸다는 설명입니다. 토큰당 단가만 비교하면 실제 청구액과 어긋날 수 있다는 뜻입니다.

공식 문서는 모델을 고를 때 사고량도 함께 비교하도록 안내합니다. 최근 오퍼스와 소네트 모델이 지원하는 effort, 즉 사고량 항목을 조절하면 같은 모델 안에서 지능과 비용을 맞바꿀 수 있고, 모델을 바꾸는 것보다 이쪽이 더 나은 조절 수단인 경우가 많다는 내용입니다. 항상 effort를 낮추라는 뜻은 아닙니다. 같은 예제와 성공 기준으로 결과, 사용량과 시간을 비교해 조절합니다. 이 글의 규칙 파일 실습에는 모델 변경이 필요하지 않습니다.

긴 작업을 맡길 때 남기는 진행 기록

에이전트에게 긴 작업을 맡길 때 메모리 구조가 중요하다는 이야기도 방향은 맞습니다. 앤트로픽이 공개한 긴 작업 에이전트 구성 글에 실제 사례가 정리되어 있습니다.

그 글이 다룬 실험은 클로드에게 claude.ai와 비슷한 서비스를 처음부터 만들게 한 것입니다. 세션이 끊겨도 다음 세션이 이어서 일하게 만드는 것이 핵심 과제였고, 해법은 파일 두 개와 스크립트 하나였습니다.

• 진행 기록 파일: 에이전트들이 무엇을 했는지 남기는 기록입니다. 새 세션이 깨끗한 컨텍스트로 시작할 때 깃 기록과 함께 읽어 현재 상태를 빠르게 파악합니다.
• 기능 목록 파일: 구현해야 할 항목을 구조화된 형식으로 적어 둡니다. 사례에서는 200개가 넘는 세부 기능이 들어갔습니다.
• 초기화 스크립트: 매 세션 시작 때 실행해 환경을 같은 상태로 맞춥니다.

작업 방식에도 규칙이 있습니다. 한 번에 기능 하나만 다루고, 검증을 마친 뒤에만 통과로 표시하게 했습니다. 다 됐다고 미리 선언해 버리는 문제를 막기 위한 장치입니다.

작업 일지를 남겨 두면 다음 사람이 어디까지 됐는지 묻지 않고도 이어 갈 수 있듯, 진행 기록 파일은 컨텍스트가 비워진 다음 세션에 같은 역할을 합니다. 상태를 대화가 아니라 파일에 두는 것이 핵심입니다.

바이브 코딩에서 API 키가 새는 지점

빠르게 만드는 것까지는 잘 되는데 데이터 설계와 보안에서 막힌다는 이야기도 자주 들립니다. API 키는 외부 서비스가 요청자를 확인하는 비밀 인증값입니다. 이 값의 유출 문제는 공개된 조사 자료가 있습니다.

커밋은 Git에 저장하는 파일 변경 기록이고, 하드코딩은 값을 코드 안에 직접 적는 것입니다. 깃가디언이 2026년 3월 발표한 조사에 따르면 2025년 한 해 공개 깃허브 커밋에서 발견된 하드코딩 비밀 정보는 2865만 건으로 전년 대비 34% 늘었습니다. 같은 조사에서 Claude Code 공동 작성으로 식별한 공개 커밋의 비밀 정보 유출 비율은 3.2%, 전체 공개 GitHub 커밋의 기준 비율은 1.5%였습니다. 모든 AI 도구의 사용자를 조사한 비율이나 개인이 사고를 겪을 확률이 아닙니다.

이런 조사 수치는 공식 문서가 아니라 보안 업체의 집계라는 점을 감안해 읽는 편이 좋습니다. 전체 기준 집단에는 AI 관련 커밋도 포함되므로 사람만 쓴 코드와의 순수 비교가 아닙니다. 관찰된 비율 차이만으로 AI가 유출을 일으킨 원인이라고 확정할 수 없습니다. 공개 전 비밀값 검사가 필요하다는 근거로 읽을 수 있습니다.

앞 절의 구분이 여기에도 그대로 적용됩니다. 키를 코드에 넣지 말라고 CLAUDE.md에 적어 두는 것은 안내문이고, 대상 파일을 검사하고 탐지 시 커밋을 막도록 구성한 검사는 잠금장치에 해당합니다. 탐지하지 못하는 비밀값도 있을 수 있어 완전한 유출 방지를 보장하지는 않습니다. 비밀값을 다루는 작업에서는 문장 지시와 실제 검사를 함께 적용합니다.

CLAUDE.md가 200줄을 넘으면 어떻게 되나요?

200줄에서 파일이 잘리지는 않습니다. 일반적인 로딩 경로에서는 4MiB까지의 CLAUDE.md를 전부 읽어 들이고 그보다 큰 파일만 건너뜁니다. 200줄은 지시가 얼마나 잘 지켜지는지에 관한 권고입니다.

길이가 부담스러우면 두 가지를 먼저 해 볼 수 있습니다. 특정 파일에서만 쓰이는 지시는 경로 규칙으로 옮기고, 여러 단계를 거치는 절차는 스킬로 내립니다. 지원 버전의 진단 기능을 쓴다면 삭제 제안을 자동으로 적용하지 않고 현재 필요한 규칙인지 먼저 검토합니다. 코드에서 알아낼 수 있는 폴더 구조나 의존성 목록을 덜어 내고, 도구 기본값과 다른 규칙이나 주의점은 남기는 방식입니다.

지시가 서로 부딪히면 어느 쪽이 이기나요?

공식 문서는 규칙 두 개가 서로 어긋나면 클로드가 임의로 한쪽을 고를 수 있다고 적고 있습니다. 우선순위가 보장되지 않는다는 뜻이라, 부딪히는 규칙을 남겨 두는 것 자체가 위험합니다.

클로드 코드가 파일을 여러 곳에서 읽는다는 점도 함께 봐야 합니다. 일반 설정에서는 현재 폴더와 그 위 폴더들의 CLAUDE.md를 읽어 이어 붙이고, 실행한 위치에 가까운 파일을 나중에 읽습니다. 큰 저장소에서 다른 팀의 파일까지 딸려 온다면 claudeMdExcludes 설정으로 뺄 수 있습니다. bare나 조직의 managed-only처럼 시작 지침을 제한하는 설정은 예외가 있습니다. 어떤 파일이 실제로 읽혔는지는 세션에서 /context를 실행해 메모리 파일 목록으로 확인합니다.

Sources

• How Claude remembers your project, Claude Code Docs
• Extend Claude with skills, Claude Code Docs
• Pricing, Claude Platform Docs
• Choosing the right model, Claude Platform Docs
• Effective harnesses for long-running agents, Anthropic
• GitGuardian 2026 비밀 정보 유출 조사
• Claude Code 모범 사례

3줄 요약

1. CLAUDE.md는 프로젝트 지침 파일이며 공식 권장 길이인 200줄 미만은 강제 용량 제한과 다릅니다.

2. 작은 규칙부터 저장해 새 세션의 로딩 목록과 실제 결과를 확인하고 잘못된 동작은 조건을 좁혀 수정합니다.

3. 확실한 실행 제한에는 권한 설정과 훅 등의 별도 구성이 필요하며 적용 범위와 차단 결과를 검증합니다.