실행 가능한 체크가 없다면? 당신이 Claude Code의 검증 루프가 된다

Claude Code로 실제 배포 가능한 결과를 가장 빠르게 만드는 방법은 더 영리한 프롬프트가 아니라, 일이 정말 끝났는지 판단할 검사를 먼저 이름 붙이는 것이다. 2026년 Anthropic은 이 원칙을 가장 높은 우선순위에 두며, 나머지는 모두 여기서 이어진다.

2026년 Claude Code와 일할 때 Anthropic이 가장 강조하는 것

Anthropic이 Claude Code 모범 사례 순위에서 검증을 맨 위에 둔 이유는 실행 가능한 검사가 없으면 “끝난 것처럼 보인다”는 신호만 남고, 결국 사람이 검증 루프가 되기 때문이다 . 공식 가이드는 이렇게 설명한다.

"Claude stops when the work looks done. Without a check it can run, 'looks done' is the only signal available, and you become the verification loop." — Anthropic, Claude Code best practices (source: code.claude.com/docs)

2026년 7월의 기본 기능들은 이 검사를 추상적 바람이 아니라 구체적인 장치로 만든다. Stop hook은 스크립트가 통과하기 전까지 턴이 끝나지 못하게 막고, 8회 연속 차단 시 안전장치로 우회할 수 있다. /goal 조건은 매 턴 뒤 별도 평가자가 다시 확인한다. 자동 권한 모드는 일상적이고 되돌릴 수 있는 명령은 통과시키면서 파괴적인 명령은 그대로 제한한다 .

Anthropic의 2026년 6월 18일 조정 관련 글은 시야를 더 넓혀, CLAUDE.md 파일, rules, skills, subagents, hooks, output styles, system-prompt append라는 일곱 가지 지시 메커니즘을 구분한다. 각각 지속성과 강제력은 다르며, hooks는 결정적으로 실행되는 반면 CLAUDE.md는 조언에 가깝다 . 핵심 흐름은 사람의 역할 변화다. 매 키 입력을 지켜보는 대신, 종료 조건, 계획 게이트, CLAUDE.md 위생 같은 레일을 깔고 에이전트가 달리게 하는 쪽으로 이동한다.

Claude Code 상호작용 원칙을 실제로 적용하는 법

이 순위를 적용한다는 것은 각 원칙을 실제 키 입력, 명령, 설정 항목으로 바꾸는 일이다. 검증에서 시작하고, 그다음 계획 게이트, 앞단에서 충분히 채운 프롬프트, 컨텍스트 위생 순서로 간다. Anthropic의 모범 사례 가이드가 가중치를 두는 순서와 같다 . 아래 표는 각 원칙을 어떤 메커니즘으로 강제할지 연결하고, 이어지는 문단은 그대로 복사해 적용할 수 있는 경로를 설명한다.

원칙 1 — 검증. 모든 코딩 요청에는 실행할 검사와 허용 가능한 출력을 명시해야 한다. 표준 템플릿은 "write the failing test, implement, run the focused test, then run typecheck."이다. 사람이 지켜보지 않아도 이를 강제하려면 .claude/settings.json에 Stop hook을 연결해, 스크립트가 통과하기 전까지 턴이 완료되지 않게 막는다. Claude Code는 8회 연속 차단된 뒤에만 hook을 우회한다 . hooks는 결정적으로 실행되고 CLAUDE.md는 조언에 가깝기 때문에, 검사가 실제로 실행되도록 보장하는 것은 문서화된 지시가 아니라 hook이다 .

원칙 2 — 계획 모드. Shift+Tab을 눌러 계획 모드에 들어간 뒤, Ctrl+G로 에디터에서 계획을 열어 Claude가 진행하기 전에 검토한다. 구현 단계에서는 계획 모드에서 나와 그 계획에 맞춰 구현하고 검증한다 . 좋은 계획은 파일, 인터페이스, 엣지 케이스, 테스트, 롤백 위험을 명시한다. 오타 수정, 로그 한 줄, 단일 파일 이름 변경처럼 한 문장으로 설명되는 diff라면 건너뛰어도 된다. Anthropic은 계획 모드의 비용이 작지 않다고 분명히 말한다. "If you could describe the diff in one sentence, skip the plan" .

