클로드 코드 CLAUDE.md 세팅, 공식 문서와 다른 대목 정리

CLAUDE.md는 클로드 코드가 세션을 시작할 때마다 읽는 지시 파일입니다. 프로젝트 규칙을 여기 적어 두면 매번 설명하지 않아도 된다는 것까지는 쓰는 사람 대부분이 알고 있습니다.

정작 알기 어려운 것은 그다음입니다. 이 파일이 얼마나 길어도 되는지, 여기 적은 금지 규칙이 실제로 지켜지는지는 화면 어디에도 표시되지 않습니다. 그래서 잘 쓴다는 사람들의 요령이 입에서 입으로 옮겨 다니고, 그 가운데 일부는 공식 문서와 어긋난 채로 굳어집니다.

어긋난 요령을 믿으면 문제가 생겼을 때 원인을 엉뚱한 곳에서 찾게 됩니다. 금지 규칙이 지켜지지 않았을 때 문장 표현을 계속 고치는 식입니다. 이 글에서는 요즘 자주 오가는 세팅 이야기를 앤트로픽 공식 문서와 하나씩 맞춰 봤습니다. 2026년 8월 28일 기준입니다.

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

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

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

같은 문단에 이유도 붙어 있습니다. 파일이 길어질수록 컨텍스트를 더 많이 차지하고 지시 준수율이 떨어진다는 설명입니다. 여기서 준수율이라는 말이 중요합니다. 길이 제한이 있어서 잘리는 것이 아니라, 길수록 덜 지켜진다는 이야기입니다.

실제로 클로드 코드는 4MiB까지의 CLAUDE.md를 통째로 읽어 들이고 그보다 큰 파일만 건너뜁니다. 1000줄짜리 파일도 전부 읽히기는 합니다. 다만 벽에 붙인 안내문이 빽빽할수록 지나가는 사람이 절반만 읽고 마는 것처럼, 파일이 길수록 실제로 반영되는 항목은 줄어듭니다.

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

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

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

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

공식 문서는 CLAUDE.md를 강제 설정이 아니라 참고 자료로 규정합니다. 실제로 동작을 막는 것은 훅과 권한 설정입니다.

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

벽에 "이 문은 열지 마시오"라고 써 붙이는 것과 문에 잠금장치를 다는 것은 다릅니다. 안내문은 읽는 사람의 판단에 맡기고, 잠금장치는 판단과 상관없이 막습니다. 정리하면 CLAUDE.md는 안내문이고, 훅과 권한 설정은 잠금장치입니다.

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

하려는 것	두는 곳
특정 도구, 명령, 경로를 차단	설정 파일의 `permissions.deny`
매 커밋 전처럼 정해진 시점에 반드시 실행	훅
코드 스타일과 품질 기준	CLAUDE.md
프로젝트 구조와 작업 흐름 안내	CLAUDE.md

기준은 간단합니다. 어겼을 때 곤란한 정도가 크면 잠금장치로, 알려 두면 충분한 것은 안내문으로 보냅니다.

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

200줄을 지키라는 말은 규칙을 줄이라는 뜻이 아니라 옮기라는 뜻에 가깝습니다. 옮길 곳은 세 군데이고 성격이 서로 다릅니다.

경로 규칙(.claude/rules/): 파일 종류나 폴더에 묶어 두는 지시입니다. paths 항목에 패턴을 적으면 클로드가 그 파일을 읽을 때만 규칙이 따라 들어옵니다.
스킬(skills): 절차를 담습니다. 부를 때만 본문이 읽히므로 길게 써도 평소 컨텍스트를 차지하지 않습니다.
훅(hooks): 앞 절에서 다룬 잠금장치입니다. 반드시 실행되어야 하는 검사를 넣습니다.

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

스킬 문서의 설명이 이 차이를 잘 보여 줍니다. CLAUDE.md 내용과 달리 스킬 본문은 쓸 때만 읽히므로, 긴 참고 자료를 넣어 두어도 필요해지기 전까지는 비용이 거의 들지 않는다는 내용입니다.

