Claude가 따르는 지침. 무시 못 하는 훅.

Claude Code는 사용자의 CLAUDE.md와 세션 중 지시사항을 읽습니다. 하지만 읽는 것과 따르는 것은 다릅니다. 실제로 배포에 쓰는 사람에게 중요한 경계선은 이 도구가 무엇을 제안하는지와 무엇을 강제하는지 사이에 있습니다.

Claude Code가 강제하는 것과 단지 제안하는 것

Claude Code에 지시하는 대부분의 내용은 권고에 가깝습니다. CLAUDE.md와 세션 중 프롬프트는 동작을 유도하지만 보장하지는 않습니다. 실무자들은 100%가 아니라 대략 80% 수준의 준수율을 보고합니다 . 반드시 보장되어야 하는 동작은 지시 문단이 아니라 결정론적 메커니즘에 넣어야 합니다.

실제로 강제하는 계층은 두 가지입니다. Hooks는 생명주기 이벤트에서 실행되는 결정론적 셸 명령, HTTP 엔드포인트, MCP 도구, 또는 LLM 호출입니다. PreToolUse는 무엇이든 실행되기 전에 도구 호출을 평가하고 차단할 수 있고, PostToolUse는 성공 후 실행되며, FileChanged는 비동기로 반응하고, Stop 훅은 테스트가 통과할 때까지 한 턴을 막을 수 있습니다. Claude는 말로 이 장벽을 우회할 수 없습니다 . Permissions는 또 다른 강제 계층입니다. 결과는 deny → ask → allow 순서로 평가되며, CLAUDE.md도 어떤 요청도 이 체인을 덮어쓸 수 없습니다 .

팀에서는 규칙을 어디에 두느냐가 권한을 결정합니다. 설정 우선순위는 managed settings > CLI arguments > local (.claude/settings.local.json) > project > user 순서입니다 . 공유 규칙은 project 범위에, 개인용 오버라이드는 local settings에 두고, bypassPermissions를 조직 전체에서 비활성화하는 것 같은 강제 정책은 managed settings에 넣어야 합니다. 그러면 개인 설정으로 되돌릴 수 없습니다.

Hooks, subagents, skills 연결 방식

연결 원칙은 하나입니다. Claude가 논리로 빠져나갈 수 있는 지시를, 빠져나갈 수 없는 메커니즘으로 바꾸는 것입니다. PreToolUse 훅은 도구 호출 전에 실행되고 0이 아닌 종료 코드로 차단하는 결정론적 게이트입니다. 셸 명령, HTTP 엔드포인트, MCP 도구, 또는 LLM 프롬프트가 될 수 있습니다 . 그 위에 skills, 범위가 제한된 subagents, plan mode, /verify를 얹습니다. 아래는 다섯 가지 확장 지점을 실제로 복사해 따라갈 수 있는 흐름입니다.

Step 1 — PreToolUse 훅으로 위험한 도구 호출을 막습니다. .claude/settings.json에 도구 이름(예: Bash)을 키로 하는 hooks 항목을 추가하고, 거부하려면 0이 아닌 코드로 종료하는 명령을 실행하게 합니다. Anthropic은 rm -rf 차단이나 migration 폴더 쓰기 차단 같은 가드레일에 이 패턴을 권장합니다 .

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command",
            "command": "grep -qE 'rm -rf|/migrations/' && exit 2 || exit 0" }
        ]
      }
    ]
  }
}

훅은 보안에 민감한 코드로 다뤄야 합니다. Claude에게 작성하게 할 수는 있지만 반드시 검토하세요 . Anthropic의 자체 가이드는 이 트레이드오프를 이렇게 표현합니다.

"Use enforced permission rules, not instructions" — Anthropic, Best practices for Claude Code (source: code.claude.com).

Step 2 — 절차를 skills로 옮깁니다. .claude/skills/<name>/SKILL.md를 만들고 /name으로 호출합니다. 매 세션 로드되고 대략 80% 정도만 따라지는 CLAUDE.md와 달리 , skill은 호출될 때만 로드됩니다. 예를 들어 git diff HEAD 출력 같은 동적 컨텍스트를 인라인으로 넣으면, 수동으로 붙여넣지 않아도 모델이 근거를 잡고 시작합니다 .

Step 3 — subagent의 도구 범위를 제한합니다. .claude/agents/<name>.md에 명시적인 allowed_tools 목록과 함께 정의합니다. subagent는 별도의 컨텍스트 창에서 실행되고 요약을 돌려주며, 문서에서는 이를 컨텍스트 비대화를 막는 가장 강력한 도구 중 하나로 설명합니다 . 대규모 마이그레이션에서는 /batch(v2.1.145+)가 작업을 5~30개의 독립 단위로 분해하고, 각 단위를 격리된 git worktree에서 백그라운드 subagent로 실행하며, 테스트를 돌리고 PR을 엽니다 .

