비대한 CLAUDE.md는 Claude가 당신을 무시하게 만든다

Claude Code를 강하게 밀어붙여 쓰는 사람이라면, 이틀 연속 나온 두 번의 변경 로그가 기준선을 다시 잡아 줍니다. 그중 가장 큰 변화는 조용하지만 중요합니다. 이제 컨텍스트를 얼마나 자주 챙겨야 하는지 자체가 달라졌습니다.

Sonnet 5, Chrome 정식 출시, 알림 훅: 시작 전에 따라잡을 것들

워크플로를 최적화하려면 현재 빌드부터 기준으로 삼으세요. Claude Code 2.1.197(2026년 6월 30일)은 Claude Sonnet 5를 기본 모델로 바꾸고, 네이티브 100만 토큰 컨텍스트 창과 2026년 8월 31일까지 적용되는 백만 토큰당 $2/$10 프로모션 가격을 도입했습니다 . 이 더 큰 상한은 계산법을 바꿉니다. 성능이 떨어지기 전까지 세션 안에 더 많은 것을 담을 수 있습니다. 다만 disciplined context management가 사라지는 것은 아닙니다. 기준선이 높아졌을 뿐입니다.

다음 날 나온 2.1.198(2026년 7월 1일)은 Claude in Chrome을 격리된 Anthropic 클라우드 VM에서 정식 제공하기 시작했습니다. 로컬 설치 없이 사용할 수 있으며, 백그라운드 에이전트는 worktree에서 작업한 뒤 commit, push, draft PR 생성까지 하도록 바뀌었습니다 . 또한 무인 세션을 돌린다면 연결해 둘 만한 백그라운드 에이전트 알림 훅 이벤트 두 가지, agent_needs_input과 agent_completed가 추가됐고, 번들 /dataviz skill도 들어갔습니다 .

버전 관리는 중요합니다. Homebrew stable cask는 최신 버전보다 대략 일주일 정도 늦고, npm과 네이티브 설치 프로그램은 자동 업데이트됩니다. 버전에 따라 달라지는 동작을 믿기 전에 claude --version으로 확인하세요 .

먼저 확인할 것들

Claude Code를 오래 굴릴 워크플로에 붙이기 전에 세 가지를 확인하세요. 버전, 컨텍스트 예산, 권한입니다. 몇몇 기능은 특정 버전 이상에서만 동작합니다. /run, /verify, /run-skill-generator는 v2.1.145+가 필요하고, claude mcp login/logout 및 SSH 환경의 --no-browser OAuth는 v2.1.186+가 필요합니다 . claude --version으로 확인하세요. 단, claude --help가 모든 플래그를 보여 주지는 않는다는 점도 기억해야 합니다 .

CLAUDE.md에는 하드 캡이 있습니다. 세션마다 처음 200줄 또는 25KB까지만 로드되고, 그 이후 내용은 조용히 버려집니다 . 믿고 쓰기 전에 점검하세요.

wc -l CLAUDE.md   # line count — must stay under 200
wc -c CLAUDE.md   # byte size — must stay under 25000

CI를 건드리기 전에 headless sanity check를 한 번 실행하세요. OAuth 토큰, 모델 접근 권한, 도구 권한을 한 번의 호출로 검증합니다.

claude -p 'echo ok' --output-format json

마지막으로 권한 단계도 알아 두세요. default → acceptEdits → plan → auto(research preview) → dontAsk → bypassPermissions 순서입니다 . bypassPermissions는 격리된 컨테이너나 VM에서만 쓰세요. 모든 tool-call guard를 비활성화하므로, 실제 credential이 있는 로컬 환경에서는 절대 실행하면 안 됩니다.

효과가 큰 지점: CLAUDE.md 줄이기, Slash Command, Subagent, Hook

가장 효과가 큰 조치는 의외로 단순합니다. CLAUDE.md를 줄이는 것입니다. 파일이 비대하면 Claude가 지시를 무시하게 되고, 계속 무시되는 규칙에 대한 문서화된 해결책은 파일을 정리하거나 그 규칙을 hook으로 바꾸는 것입니다 . 여러 단계 절차는 YAML frontmatter가 있는 .claude/skills/<name>/SKILL.md로 옮기세요. skill 본문은 해당 skill이 호출될 때만 로드되므로, 사용 전까지는 비용이 들지 않습니다. skill과 slash command 이름이 충돌하면 skill이 우선합니다 . 계획할 때 주의할 점도 하나 있습니다. /compact 이후 호출된 skill 본문은 skill당 5,000토큰, 전체 25,000토큰 한도로 다시 주입됩니다 . 그러니 개별 SKILL.md 본문은 짧고 단단하게 유지하세요.

