Claude Code는 출력이 그럴듯하게 완성된 것처럼 보이는 순간 작업이 끝났다고 말하고 그대로 멈추곤 합니다. 이 기본 동작에 거의 매일 이어진 1년 치 릴리스가 더해지면서, 지금 유용한 워크플로의 대부분은 직접 켜야 하는 기능들 안에 들어가게 됐습니다.
GA 이후 정식 기능이 된 것들: 컨텍스트 압축, 백그라운드 중첩, 팬아웃 서브에이전트
v2.1.147(5월 21일)부터 v2.1.200(2026년 7월 3일)까지 Claude Code는 거의 하루에 한 번꼴로 릴리스되며, 2025년에는 문서화되지 않았던 동작들을 안정적인 플래그가 붙은 이름 있는 1급 기능으로 끌어올렸습니다 . 가장 먼저 받아들여야 할 핵심은 버그가 아니라 문서화된 기본값입니다. 프롬프트에 실행 가능한 검사가 없으면 Claude Code는 출력이 "끝난 것처럼 보일" 때 종료합니다 . 아래 내용은 전부 그 간극을 메우기 위한 것입니다.
세 가지 최근 변경 사항은 세션 설정 방식에 직접적인 영향을 줍니다.
- 이제 되감기는 파일만이 아니라 컨텍스트도 복원합니다. v2.1.191(2026년 6월 24일)부터
/rewind는 파일 변경만 되돌리는 데 그치지 않고,/clear이전의 컨텍스트에서 다시 이어갈 수 있습니다 . - 백그라운드 서브에이전트가 기본값입니다. v2.1.198부터 서브에이전트는 기본적으로 격리된 컨텍스트에서 실행되고 완료 알림을 보내므로, 메인 세션을 깔끔하게 유지할 수 있습니다 .
- 자동 권한 모드가 범위를 통제합니다. v2.1.183에 도입된
--permission-mode auto는 ML 분류기를 사용해 반복적인 승인은 건너뛰되, 범위 확대와 위험한 git/terraform 명령은 차단합니다. 일곱 가지 권한 모드 중 하나입니다 .
표면 기능이 매주 바뀌기 때문에, 특정 플래그는 버전에 묶인 것으로 보고 의존하기 전에 변경 로그를 확인하세요 .
이 방식들을 믿고 쓰기 전에 갖춰야 할 것들
게이트, 체크포인트, 서브에이전트를 본격적으로 쓰기 전에 네 가지를 확인하세요. 요금제, 최신 바이너리, 깨끗한 git 저장소, 가벼운 CLAUDE.md입니다. Claude Code는 Pro에서 연간 결제 기준 월 $17(또는 월간 결제 $20)로 제공되며, Max는 사용량 여유를 5배 또는 20배로 늘려 월 $100부터 시작합니다 . PR을 여는 웹 기반 격리 실행에는 연간 결제 기준 좌석당 월 $100의 Team 프리미엄 좌석이 필요합니다 .
- 바이너리:
claude --version을 실행하세요. Stop hooks와/code-review스킬에는 2.1.152 이상이 필요하고, 자동 권한 모드에는 2.1.183 이상이 필요합니다 . - Git 기록:
/rewind는 Claude가 편집한 파일만 스냅샷으로 잡고 외부 프로세스가 쓴 내용은 잡지 않으므로 git을 대체하지 않습니다. 자율 실행을 시작하기 전에는git status를 실행하세요 . - CLAUDE.md: 파일이 없다면
/init으로 기본 파일을 만들고, 지시 준수 품질이 떨어지기 전에 200줄 미만으로 유지하세요 .
오늘 바로 설정할 네 가지 실천법
한 세션 안에서도 효과가 나는 변화는 네 가지입니다. 검증 게이트, 간결한 CLAUDE.md, 목적이 분명한 압축, 그리고 작업을 분리해 맡기는 서브에이전트입니다. 플러그인이나 마켓플레이스 설치는 필요 없습니다. 이미 가지고 있는 파일과 명령만으로 충분합니다. 이 순서대로 설정하세요. 앞 단계가 다음 단계를 평가하기 어렵게 만드는 잡음을 줄여 주기 때문입니다.
1. 검증 게이트를 추가하세요. Anthropic은 Claude가 실행할 수 있는 확인 절차를 주지 않으면 작업이 "완료된 것처럼 보일" 때 멈춘다고 분명히 말합니다 . 가장 저렴한 게이트는 프롬프트 안에 직접 넣는 방식입니다. 사소하지 않은 모든 프롬프트 끝에 실행 가능한 확인 명령을 붙이세요.
수정 후 실행: pytest -q
작업 완료를 보고하기 전에 프로세스가 0으로 종료되는지 확인하세요.강제로 적용하려면 검사가 통과할 때까지 0이 아닌 값으로 종료하는 Stop hook을 .claude/hooks/에 작성하세요. 다만 이것은 안전장치로 다뤄야지 절대적인 차단 장치로 보면 안 됩니다. Claude는 Stop hook에 8번 연속 막히면 이를 override합니다 .
2. CLAUDE.md를 줄이세요. 지시 준수율이 떨어지기 전에 200줄 이하로 유지하고, 반드시 따라야 하는 규칙 앞에는 "IMPORTANT"나 "YOU MUST"를 붙이세요. Anthropic은 강조 단어가 준수율을 측정 가능하게 높인다고 확인했습니다 . 개인용 override는 gitignore 처리된 CLAUDE.local.md에 두고, 공유 AGENTS.md는 내용을 중복해 컨텍스트를 두 번 쓰지 말고 @path로 가져오세요 .
3. /clear 대신 /compact를 쓰세요. 큰 리팩터링 사이에는 컨텍스트를 지우지 말고 /compact Focus on the API surface changes를 실행해 의도가 남는 요약을 만드세요. CLAUDE.md에는 "always preserve the full list of modified files and test commands" 같은 지시를 넣어 중요한 상태가 자동 요약 뒤에도 살아남게 하세요 . 답변이 대화 기록에 절대 들어가면 안 되는 일회성 질문에는 /btw를 사용하세요 .
| 명령 | 히스토리에 미치는 영향 | 사용할 때 |
|---|---|---|
/clear | 컨텍스트를 완전히 지움 | 관련 없는 작업으로 전환할 때 |
/compact <focus> | 요약하되 핵심 흐름은 유지 | 긴 리팩터링을 계속할 때 |
/btw | 답변이 히스토리에 들어가지 않음 | 일회성 사이드 질문 |
4. 넓은 하위 작업은 서브에이전트로 보내세요. 저렴하고 빠른 읽기 전용 검토를 위해 YAML frontmatter에 model: haiku를 넣은 .claude/agents/reviewer.md를 만드세요. 깊은 분석에는 model: opus로 바꾸면 됩니다. 기본 제공되는 Explore와 Plan 서브에이전트는 기본적으로 Write와 Edit을 거부하므로 어떤 코드베이스에서도 안전합니다 . Anthropic의 설명처럼 서브에이전트는 "run in isolated context with their own tools and model"이므로 메인 스레드를 깨끗하게 유지할 수 있습니다 (source: Claude Code best practices).
이 방식들이 어긋나는 지점
컨텍스트를 깨끗하게 유지해 주는 기능도 무작정 믿으면 조용히 실패할 수 있습니다. 대부분의 예상 밖 상황은 네 가지 실패 모드에서 나오며, 각각에는 구체적인 방어책이 있습니다.
첫째, CLAUDE.md의 @path import는 최대 네 단계까지 재귀적으로 따라가며, 가져온 파일도 줄 수에 비례해 컨텍스트 예산을 씁니다. 500줄짜리 파일을 가져오면 500줄을 직접 넣은 것과 같은 비용이 듭니다 . 깊이 제한 실패는 조용히 일어나므로, import가 해결됐다고 가정하지 말고 시작 후 /context를 실행해 실제로 무엇이 로드됐는지 확인하세요 .
둘째, Stop hook은 강제 차단이 아닙니다. Claude는 hook이 8번 연속 0이 아닌 값으로 종료되면 이를 override합니다 . 반드시 막아야 하는 동작이라면 실행 시점에 --allowedTools allowlist를 함께 사용해, 기능이 단순히 권장되지 않는 수준이 아니라 아예 없는 상태가 되게 하세요.
"Hooks are deterministic guarantees rather than advisory context," — Anthropic, Claude Code best practices (source: Claude Code docs).
셋째, /rewind는 세션 중 Claude가 만든 수정만 되돌립니다. 한 턴 안에서 실행된 npm install, 데이터베이스 마이그레이션, 외부 API 호출은 스냅샷으로 보관되지 않습니다 . 되감은 뒤에는 항상 git diff로 다시 확인하세요.
넷째, /fix-issue 1234처럼 부작용이 있는 SKILL.md 워크플로는 반드시 disable-model-invocation: true를 설정해야 합니다. 이를 빠뜨리면 Claude가 요약 중에도 해당 skill을 자율적으로 실행할 수 있습니다 .
다음 단계: fan-out, CI, 적대적 서브에이전트
단일 세션 루프가 안정되면 바깥으로 확장하세요. fan-out 마이그레이션에서는 각 worktree의 범위를 allowlist와 지출 한도로 제한하고, 중단 후에도 이어갈 수 있도록 세션 이름을 지정하세요.
claude -p "migrate deprecated API calls" \
--allowedTools 'Edit,Read' \
--session my-migration \
--max-budget-usd 2.00CI에서는 pre-commit hook에서 staged diff를 Claude에 넘기고 결과를 파싱하세요. linter나 문서 생성기에서 검증된 구조화 출력을 받아야 한다면 --json-schema를 추가하세요.
claude -p "$(git diff --cached)" \
--output-format stream-json --verbose | jq '.result'적대적 리뷰에는 .claude/agents/critic.md에 model: claude-opus-4와 함께 평가 rubric을 넣어 격리된 컨텍스트에서 실행되게 한 다음, 새로 읽기만 하려면 번들된 /code-review를, 지적 사항을 적용하려면 /code-review --fix를 호출하세요 (v2.1.152–154). 외부 시스템을 연결하려면 claude mcp add와 claude mcp login을 사용하면 CLAUDE.md를 건드리지 않고 연결할 수 있고, /plugin은 skill, hook, subagent, MCP를 하나의 공유 가능한 단위로 묶은 마켓플레이스를 탐색합니다 .
핵심은 이것이 프롬프트 트릭이 아니라는 점입니다. 먼저 컨텍스트, 검증, 범위가 정해진 메모리를 제대로 잡으세요. 그래야 fan-out, CI 게이트, critic 서브에이전트가 불안정한 루프를 증폭하는 대신 효과를 누적합니다.
자주 묻는 질문
Claude Code의 검증 게이트란 무엇이고 왜 중요한가요?
검증 게이트는 테스트 명령, 린터, 빌드 종료 코드, 스크린샷 diff처럼 실행 가능한 확인 절차입니다. Claude Code가 한 턴을 완료로 간주하기 전에 반드시 통과해야 하는 기준입니다. Anthropic 문서에 따르면 Claude는 실행할 수 있는 확인 절차를 주지 않으면 작업이 “끝난 것처럼 보일” 때 멈추기 때문에 중요합니다 . 게이트의 강도는 단계적으로 높아집니다. 프롬프트 안에 직접 넣기 → 별도 평가자가 매 턴 다시 확인하는 /goal 조건 → 스크립트가 0으로 종료될 때까지 턴 종료를 막는 Stop hook → diff를 리뷰하는 적대적 critic 서브에이전트. 신경 쓰는 실패를 안정적으로 잡아내는 범위에서 가장 약한 게이트를 고르세요.
CLAUDE.md는 얼마나 짧아야 하고, 너무 길면 어떻게 되나요?
CLAUDE.md는 200줄 미만으로 유지하세요. 이것이 Anthropic이 명시한 권장 기준입니다 . 자동 메모리는 세션 시작 시 로드되며, 처음 200줄 또는 25KB를 읽습니다 . 이 한도를 넘으면 파일은 강한 지시가 아니라 배경 소음에 가까워지고, 특정 규칙 준수율은 조용히 떨어집니다. 오류도 경고도 없습니다. 반드시 항상 실행되어야 하는 규칙이라면 메모리 한 줄이 아니라 hook으로 인코딩하세요. CLAUDE.md는 컨텍스트이지 강제 장치가 아닙니다 .
/clear, /compact, /btw는 어떻게 다른가요?
세 명령은 모두 컨텍스트 창을 관리합니다. 컨텍스트 창은 빠르게 차고, 찰수록 성능이 저하됩니다 . /clear는 대화 기록을 완전히 지웁니다. 컨텍스트를 가장 많이 확보하지만 작업 상태도 모두 잃으므로 서로 관련 없는 작업 사이에서만 쓰는 것이 좋습니다. /compact <focus>는 방향성을 가진 관점으로 요약합니다. 예를 들어 /compact Focus on the API changes처럼 쓰면 지정한 컨텍스트는 보존하고 나머지는 덜어냅니다. /btw는 일회성 곁가지 질문을 할 때 쓰며, 그 답변은 대화 기록에 기록되지 않습니다. 작업 컨텍스트를 오염시키고 싶지 않은 빠른 방향 확인 질문에 적합합니다 .
Claude Code 서브에이전트에 더 저렴하거나 빠른 모델을 쓸 수 있나요?
네. .claude/agents/<name>.md의 YAML frontmatter에 model: haiku를 설정하면 해당 서브에이전트를 더 저렴하고 빠른 모델로 라우팅할 수 있고, 깊은 분석 패스에는 model: opus를 사용할 수 있습니다 . 서브에이전트가 어떤 모델에서 실행되든 메인 대화 컨텍스트는 깔끔하게 유지됩니다. 각 서브에이전트는 자체 도구를 가진 격리된 컨텍스트에서 실행되기 때문입니다. 서브에이전트는 이제 기본적으로 백그라운드에서 실행되고 완료 알림을 보냅니다. 이 기능은 v2.1.198에 포함되었습니다 .
Stop hook은 어떻게 작동하고, 한계는 무엇인가요?
Stop hook은 턴 종료 시 실행되며, 스크립트가 0으로 종료될 때까지 완료를 막습니다. 그래서 검증 확인을 조언성 컨텍스트가 아니라 결정적인 보장에 가깝게 바꿉니다 . 핵심 한계는 Claude가 8번 연속으로 0이 아닌 종료 코드를 받으면 hook을 우회한다는 점입니다 . 따라서 hook은 단단한 벽이 아니라 가드레일에 가깝습니다. 더 엄격히 강제하려면 --allowedTools 허용 목록과 함께 쓰세요. 최근 릴리스에서는 hook을 걸 수 있는 라이프사이클이 SessionStart, MessageDisplay, post-session 이벤트까지 확장되었습니다 .