Step 4 — 여러 파일을 수정하기 전에 계획합니다. /plan은 Plan subagent로 읽기 전용 탐색을 실행해, 그 출력을 메인 컨텍스트 창 밖에 둡니다. Ctrl+G를 누르면 생성된 계획을 에디터에서 열 수 있습니다 . 한 문장짜리 diff에는 건너뛰고, 익숙하지 않은 여러 파일 변경에는 사용하세요.

Step 5 — /verify로 실제 실행을 확인합니다. 테스트가 0으로 종료되어도 앱은 시작하자마자 크래시할 수 있습니다. /verify(v2.1.145+)는 빌드하고 실행한 뒤, 실행 중인 앱을 관찰해 실제로 시작되고 동작하는지 확인합니다 .

훅, 서브에이전트, 플랜 모드가 빗나가는 지점

정책을 강제하는 바로 그 메커니즘에도 문서화된 우회 지점이 있으며, 이를 단단한 게이트로 믿는 순간 자동화 파이프라인이 깨집니다. Stop 훅은 테스트가 통과할 때까지 한 턴을 막지만, Claude는 8번 연속 차단되면 이를 오버라이드합니다 . 따라서 장시간 무인 실행에서 이것을 벽처럼 취급하면 안 됩니다. 훅에는 명시적인 허용 목록 권한 규칙을 함께 두세요. 이 규칙은 모델 지시나 CLAUDE.md로도 오버라이드할 수 없습니다 .

다음 함정은 권한 모드 선택입니다. bypassPermissions는 rm -rf /와 rm -rf ~처럼 루트와 홈을 제거하는 작업에는 여전히 확인을 요구하지만, .git, .claude, .vscode, .husky, .mvn 같은 민감한 디렉터리에 대해서는 확인을 건너뜁니다 . Anthropic은 이 모드를 컨테이너나 VM 안에서만 쓰라고 권장합니다. .git에 잘못 쓰인 변경이 조용히 통과하는 공유 개발 머신에는 맞지 않습니다.

컨텍스트 손실은 더 조용히 일어납니다. 자동 압축은 컨텍스트가 대략 80%대 초중반까지 찼을 때 실행되며 손실을 동반합니다. 세션 초반에 내린 결정이 도구 호출 사이에서 사라질 수 있습니다 . 무엇을 남길지 지정하려면 /compact <instructions>를 쓰고, 압축 실행 전 체크포인트로 되돌리려면 Esc+Esc(/rewind)를 사용하세요 .

"Claude의 컨텍스트 창은 빠르게 차고, 찰수록 성능이 저하된다." — Anthropic, Claude Code 모범 사례 (source: code.claude.com)

조용한 실패는 두 가지 더 있습니다. 스킬 범위는 enterprise > personal > project > plugin 순서로 해석되므로, 같은 이름의 팀원 프로젝트 스킬을 개인 스킬이 가릴 수 있습니다 . 범위 소유권을 문서화하세요. 그리고 서브에이전트는 전체 기록이 아니라 스스로 작성한 요약을 반환합니다 . 자연어 보고를 믿기보다 테스트, 린트, /verify 같은 검증 가능한 체크를 완료 조건에 연결하세요.

이제 연결해 둘 것들

프로젝트마다 /run-skill-generator를 한 번 실행하는 것부터 시작하세요(v2.1.145+ 필요). 이 명령은 설치 명령, 환경 변수, 실행 스크립트를 기록해 두므로, 이후 /run과 /verify 호출이 다시 묻지 않고 앱을 정확히 시작할 수 있습니다 . 이 한 번의 설정으로, 테스트만 실행하는 것이 아니라 앱을 빌드하고 실행하고 관찰하는 /verify가 신뢰할 수 있는 완료 게이트가 됩니다.

Claude가 이슈, 모니터링, 데이터베이스, Slack 컨텍스트를 반복해서 붙여 넣으라고 요구한다면 claude mcp add로 MCP 서버를 추가하세요. HTTP 전송을 사용하세요(SSE는 HTTP가 있는 곳에서는 더 이상 권장되지 않음). 연결된 서버는 자신의 프롬프트를 /mcp__<server>__<prompt> 형태의 슬래시 명령으로 노출한다는 점도 기억해 두세요 .

세션이 예상보다 빠르게 컨텍스트를 소모한다면 첫 진단 도구는 /usage입니다. Pro, Max, Team, Enterprise 플랜에서 스킬, 서브에이전트, 플러그인, MCP 서버별 소비량을 나누어 보여줍니다 .

