많은 사람이 Claude Code를 길들이는 방법으로 CLAUDE.md 파일에 규칙을 쌓습니다. “수정 후엔 항상 포매터를 돌려라”, “이 명령어는 절대 쓰지 마라” 같은 식으로요. 그런데 Anthropic은 바로 이 방식이 가장 흔한 실수라고 말합니다. 지시문은 대부분의 경우 잘 지켜지지만, 긴 세션이나 모호한 상황에서는 모델이 그 규칙을 그냥 놓칠 수 있기 때문입니다.

Anthropic이 Claude Code의 동작을 제어하는 일곱 가지 방법을 정리한 가이드를 공개했습니다. Rules, Skills, Subagents, Hooks, Output styles, 그리고 시스템 프롬프트 추가 방식까지 — 각각이 컨텍스트를 얼마나 잡아먹고, 얼마나 강하게 지시를 따르게 만드는지를 비교했습니다. 핵심 메시지는 하나입니다. 코딩 에이전트에게 무언가를 “시키는 것”과 “반드시 일어나게 만드는 것”은 전혀 다른 일이라는 점입니다.

출처: Steering Claude Code: skills, hooks, subagents and more – Anthropic

“지시”와 “강제”는 다른 일입니다

이 가이드를 관통하는 구분선은 단순합니다. 어떤 방법은 모델에게 부탁하는 것이고, 어떤 방법은 코드로 강제하는 것입니다.

CLAUDE.md나 Rules, Skills에 적은 내용은 전부 전자에 속합니다. Claude가 읽고 따르려 노력하지만, 판단의 여지가 있습니다. 그래서 Anthropic은 “절대 하면 안 되는 일”을 지시문으로 적는 것을 명확히 잘못된 도구 선택이라고 봅니다. 긴 대화, 애매한 맥락, 혹은 작업 중 읽어 들인 파일에 숨어 있던 악의적 지시(프롬프트 인젝션) 앞에서 프롬프트로 적은 규칙은 깨질 수 있기 때문입니다.

진짜 가드레일은 결정론적이어야 합니다. 모델의 판단이 끼어들 틈 없이 무조건 실행되는 장치여야 한다는 뜻입니다. Claude Code에서 그 역할을 하는 것이 Hooks와 permissions입니다. 예를 들어 PreToolUse 훅은 Claude가 어떤 도구를 호출하기 직전에 그 호출을 가로채 검사하고, 문제가 있으면 종료 코드 2로 차단합니다. 모델이 “포매터를 돌리는 게 좋겠다”고 판단하는 것과, 파일이 수정될 때마다 포매터가 자동으로 돌아가는 것은 근본적으로 다릅니다.

일곱 가지 방법, 두 개의 축

가이드는 각 방법을 두 가지 기준으로 비교합니다. 컨텍스트 비용(토큰을 얼마나 차지하는가)과 지시 권위(얼마나 강하게 따르는가)입니다.

가볍게 정리하면 이렇습니다.

• Rules: .claude/rules/에 두는 마크다운 규칙. paths 필드로 특정 폴더에서 작업할 때만 불러오도록 범위를 지정할 수 있어, 관련 없는 작업 때 토큰을 낭비하지 않습니다.
• Skills: .claude/skills/에 두는 절차 묶음. 세션 시작 때는 이름과 설명만 로드되고, 실제 호출될 때 본문이 불러와집니다. 배포 워크플로나 리뷰 체크리스트처럼 단계가 있는 작업에 적합합니다.
• Subagents: 별도의 격리된 컨텍스트에서 도는 보조 어시스턴트. 로그 분석이나 의존성 감사처럼 중간 결과가 잔뜩 나오지만 나중에 다시 볼 일 없는 곁가지 작업에 씁니다. 결과 메시지만 본 세션으로 돌아옵니다.
• Hooks: 파일 편집, 도구 호출 같은 특정 이벤트에 결정론적으로 반응하는 장치. 컨텍스트 밖에서 코드로 실행되므로 토큰 비용이 낮습니다.
• Output styles: 시스템 프롬프트에 직접 주입되는 스타일 파일. 가장 강한 지시 권위를 갖지만, 잘못 쓰면 Claude Code를 소프트웨어 엔지니어가 아닌 일반 비서로 바꿔버릴 수 있습니다.

Subagent의 격리 방식은 한 번 더 눈여겨볼 만합니다. 서브에이전트 본문의 지시는 본 대화로 아예 들어오지 않고, 자기만의 새 컨텍스트 창에서 돕니다. 그래서 수십에서 수백 개의 백그라운드 에이전트를 띄워도 본 세션의 맥락이 흐트러지지 않습니다.

같은 일도 어디에 적느냐가 다릅니다

가이드에서 가장 실용적인 부분은 “이런 걸 CLAUDE.md에 적고 있다면 다른 곳으로 옮기라”는 신호 목록입니다.

매번 반복돼야 하는 동작(“X 할 때마다 항상 Y”)은 훅으로, 30줄짜리 절차는 스킬로, 특정 디렉터리에만 적용되는 규칙은 paths로 범위를 좁힌 Rule로 옮기라는 식입니다. 개인 취향(“커밋 메시지는 항상 시맨틱하게”)은 프로젝트 파일이 아니라 사용자 단위 파일에 두는 게 맞습니다.

특히 조직 차원의 가드레일을 강제하려면 관리형 설정(managed settings)을 써야 합니다. 관리자가 배포하고 사용자가 로컬 설정으로 덮어쓸 수 없는 유일한 방법이기 때문입니다.

왜 이 구분이 중요한가

이 가이드의 가치는 기능 목록이 아니라 사고방식에 있습니다. AI 에이전트를 다루다 보면 “잘 부탁하면 알아서 하겠지”라는 기대에 기대게 됩니다. 하지만 모델의 협조에 의존하는 통제와, 코드로 보장되는 통제는 신뢰 수준이 다릅니다. 정말 일어나면 안 되는 일이라면, 지시가 아니라 차단 장치가 필요합니다.

설정값을 외우는 것보다 이 구분을 이해하는 쪽이 훨씬 오래갑니다. 각 방법의 정확한 문법과 프론트매터 예시, 컨텍스트 비용을 한눈에 비교한 표는 원문에 자세히 정리돼 있습니다.