Slash command는 실무적으로 세 가지 이점을 줍니다. 수동으로만 트리거하고 싶은 부작용 있는 skill에는 disable-model-invocation: true를 설정하세요. 예를 들어 /fix-issue 1234 같은 경우입니다. 그러면 모델이 스스로 실행하지 않습니다. /btw <question>를 쓰면 부가 질문을 닫을 수 있는 오버레이에서 답하고, 그 내용은 대화 기록에 들어가지 않아 컨텍스트를 깨끗하게 유지할 수 있습니다. 그리고 /compact에는 custom instructions를 넘겨서 요약이 추측에 기대지 않고 중요한 내용을 보존하게 하세요 .

Subagent는 .claude/agents/<name>.md에 두며, 각각 별도의 컨텍스트 창에서 실행되고 메인 세션에는 요약만 반환합니다 . 강한 모델에는 공격적인 reviewer를 고정하고, 빠른 모델에는 저렴한 classifier를 맡기세요.

---
name: security-reviewer
model: claude-opus-4-5
tools: [Read, Grep]
---
Review the diff for injection, auth, and secret-handling flaws.
Report only findings and severities.

Subagent는 대용량 파일 읽기를 격리하므로, 대량 리서치, 두 개의 fresh context로 나누는 Writer/Reviewer 분리, 또는 메인 세션을 채워 버릴 만한 모든 작업에 잘 맞습니다(video: Simon Scrapes).

.claude/settings.json의 hook은(/hooks로 탐색) 조언이 아니라 결정적 규칙입니다. PreToolUse가 기본 보안 체크포인트이며, exit code가 tool call의 운명을 결정합니다.

Claude Code는 8회 연속 차단되면 hook을 override합니다 . 그러니 불안정하거나 종료가 느린 조건에 gate를 걸지 마세요. 신뢰성 없이 차단하는 hook은 결국 우회됩니다. hook 로직을 넘어서는 강한 격리가 필요하면 /sandbox가 OS 수준의 파일시스템 및 네트워크 제한을 추가합니다 .

알아두어야 할 함정

이 함정들은 대부분 조용히 발생합니다. Claude Code는 한도 때문에 설정이 잘리거나 체크포인트가 부수 효과를 담지 못해도 경고하지 않습니다. 위에서 설명한 자동화에 기대기 전에 다음 다섯 가지 상한과 경계를 기억해 두는 편이 좋습니다 .

• 압축 이후 스킬 토큰 상한. 컨텍스트가 압축되면 다시 주입되는 스킬 본문은 스킬당 5,000토큰, 전체 25,000토큰으로 제한됩니다 . 너무 큰 SKILL.md는 이 상한에 조용히 걸려 뒷부분을 잃습니다. 긴 절차는 하나의 거대한 파일로 두지 말고 더 작은 스킬로 나누세요.
• 체크포인트는 실행 취소이지 버전 관리가 아닙니다. /rewind는 각 변경 전에 파일을 스냅샷으로 저장하지만 Claude의 편집만 추적하며, 시드 스크립트, DB 마이그레이션, 빌드 산출물 같은 외부 프로세스는 추적하지 않습니다 . 파괴적인 자동화를 실행하기 전에는 별도로 git에 커밋해 두세요.
• 훅은 8번 막히면 우회됩니다. 매 턴 실행되는 Stop 훅은 8번 연속으로 차단되면 우회됩니다 . 일반적인 경우에는 빠르게 통과하고, 실제 위반이 있을 때만 막도록 훅을 설계하세요.
• --add-dir는 CLAUDE.md 탐색을 트리거하지 않습니다. 이 플래그는 추가 디렉터리에 대한 파일 읽기/쓰기 접근 권한을 주지만, 해당 경로의 프로젝트 CLAUDE.md를 자동으로 로드하지는 않습니다 . @path/to/CLAUDE.md로 명시적으로 참조하세요.
• 자동 메모리에는 로드 창이 있습니다. 캡처된 빌드 명령과 디버깅 노트는 세션당 처음 200줄 또는 25KB만 로드됩니다 . 오래된 항목이 현재 항목을 밀어내지 않도록 주기적으로 점검하세요.

그다음 단계: 헤드리스 CI, 팬아웃, 적대적 서브에이전트

대화형 설정이 안정되면 다음 레버리지는 무인 확장입니다. 헤드리스 모드는 CI, pre-commit 훅, 배치 작업에서 Claude Code를 비대화형으로 실행합니다. 영향 범위를 명시적으로 제한하고, 내용을 붙여넣기보다 파이프로 컨텍스트를 전달하세요.

cat error.log | claude -p "이 스택 트레이스를 분류해줘" --output-format stream-json --verbose

git diff | claude -p "회귀가 있는지 리뷰해줘"

claude -p "새 API로 마이그레이션해줘" --allowedTools "Edit,Bash(git commit *)"

--allowedTools 허용 목록은 무인 실행의 안전 경계입니다. 에이전트가 여러 파일에 걸쳐 건드릴 수 있는 범위를 제한합니다.

