CLAUDE.md에 공들여 지침을 써 두었는데도 Claude Code가 계속 무시하고 즉흥적으로 움직인다면, 원인은 대개 문구가 아닙니다. 지침이 어디에 놓여 있는지, 그리고 그 파일이 실제로 로드되는지가 문제입니다.
CLAUDE.md만으로 충분할까? 2026년 중반 Claude Code 지침 우선순위
아닙니다. CLAUDE.md만으로는 충분하지 않습니다. 세션마다 처음 200줄 또는 25KB까지만 로드되며, 그 한계를 넘는 내용은 아무리 신중하게 작성했더라도 조용히 버려집니다 . Anthropic의 메모리 문서도 파일을 200줄 미만으로 유지하라고 권장합니다. 파일이 비대해지면 Claude가 실제 지침을 무시하게 되기 때문입니다 .
빠른 답: CLAUDE.md는 항상 켜져 있어야 하는 프로젝트 컨텍스트 전용입니다. 세션마다 처음 200줄 또는 25KB만 로드되며, 추가 규칙은 조용히 버려집니다. 2026년 중반에는 다섯 가지 기본 요소(Rules, Skills, Subagents, Hooks, Output Styles)가 추가되어, 범위별 지침을 한 파일에 계속 쌓는 대신 필요할 때만 로드할 수 있습니다.
Steering Claude Code 블로그(2026년 6월 18일)는 CLAUDE.md와 함께 다섯 가지 지침 기본 요소를 추가합니다. 일치하는 파일을 건드릴 때만 로드되는 .claude/rules/의 경로 범위 Rules, 온디맨드 Skills(SKILL.md), .claude/agents/의 격리된 Subagents, 결정론적 Hooks, 그리고 시스템 프롬프트 Output Styles입니다 . 이들을 관통하는 핵심은 이렇습니다. 거의 모든 개선은 결국 컨텍스트 관리의 문제입니다. 창은 빠르게 차고, 가득 찰수록 신뢰도는 떨어집니다.
여러 출처가 충돌할 때 우선순위는 높은 순서에서 낮은 순서로 다음과 같습니다.
| 우선순위 | 출처 | 범위 |
|---|---|---|
| 1 (최고) | 조직 관리 설정 | 플랫폼/엔터프라이즈에서 강제 |
| 2 | ~/.claude/CLAUDE.md | 전역, 모든 프로젝트 |
| 3 | ./CLAUDE.md | 프로젝트, 커밋됨 |
| 4 | ./CLAUDE.local.md | 로컬, gitignore 처리 |
| 5 | 상위/하위 디렉터리 | 모노레포, 디렉터리 범위 |
CLAUDE.md에는 항상 필요한 컨텍스트만 남기고, 범위가 정해진 지침은 경로 범위 Rules나 Skills로 옮기세요. 그러면 파일을 키우지 않고도 필요할 때만 로드할 수 있습니다 .
CLAUDE.md를 줄이고 Subagent로 나누기
CLAUDE.md 정리는 /init에서 시작합니다. 이 명령은 감지된 빌드 시스템, 테스트 프레임워크, 코드 관례를 바탕으로 시작 파일을 자동 생성합니다. 그런 다음 직접 가지치기해 200줄 미만으로 줄입니다 . 이 제한은 겉치레가 아닙니다. Anthropic의 메모리 문서는 파일이 비대해지면 Claude가 실제 지침을 무시하며, 세션마다 처음 200줄 또는 25KB만 로드된다고 명시합니다 . 그 아래 내용은 조용히 버려지고, 바로 그때부터 Claude가 즉흥적으로 움직이기 시작합니다.
파일을 가볍게 만든 뒤에는 지침을 세 계층으로 나누고, 같은 지침을 여러 곳에 중복하지 마세요.
./CLAUDE.md— 커밋되며 팀이 공유하는 프로젝트 컨텍스트../CLAUDE.local.md— gitignore 처리되는 개인 선호 설정.~/.claude/CLAUDE.md— 모든 프로젝트에 적용되는 전역 기본값 .
중복은 파일을 다시 비대하게 만드는 조용한 원인입니다. 각 계층이 자기 범위만 책임지게 하세요. 반드시 무시되면 안 되는 지침에는 IMPORTANT 또는 YOU MUST를 앞에 붙이세요. Anthropic 문서도 이런 강조가 표시되지 않은 줄보다 준수율을 측정 가능하게 높인다고 확인합니다 . 실무자들도 가장 중요한 규칙을 앞쪽에 배치하는 같은 습관을 강조합니다(동영상: Dan Martell).
정리의 나머지 절반은 위임입니다. .claude/agents/에 subagent를 정의하고, frontmatter에 name, description, tools, model을 넣습니다 :
---
name: security-audit
description: Reviews changed files for auth and injection risks
tools: Read, Grep, Bash
model: opus
---
You are a security reviewer. Inspect the diff, report findings, and
return only a prioritized summary — do not modify code.작업에 맞춰 모델을 고르세요. 저렴하고 빠른 검토에는 Haiku, 기본값으로는 Sonnet, 복잡한 추론에는 Opus가 적합합니다 . 각 subagent는 자체 격리된 컨텍스트 창에서 실행되므로, 그 작업이 메인 스레드를 비대하게 만들지 않습니다 . 보안 감사, 대규모 코드베이스 읽기, 마이그레이션 계획처럼 파일을 많이 다루는 작업은 그쪽으로 보내고, 결과 요약만 가져오세요. 그러면 메인 대화는 다음 결정을 위해 가볍게 유지됩니다 .
Claude Code 집중 유지하기: /compact, /clear, /rewind
컨텍스트는 공짜 자원이 아니라 예산입니다. 1M 토큰 창에서도 세션이 300~400k 토큰을 넘기면 신뢰성이 떨어지기 때문에, Anthropic은 숙련 사용자에게 명령 준수 능력을 유지하려면 사용량을 대략 30% 아래로, 초보자는 약 40% 아래로 유지하라고 권합니다 . 실제로 쓸 수 있는 레버는 많지 않습니다. /clear, /compact, Esc 두 번, /btw 정도입니다. 의식적으로 사용하면 모델이 오래된 가정 위에서 맴돌지 않고 현재 작업에 집중하게 할 수 있습니다.
서로 관련 없는 작업 사이에서는 /clear를 쓰세요. 버그 수정에서 문서 정리로 넘어갈 때 이전 대화 맥락까지 끌고 갈 필요는 없습니다. 이어지는 맥락은 필요하지만 부피를 줄이고 싶다면 /compact <instructions>가 사용자가 명시한 것만, 예를 들어 변경된 파일, 테스트 명령, 현재 목표를 보존하고 나머지는 버립니다 . 중요한 내용을 직접 적으세요. 아무 지시 없이 /compact만 입력하면 요약기가 무엇을 남길지 대신 결정합니다.
"검증, 컨텍스트, 도구 접근 권한을 관리해야 할 희소한 예산으로 다루라," — Claude Code 조율에 관한 Anthropic engineering의 설명 (source: Steering Claude Code, 2026-06).
복구가 필요할 때는 Esc로 실행을 중단하고, Esc를 두 번 누르거나 /rewind를 사용하면 코드와 대화의 마지막 체크포인트로 되돌릴 수 있습니다. 여러 파일에 걸친 잘못된 수정을 되감기에 유용합니다 . 이 체크포인트는 Claude가 만든 변경만 추적합니다. git을 대체하는 기능이 아니므로 정말 중요한 내용은 커밋해 두세요. 기록에 남기지 않을 곁가지 질문에는 /btw를 쓰세요. 그렇지 않으면 컨텍스트 예산을 잡아먹을 비공개 확인 질문에 적합합니다 .
한 가지 규칙만 지켜도 반복 실패를 피할 수 있습니다. 같은 문제에서 수정이 두 번 연속 실패하면 /clear를 실행하고 처음부터 다시 설명하세요. 그 시점의 모델은 잘못된 가정에 고정된 채 반복하고 있을 가능성이 높으며, 세 번째로 밀어붙이는 것보다 새 컨텍스트가 낫습니다 .
엔지니어가 자주 놓치는 Claude Code 함정
2026년 중반 Claude Code 실패 사례 대부분은 프롬프트가 나빠서가 아니라 버전과 환경에 따라 달라지는 몇 가지 함정에서 비롯됩니다. Homebrew의 claude-code 포뮬러는 안정 채널입니다. 대략 1주일 정도 늦게 반영되며, 큰 회귀가 있는 릴리스는 의도적으로 건너뜁니다 . 이 안전장치에는 비용이 있습니다. 최근 포인트 릴리스에 포함된 플래그나 번들 슬래시 명령이 필요하다면 대신 claude-code@latest를 설치하세요.
통합 기능과 권한도 주의해야 합니다. v2.1.187부터 MCP 도구는 5분 동안 출력이 없으면 중단되므로, 오래 실행되는 작업은 출력을 스트리밍하거나 하트비트를 보내도록 설계하고, 큰 페이로드를 자주 반환하는 도구에는 MAX_MCP_OUTPUT_TOKENS를 설정하세요 . --dangerously-skip-permissions 플래그, 즉 --permission-mode bypassPermissions 별칭은 전체 파일시스템 접근 권한을 부여합니다. 이미 격리된 CI 샌드박스 안에서만 안전하며, 프로덕션 머신에서는 절대 사용하지 마세요 .
마지막으로, 헤드라인의 컨텍스트 숫자는 중요한 사실을 빠뜨립니다. 1M 토큰 창이 1M 토큰을 안정적으로 사용할 수 있다는 뜻은 아닙니다. 300~400k를 넘기면 1M 모델에서도 추론 품질과 명령 준수 능력이 눈에 띄게 떨어지므로, 컨텍스트를 한도가 아니라 예산으로 다뤄야 합니다 . 또한 changelog가 매우 활발하게 바뀌고 있으며, v2.1.195는 2026년 6월 26일에 출시되었습니다 . 따라서 CI에 연결하기 전에 플래그 이름과 번들 skill 이름을 실시간 문서에서 확인하세요. 핵심은 명확합니다. 버전을 고정하고, 우회 권한을 쓰기 전에 격리하고, 스크립트로 만들기 전에 changelog를 다시 읽으세요.
자주 묻는 질문
CLAUDE.md와 .claude/rules/의 경로별 Rules는 무엇이 다른가요?
CLAUDE.md는 모든 세션에서 로드되는 상시 컨텍스트입니다. 다만 세션마다 처음 200줄 또는 25KB까지만 읽습니다 . 그래서 파일이 비대해지면 실제 지침이 잘려 나갈 수 있습니다. .claude/rules/의 경로별 Rules는 Claude가 해당 경로 패턴과 일치하는 파일을 다룰 때만 로드됩니다 . 언어나 디렉터리에 한정된 지침, 예를 들어 Python 스타일 규칙이나 migrations 폴더 관례처럼 관련 있을 때만 보여야 하는 내용은 Rules에 두고, CLAUDE.md에는 정말 모든 곳에 적용되는 내용만 간결하게 남기세요.
CI에서 Claude Code를 헤드리스로 실행하려면 어떻게 하나요?
스크립트, CI, 배치 작업에는 헤드리스 플래그인 claude -p를 사용합니다 . 다른 프로그램이 출력을 파싱한다면 --output-format json 또는 stream-json --verbose를 추가하고, --max-turns와 --max-budget-usd로 실행 범위를 제한하세요 .
claude -p "fix failing tests in src/auth" \
--output-format json \
--allowedTools "Read,Edit,Bash(npm test)" \
--permission-mode acceptEdits \
--max-turns 20 \
--max-budget-usd 2.00--allowedTools로 권한 범위를 좁게 잡고, 이미 격리된 샌드박스 안에서는 --permission-mode acceptEdits를 선호하세요. bypassPermissions(--dangerously-skip-permissions와 동일)는 이미 격리된 환경에서만 사용하고, 공유 러너에서는 절대 사용하지 마세요 .
Claude Code에 바로 요청하지 않고 subagent를 만들어야 할 때는 언제인가요?
대량의 코드나 데이터를 읽어야 하지만 그 과정이 메인 스레드를 오염시키지 않았으면 할 때 subagent를 만드세요. Subagent는 격리된 컨텍스트 창에서 실행되고 결과만 돌려줍니다 . 그래서 기본 세션을 가볍게 유지할 수 있습니다. 보안 감사, 마이그레이션 계획, 큰 코드베이스 검색처럼 답을 얻고 나면 중간 파일 읽기 과정이 잡음이 되는 작업에 잘 맞습니다. 이름, 설명, 도구, 모델을 frontmatter로 지정해 .claude/agents/에 정의하세요 . 파일 하나를 빠르게 수정하는 정도라면 Claude에게 바로 요청하면 됩니다.
Claude Code는 어떤 MCP 전송 방식을 지원하나요?
Claude Code는 HTTP, deprecated 상태인 SSE, stdio, WebSocket 전송 방식을 지원합니다 . 연결은 최대 5회까지 지수 백오프로 자동 재연결되며, v2.1.187 기준으로 원격 도구가 5분 동안 응답하지 않으면 중단됩니다 . 도구가 10,000개가 넘는 출력 토큰을 반환하면 Claude가 경고합니다. 이 한도에 자주 걸리는 장황한 서버라면 MAX_MCP_OUTPUT_TOKENS 환경 변수로 상한을 높이세요 .
Claude Code는 월 $20짜리 Claude.ai 구독에 포함되나요?
아니요. Claude Code는 소비자용 Claude.ai 플랜과 별개의 agentic coding 제품이며, 자체 가격 체계를 갖고 있습니다 . 공식 가격표 기준 Sonnet 4.6은 입력/출력 토큰 100만 개당 $3/$15, Opus 4.8은 $5/$25이며, 프롬프트 캐시 히트는 기본 입력 비용의 0.1배로 청구됩니다 . Opus 4.8/4.7/4.6과 Sonnet 4.6은 모두 표준 가격으로 100만 토큰 컨텍스트 창을 포함합니다. 다만 300~400k 토큰을 넘으면 컨텍스트가 흐려지는 문제가 생기므로 사용량은 여전히 가볍게 유지하는 편이 좋습니다 .