가장 효과가 큰 습관은 적대적 diff 점검입니다. diff와 PLAN.md만 받는 새 서브에이전트를 띄우고, 계획 준수 여부를 평가하게 하세요. Claude의 자기 평가는 고립된 읽기에서 드러나는 이탈을 놓칩니다. 손실 있는 자동 압축 이후에는 특히 그렇습니다. 한 번 설정하고, 항상 검증하세요.

자주 묻는 질문

Claude Code 훅과 CLAUDE.md 지시문의 차이는 무엇인가요?

훅은 결정적으로 실행되고, CLAUDE.md 지시문은 참고용 안내에 가깝습니다. 훅은 모델의 판단과 관계없이 셸 명령, HTTP 엔드포인트, MCP 도구로 실행되며, PreToolUse 훅은 도구 호출이 실행되기 전에 이를 차단할 수 있습니다 . 반면 CLAUDE.md는 Claude가 추론 과정에서 넘어갈 수 있는 가이드입니다. 실무자들은 대략 80% 정도만 지켜진다고 보고합니다 . 반드시 일어나면 안 되는 일, 예를 들어 rm -rf를 막거나 마이그레이션 폴더에 쓰기 작업을 차단해야 한다면 CLAUDE.md의 한 문장이 아니라 PreToolUse 훅을 사용하세요.

CLAUDE.md에 절차를 더 쓰는 대신 skill을 써야 하는 때는 언제인가요?

절차에는 skill을 쓰고, CLAUDE.md에는 사실만 남겨두세요. SKILL.md는 /skill-name으로 직접 호출되며 사용할 때만 로드되므로 평소에는 컨텍스트를 전혀 쓰지 않습니다. 반면 CLAUDE.md는 매 세션마다 로드되어 컨텍스트 예산을 차지합니다 . 배포 절차, 마이그레이션 레시피, 코드 리뷰 체크리스트는 .claude/skills/<name>/SKILL.md 아래의 skill로 옮기세요. CLAUDE.md에는 Claude가 모든 작업에서 정말로 알아야 하는 몇 가지 사실만 남기는 편이 좋습니다. Claude의 컨텍스트 창은 빠르게 차고, 찰수록 성능이 떨어지기 때문입니다 .

/verify는 테스트 실행과 무엇이 다른가요?

/verify는 앱을 빌드하고 실행한 뒤 실제로 동작하는 모습을 관찰합니다. 단지 유닛 테스트가 0으로 종료되는지만 보는 것이 아니라, 실제 시작 여부와 기본 런타임 동작을 확인합니다 . 흔한 실패 사례는 테스트는 통과하지만 환경 변수가 빠졌거나 엔트리포인트 설정이 잘못되어 앱이 시작과 동시에 크래시하는 경우입니다. /verify는 이 빈틈을 잡아내므로, /run-skill-generator와 함께 사용해 설치 명령, 환경 변수, 실행 스크립트를 기록하는 흐름과 잘 맞습니다. v2.1.145 이상이 필요합니다 .

자동 압축은 긴 Claude Code 세션에 어떤 영향을 주나요?

자동 압축은 손실이 있으며, 앞서 내린 결정을 조용히 지워버릴 수 있습니다. 컨텍스트 사용량이 대략 80%대 초중반에 이르면 실행되어 대화 기록을 요약하므로, 세션 초반의 아키텍처 결정이나 제약 조건 논의가 예고 없이 사라질 수 있습니다 . 완화 방법은 두 가지입니다. 보존해야 할 내용을 명시해 /compact를 실행하거나, /rewind(Esc+Esc)를 사용해 압축이 실행되기 전 체크포인트로 되돌리는 것입니다 . /context로 창 사용량을 확인하고, 서로 관련 없는 작업 사이에는 /clear를 사용하세요.

서브에이전트는 병렬로 실행할 수 있고, 결과는 어떻게 돌아오나요?

가능합니다. /batch는 작업을 5~30개의 독립 단위로 나누고, 각 단위마다 격리된 git worktree에서 백그라운드 서브에이전트 하나를 띄운 뒤 테스트를 실행하고 각각 PR을 엽니다 . 서브에이전트는 별도의 컨텍스트 창에서 실행되고 압축된 출력만 보고하므로, 결과는 전체 transcript가 아니라 요약 형태로 돌아옵니다 . 요약에는 실패가 빠질 수 있으므로, 병합하기 전에 /batch를 검증 가능한 완료 조건, 즉 테스트 통과나 /verify 성공과 함께 확인하세요.