스킬 본문은 부를 때만 읽힙니다. 매번 필요하지 않은 절차를 CLAUDE.md에서 스킬로 옮기면 실제로 컨텍스트가 줄어듭니다.

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

모델 선택에서 실제로 달라진 것

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

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

2026년 8월 28일 기준 공식 가격표는 다음과 같습니다.

모델	입력 100만 토큰	출력 100만 토큰
클로드 오퍼스 5	5달러	25달러
클로드 소네트 5	2달러	10달러
클로드 하이쿠 4.5	1달러	5달러

같은 화면 아래쪽에 가격 비교를 흔들 수 있는 안내가 하나 더 있습니다. 클로드 4.7 이후 모델은 새 토크나이저를 쓰는데, 같은 글을 넣어도 토큰이 약 30% 더 나온다는 설명입니다. 토큰당 단가만 비교하면 실제 청구액과 어긋날 수 있다는 뜻입니다.

측정한 뒤 고른다는 원칙에 대해서도 공식 문서가 한 단계 더 들어간 안내를 두고 있습니다. 최근 오퍼스와 소네트 모델이 지원하는 effort, 즉 사고량 항목을 조절하면 같은 모델 안에서 지능과 비용을 맞바꿀 수 있고, 모델을 바꾸는 것보다 이쪽이 더 나은 조절 수단인 경우가 많다는 내용입니다. 모델을 갈아 끼우기 전에 확인해 볼 만한 값입니다.

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

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

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

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

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

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

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

빠르게 만드는 것까지는 잘 되는데 데이터 설계와 보안에서 막힌다는 이야기도 자주 들립니다. 이 가운데 API 키 문제는 공개된 조사 자료가 있습니다.

깃가디언이 2026년 3월 발표한 조사에 따르면 2025년 한 해 공개 깃허브 커밋에서 발견된 하드코딩 비밀 정보는 2865만 건으로 전년 대비 34% 늘었습니다. 같은 조사에서 AI가 개입한 커밋의 비밀 정보 유출 비율은 3.2%로, 전체 평균인 1.5%의 두 배가량이었습니다.

이런 조사 수치는 공식 문서가 아니라 보안 업체의 집계라는 점을 감안해 읽는 편이 좋습니다. 다만 방향은 분명해 보입니다. 코드를 만드는 속도가 빨라진 만큼 키가 코드에 섞여 들어갈 기회도 늘어난다는 이야기입니다.

앞 절의 구분이 여기에도 그대로 적용됩니다. 키를 코드에 넣지 말라고 CLAUDE.md에 적어 두는 것은 안내문이고, 커밋 전에 검사를 돌리는 훅을 거는 것은 잠금장치입니다. 어느 쪽이 필요한지는 키가 한 번 새어 나갔을 때 감당할 수 있는지로 정하면 됩니다.

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

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

길이가 부담스러우면 두 가지를 먼저 해 볼 수 있습니다. 특정 파일에서만 쓰이는 지시는 경로 규칙으로 옮기고, 여러 단계를 거치는 절차는 스킬로 내립니다. 클로드 코드 2.1.206 이후 버전에서는 /doctor 점검이 프로젝트에 커밋된 CLAUDE.md의 정리안을 제안합니다. 코드에서 알아낼 수 있는 폴더 구조나 의존성 목록을 덜어 내고, 도구 기본값과 다른 규칙이나 주의점은 남기는 방식입니다.

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

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

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

3줄 요약

CLAUDE.md는 클로드 코드가 세션마다 읽는 지시 파일이고, 공식 문서가 권하는 길이는 300줄이 아니라 200줄 미만입니다. 길이 제한이 아니라 지시 준수율에 관한 권고입니다.
공식 문서는 CLAUDE.md를 강제 설정이 아니라 참고 자료로 규정합니다. 어떤 동작을 확실히 막으려면 PreToolUse 훅이나 권한 설정을 씁니다.
소네트 5의 9월 1일 가격 인상은 취소되어 100만 토큰당 2달러와 10달러가 표준가가 되었고, 공식 문서는 모델을 바꾸기 전에 effort 조절을 권합니다.