파일별 팬아웃: 대상 파일마다 git worktree를 만들고 각각에서 claude -p를 실행하거나, 로컬 git 오버헤드 없이 실제 프로세스 격리를 위해 격리된 클라우드 VM에서 실행되는 웹 Claude Code로 오프로드하세요. claude agents에서 시작한 백그라운드 에이전트는 Claude Code 2.1.198 기준으로 worktree에서 작업한 뒤 스스로 커밋, 푸시, draft PR 생성을 수행합니다 (July 1, 2026).

적대적 리뷰: model: claude-opus-4-5로 고정한 .claude/agents/security-reviewer.md를 추가하세요. 별도 컨텍스트에서 실행되고 메인 세션의 요약만 받기 때문에, 함께 구현 과정을 지켜보며 생기는 정상화 편향 없이 비판을 제시할 수 있습니다.

Anthropic의 best-practices documentation에 따르면, "서브에이전트는 별도 컨텍스트에서 실행되고 요약만 반환합니다. 큰 파일 읽기를 메인 컨텍스트 밖에 두는 적대적 리뷰에 이상적입니다."

MCP와 플러그인: claude mcp add <name> <server-url>는 Notion, Figma, GitHub, Slack, 데이터베이스를 도구 호출에 연결합니다. SSH 환경에서 OAuth를 사용할 때는 claude mcp login --no-browser를 쓰세요(v2.1.186+) . 플러그인(/plugin)은 스킬, 훅, 서브에이전트, MCP 서버를 하나의 설치 가능한 단위로 묶습니다. 핵심은 이렇습니다. CLAUDE.md를 줄이고, 권한 범위를 제한하고, 반복 가능한 작업을 헤드리스 실행과 새 컨텍스트의 서브에이전트로 밀어 넣으세요. 레버리지는 거기서 누적됩니다.

자주 묻는 질문

/compact는 토큰을 아끼나요, 아니면 컨텍스트만 정리하나요?

둘 다 합니다. 다만 최종적으로 토큰이 반드시 절약된다고 보장되지는 않습니다. /compact는 대화를 요약하고 세부 이력을 버려 컨텍스트 창을 줄입니다. 문제는 압축 이후에도 활성화된 스킬 본문이 다시 주입된다는 점입니다. 이때 스킬당 5,000토큰, 전체 25,000토큰으로 제한됩니다 . 그래서 여러 스킬이 로드되어 있다면 되찾는 공간은 예상보다 작습니다. 요약에 무엇을 남길지 조정하려면 /compact focus on the auth refactor처럼 사용자 지정 지시를 함께 전달하세요.

스킬 대신 서브에이전트는 언제 써야 하나요?

컨텍스트 경계를 기준으로 고르면 됩니다. 스킬은 메인 세션 안에서 실행되고 전체 출력을 반환하므로, 현재 대화 이력을 활용하면 좋은 템플릿형 프롬프트나 도메인 로직에 적합합니다. 서브에이전트는 별도 컨텍스트에서 실행되고 요약만 반환합니다 . 격리가 필요할 때 서브에이전트를 사용하세요. 새로운 관점의 비판적 리뷰, 병렬 작업, 또는 대량 파일 읽기로 메인 컨텍스트가 넘쳐날 수 있는 고용량 리서치에 알맞습니다.

특정 도구 호출을 막는 PreToolUse 훅은 어떻게 연결하나요?

.claude/settings.json의 hooks 아래에 PreToolUse 항목을 추가하세요. 셸 명령은 stdin으로 도구 이름과 인수를 JSON으로 받으며, 종료 코드가 결과를 결정합니다. 2는 호출 차단, 1은 경고 후 허용, 0은 그대로 허용입니다 . 8회 연속 차단 시 우회되는 동작도 주의해야 합니다. Claude Code는 훅이 여덟 번 연속 차단하면 해당 훅을 우회하므로, 반복적으로 실패할 가능성이 있는 간헐적이거나 느린 조건으로 게이트를 걸지 마세요.

Chrome의 Claude Code는 터미널 버전과 같은가요?

기능적으로는 가깝지만 완전히 같지는 않습니다. Chrome은 같은 모델과 도구 기본 요소를 사용하지만, 로컬 설치 없이 격리된 Anthropic 클라우드 VM에서 실행됩니다. 그곳에서 시작한 백그라운드 에이전트는 worktree에서 작업한 뒤 커밋, 푸시, 초안 PR 생성을 수행합니다 . Chrome의 Claude는 2026년 7월 1일 Claude Code 2.1.198에서 정식 출시되었습니다 .

Homebrew의 Claude Code 버전은 왜 뒤처져 있나요?

Homebrew stable cask는 최신 릴리스보다 대략 일주일 늦게 따라가며, 수동 업그레이드가 필요합니다 . 당일 자동 업데이트가 필요하다면 백그라운드에서 업데이트되는 네이티브 직접 설치 프로그램을 사용하세요. 어떤 채널을 쓰든 버전 제한 기능에 의존하기 전에는 claude --version으로 확인하세요. /run과 /verify에는 v2.1.145 이상이 필요하고, claude mcp login에는 v2.1.186 이상이 필요합니다 .