원칙 3 — 첫 턴을 충분히 채운 프롬프트. 의도, 제약, 수락 기준은 첫 턴에 넣는다. 여러 턴에 걸쳐 모호함을 조금씩 줄이는 방식은 토큰을 더 쓰고 때로는 품질도 떨어뜨린다 . 목표, 범위, 하지 않을 일, @를 통한 파일 위치, 완료 기준, 검증 명령을 포함한다. 더 큰 작업이라면 AskUserQuestion의 “Claude가 나를 인터뷰하게 하기” 패턴으로 독립적인 SPEC.md를 만든 다음, 그 문서에서 새 구현 세션을 시작한다 .

원칙 4 — 컨텍스트 위생. 서로 관련 없는 작업 사이에는 /clear를 실행하고, 중요한 내용은 남기면서 나머지를 덜어내려면 /compact "Focus on the API changes"를 사용한다. 같은 내용을 계속 고치게 되는 상황의 해결책은 이렇다. 두 번 수정에 실패했다면 쇠퇴한 스레드를 계속 덧대기보다 /clear를 실행하고 더 나은 초기 요청을 다시 작성한다. 기록을 오염시키면 안 되는 곁가지 질문에는 /btw를 쓴다 . 이런 습관은 누적 효과가 있다. 2026년 7월 changelog에서는 버전 2.1.212에 세션당 WebSearch 호출 200회, subagent 생성 200회 제한까지 추가했다 . 컨텍스트와 도구 예산이 지켜야 할 유한한 자원이라는 사실을 상기시킨다.

관리 없이 실행한 Claude Code가 멈추는 이유: CLAUDE.md 비대화와 상호작용 품질 저하

관리 없이 돌린 실행은 두 가지 구조적 이유로 멈추며, 둘 다 컨텍스트 문제다. 첫 번째는 비대해진 CLAUDE.md다. Anthropic은 이 실패 양상을 분명히 말한다.

"Bloated CLAUDE.md files cause Claude to ignore your actual instructions." — Anthropic, Claude Code best practices (source: code.claude.com/docs)

루트 CLAUDE.md는 모든 세션에서 전체 컨텍스트 비용을 들여 로드되므로, 2026년 6월 18일 스티어링 글은 200줄 미만이라는 엄격한 기준을 둔다. 경로별 제약은 rules 파일로, 여러 단계 절차는 skills로 옮겨 항상 로드되는 파일을 가볍게 유지하라.

두 번째 정체 원인은 상호작용 품질 저하다. Anthropic이 명시적으로 말하는 “kitchen-sink session”처럼 관련 없는 작업을 한 스레드에 섞으면 창이 채워질수록 성능이 떨어지며, 해결책은 관련 없는 작업 사이에 /clear를 쓰는 것이다. 수정에도 같은 원리가 적용된다. 패치를 두 번 실패했다면 품질이 떨어진 대화를 계속 고치려 하지 말라. 모든 수정은 컨텍스트 부채를 더하므로 /clear를 실행하고 더 나은 최초 요청을 처음부터 작성하라.

더 근본적인 차이는 권고와 결정성이다. CLAUDE.md는 권고형이다. Claude가 읽고 판단을 적용한다. 반면 .claude/settings.json에 설정한 Stop hook은 결정적이다. hook 스크립트가 통과하기 전까지 Claude는 턴을 끝낼 수 없다. 매번 반드시 일어나야 하는 일이라면 CLAUDE.md는 조언만 하고, hooks가 보장한다.

숙련 다음 단계: subagents와 CI에서의 Claude Code

검증, 계획, 프롬프팅, 컨텍스트 위생, 권한 관리가 습관이 되면 다음 층은 subagents와 비대화형 실행이다. subagent는 독립된 컨텍스트 창에서 실행되고 요약과 메타데이터만 반환하므로, 깊은 검색, 의존성 감사, 보안 리뷰, 적대적 diff 리뷰를 메인 스레드를 오염시키지 않고 수행할 수 있다 [1]. 내장 /code-review skill은 이를 직접 활용한다. 방금 자신이 작성한 코드에 편향되지 않은 새 subagent가 현재 diff를 리뷰한다 [1].

2026년 7월에는 가드레일도 생겼다. 버전 2.1.212는 세션당 기본 하드 캡으로 subagent 생성 200회와 WebSearch 호출 200회를 추가했다 [8]. 이는 관리 없는 백그라운드 시나리오에서 토큰 사용이 폭주하는 일을 막는다. 수평 확장에서는 claude -p가 CI 파이프라인과 pre-commit hooks를 비대화형으로 구동하고, /batch는 격리된 git checkout의 여러 worktree agent로 마이그레이션을 분산한다 [1][3].

한 가지 주의할 점이 있다. 빈틈을 찾으라고 요청받은 리뷰어는 언제나 무언가를 찾아내고, 이는 과잉 엔지니어링으로 이어진다. 범위를 제한하라. subagent에게 “정확성이나 명시된 요구사항에 영향을 주는 빈틈만 표시하라”고 지시하라 [1]. 일곱 가지 원칙 전체를 관통하는 핵심은 하나다. 실행 가능한 체크, 가벼운 CLAUDE.md, 결정적 hook이라는 레일을 먼저 깔고, agent가 그 위에서 달리게 하라. 사람의 주의력은 타이핑이 아니라 증거 검토에 남겨두면 된다.

자주 묻는 질문

Claude Code에서 실행 가능한 종료 조건이란 무엇인가?

실행 가능한 종료 조건은 Claude가 스스로 실행하고 이진적인 통과 또는 실패로 읽을 수 있는 모든 체크를 뜻한다. 집중된 테스트 스위트, 빌드 종료 코드, linter, fixture diff, UI 작업에서 디자인과 비교하는 스크린샷 비교가 여기에 해당한다 . 핵심은 사람이 출력을 해석할 필요가 없어야 한다는 점이다. Stop hook은 이를 구체화한다. 체크 스크립트가 통과 종료 코드를 반환할 때까지 턴 종료를 막으며, Claude Code는 8번 연속으로 막힌 뒤에만 override한다 .

Claude Code에서 plan mode를 건너뛰어야 할 때는 언제인가?

diff를 한 문장으로 설명할 수 있다면 plan mode를 건너뛰어라. 오타 수정, 로그 한 줄, 단일 파일 이름 변경 같은 경우다. Anthropic은 이를 직접 밝히며, 단순 변경에 plan mode를 쓰면 무시하기 어려운 오버헤드가 생긴다고 경고한다 . Explore → Plan → Implement → Commit 흐름은 여러 파일을 건드리거나 낯선 코드베이스를 다룰 때 남겨두라. 조사와 실행을 분리해야 엉뚱한 문제를 푸는 일을 피할 수 있다.

루트 CLAUDE.md 파일은 얼마나 길어야 하는가?

루트 CLAUDE.md는 200줄 미만으로 유지하라. Anthropic의 2026년 6월 18일 스티어링 가이드는 루트 파일이 매 세션 로드되고 높은 컨텍스트 비용을 지니므로, 비대해지면 Claude가 실제 지시를 무시하기 시작한다고 설명한다 . 경로별 제약은 rules 파일로, 절차는 skills로 옮기고, 쌓아두기보다 과감하게 덜어내라.

CLAUDE.md와 Stop hook의 차이는 무엇인가?

CLAUDE.md는 권고형이다. Claude가 읽고 재량껏 해석하므로, 지침은 다른 컨텍스트와 함께 저울질될 수 있다. .claude/settings.json에 설정한 Stop hook은 결정적이다. hook 스크립트가 통과 종료 코드를 반환할 때까지 Claude는 턴을 끝낼 수 없으므로, 해당 동작이 실행된다는 점을 보장한다 . hook이 계속 실패할 때의 유일한 안전장치는 8회 연속 차단 후 override다 .

Claude Code에서 subagents는 언제 도움이 되고 언제 해가 되는가?

subagents는 격리가 중요할 때 도움이 된다. 깊은 조사, 의존성 및 보안 감사, diff에 대한 적대적 리뷰가 그런 경우다. 이들은 자체 컨텍스트 창에서 실행되고 요약만 반환하므로 메인 스레드를 깨끗하게 유지한다 . 반대로 복잡한 다중 파일 작업에서는 리뷰 오버헤드가 격리의 이점보다 커질 수 있으며, 숙련 사용자들은 이런 경우 과도한 토큰 소모가 발생한다고 보고한다 . 범위를 좁게 잡고, 정확성이나 명시된 요구사항에 영향을 주는 빈틈만 표시하라고 리뷰어에게 지시하라.

이 글이 도움이 되셨다면, 새 글이 올라올 때마다 이메일로 받아보세요.

구독하기