Claude Code 제어하기: CLAUDE.md 파일, 스킬, 훅, 규칙, 서브에이전트 외

Claude는 여러분의 작업 방식에 맞게 동작하도록 설계되었으며, Claude Code에서는 이를 직접 커스터마이즈할 수 있습니다.

Claude의 동작을 지시하는 방법은 총 7가지입니다: CLAUDE.md 파일, 규칙(rules), 스킬(skills), 서브에이전트(subagents), 훅(hooks), 출력 스타일(output styles), 그리고 시스템 프롬프트 추가(appending the system prompt)입니다.

각 방법은 다음 세 가지를 제어합니다:

• 지시 내용이 컨텍스트에 언제 로드되는가;
• 긴 세션에서도 유지되는가(컴팩션 동작);
• 얼마나 강한 권한을 갖는가.

아래 표는 각 방법의 주요 차이점을 한눈에 정리한 것이며, 본문에서는 각 지시 내용을 어디에 배치할지 판단하는 데 필요한 세부 내용과 의사결정 기준을 설명합니다.

지시 내용을 전달하는 7가지 방법

CLAUDE.md 파일

CLAUDE.md는 프로젝트 루트에 위치하는 마크다운 파일입니다. 세션 시작 시 컨텍스트에 로드되어 세션 내내 유지됩니다.

빌드 명령어, 디렉터리 구조, 모노레포 구성, 코딩 컨벤션, 팀 규범을 기록하기에 가장 적합합니다.

CLAUDE.md 파일은 두 가지 유형이 있으며, 로드 방식도 각각 다릅니다:

• 항상 로드: 첫 번째 유형은 루트 CLAUDE.md 파일로, 공유 저장소에 위치하거나 프로젝트별 개인 설정을 위해 로컬에 저장됩니다. 이 파일들은 모두 세션 시작 시 로드되며, 긴 세션에서도 소실되거나 내용이 희석되지 않습니다. Claude Code가 대화를 컴팩션할 때 이 파일들을 다시 읽습니다.
• 온디맨드: 세션을 초기화한 폴더 하위의 서브디렉터리에 있는 CLAUDE.md 파일입니다. 예를 들어 app/api/CLAUDE.md은 세션 시작 시가 아니라, Claude가 app/api 하위 파일을 읽을 때 로드됩니다. 경로 범위가 지정된 규칙과 동일한 컴팩션 동작을 따르므로, 해당 서브디렉터리에 다시 접근하기 전까지는 유지되지 않습니다.

공유 저장소에서 CLAUDE.md는 소유자 없는 설정 파일이 으레 그렇듯 점점 비대해집니다. 팀마다 자기 지시 내용을 추가하고, 아무것도 삭제되지 않죠. 이 비용은 규모가 커질수록 기하급수적으로 늘어납니다.

저장소에서 작업하는 모든 엔지니어의 모든 세션에 해당 내용 전체가 로드되는데, 현재 태스크와 무관한 내용도 예외가 아닙니다. 이는 토큰을 낭비할 뿐 아니라 실제로 중요한 지시 내용의 준수율도 떨어뜨립니다. 파일이 커질수록, 팀별 컨벤션은 경로 범위가 지정된 규칙으로, 절차적 내용은 스킬로 옮겨 관련 상황에서만 로드되도록 하세요.

팁: CLAUDE.md는 200줄 이하로 유지하고, 담당자를 지정하여 코드를 리뷰하듯 변경 사항을 관리하세요. 이 파일은 코드베이스에 대한 개요를 Claude에게 제공하거나, 필요할 때 더 자세한 정보를 찾을 수 있는 다른 파일들을 가리키는 인덱스로 활용하는 것이 이상적입니다.

모노레포에서는 각 팀의 디렉터리에 서브디렉터리 CLAUDE.md를 별도로 두어 각 팀이 자신의 컨벤션만 로드하도록 하고, 개발자는 claudeMdExcludes 설정으로 담당하지 않는 팀의 파일을 건너뛸 수 있습니다.

보안 정책이나 컴플라이언스 요건처럼 조직 전체 저장소에 일괄 적용되어야 하는 기준은, 중앙에서 관리되는 CLAUDE.md를 MDM이나 설정 관리 도구를 통해 개발자 머신에 배포하는 방식을 사용하세요. 이렇게 배포된 파일은 개인 설정으로 제외할 수 없습니다.

CLAUDE.md 설정에 대한 자세한 내용은 블로그 포스트 CLAUDE.md files: Customizing Claude Code for your codebase에서 확인하세요.

규칙

규칙은 .claude/rules/ 에 위치하는 마크다운 파일로, Claude에게 구체적인 제약 조건이나 컨벤션을 전달합니다.

범위가 지정되지 않은 규칙은 CLAUDE.md와 동일하게 동작합니다. 세션 시작 시 항상 로드되고 컴팩션 시 재주입되므로, 현재 태스크와 무관하더라도 컨텍스트를 차지해 토큰을 낭비할 수 있습니다.

경로 범위가 지정된 규칙은 paths 필드를 추가해 로드 시점을 제어함으로써, 실제로 필요한 때에만 규칙 내용을 로드할 수 있습니다.

예를 들어, src/api/**로 범위가 지정된 규칙은 문서 작업만 진행하는 세션에서는 컨텍스트에 로드되지 않습니다. 해당 src/api/ 디렉터리 내 파일에 Claude가 접근할 때만 로드됩니다.

실제 예시를 보면 다음과 같습니다:

---
paths:
  - "src/api/**"
  - "**/*.handler.ts"
---
All API handlers must validate input with Zod before processing.

팁: "마이그레이션 파일은 추가 전용"처럼 특정 파일에만 적용되는 제약 조건은 규칙의 paths 프론트매터에 두는 것이 가장 적합합니다. 특정 디렉터리 전체가 아니라 코드베이스의 여러 곳에 걸쳐 있는 횡단 관심사(cross-cutting concern)나 파일을 대상으로 할 때는, 중첩된 CLAUDE.md 파일보다 경로 범위가 지정된 규칙을 선택하세요.

스킬

스킬은 .claude/skills/에 폴더 형태로 저장되며, 지시 내용·스크립트·리소스로 구성됩니다. Claude는 이를 동적으로 로드합니다. 각 스킬에는 이름, 설명, 본문이 담긴 SKILL.md 파일이 있습니다.

세션 시작 시에는 이름과 설명만 로드되며, 전체 본문은 Claude가 스킬을 호출할 때 로드됩니다. 호출은 슬래시 명령어(/code-review)를 통하거나, 태스크에 자동으로 매칭되는 방식으로 이루어집니다.

예를 들어, /code-review는 현재 diff를 검토하고 파일을 수정하지 않고 결과를 보고하는 빌트인 스킬입니다. 스킬에 플레이북이 정의되어 있어, 호출할 때마다 Claude가 동일한 구조적 접근 방식을 따릅니다.

컴팩션 시 Claude Code는 호출된 스킬을 전체 공유 예산 한도 내에서 재주입하며, 세션 중 스킬을 많이 호출했다면 가장 오래된 것부터 제거됩니다.

팁: 배포 워크플로우, 릴리스 체크리스트, 리뷰 프로세스처럼 절차적인 지시 내용은 CLAUDE.md 대신 스킬에 두세요.

Claude Code에는 기본 스킬이 내장되어 있지만, 직접 커스텀 스킬을 작성할 수도 있습니다. 만드는 방법은 스킬 빌드 완전 가이드에서 확인하세요.

서브에이전트

서브에이전트는 .claude/agents/ 에 위치하는 마크다운 파일로, 특정 사이드 태스크를 전담하는 독립적인 보조 에이전트를 정의합니다. 각 파일은 YAML 프론트매터(이름, 설명, 그리고 모델 및 도구 접근 권한 등 선택적 필드)와 해당 서브에이전트의 시스템 프롬프트가 되는 본문으로 구성됩니다.

서브에이전트는 스킬과 유사하게 이름, 설명, 도구 목록이 세션 시작 시 로드되지만, 에이전트 본문의 더 큰 컨텍스트는 자동으로 호출되지 않습니다. Claude는 Agent 도구를 통해 서브에이전트를 호출하며, 이때 프롬프트 문자열을 함께 전달합니다.

서브에이전트 본문의 더 큰 지시 컨텍스트는 자동 호출되지 않을 뿐만 아니라, 부모 대화에 아예 진입하지도 않습니다.

서브에이전트는 독립된 새 컨텍스트 창에서 실행되며, 메인 세션으로 반환되는 것은 서브에이전트의 최종 메시지(여러 하위 태스크의 결과를 집약한 것)와 메타데이터뿐입니다.

이 패턴은 확장성이 뛰어납니다. 서브에이전트는 최대 5단계까지 중첩할 수 있으며, 동적 워크플로우를 활용하면 서브에이전트 아키텍처의 세부 사항을 직접 지정하지 않고도 수십~수백 개의 백그라운드 에이전트를 오케스트레이션할 수 있습니다. 오케스트레이션 계획과 중간 결과물은 Claude의 컨텍스트 창이 아니라 스크립트 변수에 저장되므로, 지시 내용의 정확도를 잃지 않고도 대규모 작업을 처리할 수 있습니다.

팁: 격리성이야말로 스킬 대신 서브에이전트를 선택하는 주된 이유입니다. 심층 검색, 로그 분석 패스, 의존성 감사처럼 중간 결과물이 메인 대화를 어지럽히고 나중에 다시 참조할 일도 없는 사이드 태스크에는 서브에이전트를 사용하세요. 각 단계를 직접 확인하고 방향을 조정하고 싶다면, 메인 스레드 안에서 절차가 진행되는 스킬을 사용하세요.

훅

훅은 사용자가 정의하는 명령어, HTTP 엔드포인트, 또는 LLM 프롬프트로, 파일 편집·도구 호출·세션 시작 등 Claude 라이프사이클의 특정 이벤트에 반응해 실행됨으로써 Claude의 동작을 보다 결정론적으로 제어합니다.

훅은 settings.json, 관리형 정책 설정, 또는 스킬/에이전트 프론트매터에 등록합니다.

훅의 유형에는 command, HTTP, mcp_tool, prompt, agent 등 여러 가지가 있습니다. 모든 훅은 결정론적으로 트리거되며, 앞의 세 가지(command, HTTP, mcp_tool)는 결정론적으로 실행됩니다. 반면 prompt와 agent는 고정된 규칙이 아닌 Claude의 판단에 따라 출력을 결정합니다.

훅의 설정이나 지시 내용은 메인 컨텍스트 창 외부에 위치하기 때문에 컨텍스트 비용이 낮습니다. 훅의 종류에 따라 핸들러(command, http, mcp_tool)를 실행하거나, 별도의 창에서 모델 호출(prompt, agent)을 수행합니다.

일부 훅은 출력 결과가 메인 컨텍스트 창에 저장되기도 합니다. 예를 들어, 차단 훅(blocking hook)의 표준 오류(standard error)는 Claude가 호출이 거부된 이유를 알 수 있도록 컨텍스트에 저장됩니다.

하지만 대부분의 훅은 설정에서 명시적으로 반환하도록 지정하지 않는 한 출력이 메인 창에 저장되지 않습니다. 예를 들어 PreCompact 이벤트를 이용해 컴팩션 전에 대화 기록을 다른 파일에 백업했더라도, Claude는 어느 파일에 기록이 저장되었는지 알 수 없습니다.

이 점에서 훅은 CLAUDE.md, 규칙, 스킬과 근본적으로 다릅니다. 자세한 내용은 훅 설정 방법 포스트에서 확인하세요.

팁: 편집 후 린터 실행, 완료 시 Slack 알림 발송, 특정 명령어의 실행 전 차단처럼 반드시 결정론적으로 수행되어야 하는 작업에는 훅을 사용하세요. PreToolUse 훅은 모든 도구 호출을 검사하고, 종료 코드 2를 반환해 해당 호출을 차단할 수 있습니다.

훅은 컨텍스트 비용이 낮습니다. Claude에게 로드되는 지시 내용이 아니라, 하네스(harness)가 실행하는 코드이기 때문입니다.

출력 스타일

출력 스타일은 .claude/output-styles/에 위치하는 파일로, 시스템 프롬프트에 지시 내용을 주입합니다. 컴팩션 대상이 아니며 모든 세션 시작 시 로드됩니다. 세션 내 첫 번째 요청 이후 캐싱되어 컨텍스트 비용은 중간 수준입니다.

출력 스타일은 시스템 프롬프트에 위치하기 때문에, 지금까지 다룬 모든 방법 중 지시 내용에 대한 준수 가중치가 가장 높습니다. 그만큼 신중하게 사용해야 합니다.

출력 스타일을 변경하면 기본 출력 스타일이 대체됩니다(스타일의 프론트매터에 keep-coding-instructions: true를 설정하지 않은 경우).

Claude Code에서 이 경우, Claude에게 소프트웨어 엔지니어링 태스크를 돕고 있다고 알려주는 지시 내용과 함께 다음과 같은 중요한 기본 지시 내용들이 모두 제거됩니다:

• 변경 범위를 어떻게 설정할 것인가;
• 코드 주석을 언제 추가하고 언제 생략할 것인가;
• 보안 문제가 발견되었을 때 어떻게 처리할 것인가;
• 작업 완료 전 테스트 실행 같은 검증 습관.

커스텀 출력 스타일을 적용하면 기본적으로 이 모든 내용이 제거되어, Claude Code는 소프트웨어 엔지니어 보조가 아닌 범용 보조에 가깝게 동작하게 됩니다.

팁: 커스텀 출력 스타일을 직접 작성하기 전에 빌트인 스타일을 먼저 확인해 보세요. Proactive, Explanatory, Learning은 가장 일반적인 요구사항(자율 실행, 교육 모드, 협업 코딩)을 별도 스타일 파일 관리 없이 바로 충족합니다.

시스템 프롬프트 추가

출력 스타일 파일을 수정하는 대신 사용할 수 있는 방법이 append-system-prompt 플래그입니다. 출력 스타일 파일 수정은 Claude의 동작에 의도치 않은 큰 변화를 줄 수 있지만, 추가 플래그는 기존 시스템 프롬프트에 내용을 더하기만 할 뿐 Claude의 역할 자체는 변경하지 않습니다.

또한 호출 시점에 전달되어 해당 호출에만 적용되며, 파일로 저장되어 세션 간에 유지되지 않습니다.

시스템 프롬프트 추가는 다른 지시 전달 방법보다 컨텍스트 비용이 높을 수 있습니다. 입력 토큰이 늘어나지만, 세션 내 첫 번째 요청 이후에는 프롬프트 캐싱으로 이 비용이 줄어듭니다. 더 장황하거나 긴 스타일을 사용하도록 지시하면 출력 토큰도 늘어납니다.

팁: 시스템 프롬프트 추가는 특정 코딩 표준, 출력 포맷, 도메인별 지식을 더할 때 가장 효과적입니다. 다만 이 방법은 지시 내용이 많아질수록 준수율이 떨어지는 수확 체감이 있다는 점을 기억하세요. 특히 서로 충돌하는 내용이 있다면 더욱 그렇습니다.

Claude Code 커스터마이즈 핵심 팁

다음과 같은 방식으로 지시 내용을 작성하고 있다면, 더 적합한 위치를 고려해 보세요:

CLAUDE.md에 "X할 때마다 항상 Y를 해라". 편집 후 prettier를 실행하거나 완료 시 Slack에 알림을 보내는 것처럼 반드시 일어나야 하는 동작이라면, 대신 settings.json에 훅을 사용하세요. 모델이 포매터 실행을 선택하는 것과 포매터가 자동으로 실행되는 것은 전혀 다릅니다.

CLAUDE.md에 "절대 이것은 하지 마라". 절대로 일어나서는 안 되는 일이라면, 지시 내용은 적절한 도구가 아닙니다. Claude는 대부분의 경우 지시를 따르겠지만, 긴 세션이나 모호한 상황, 또는 태스크 수행 중 접근한 파일에 포함된 프롬프트 인젝션 등 압박 상황에서는 모델이 지시 내용을 따르지 못할 수 있습니다. 진정한 가드레일은 결정론적이어야 하며, 이를 위한 수단은 훅과 권한 설정입니다. PreToolUse 훅은 호출을 검사하고 종료 코드 2를 반환해 차단할 수 있습니다. 관리형 설정 은 한 단계 더 나아가 관리자가 배포하며, 사용자의 로컬 설정으로 재정의할 수 없고, 결정론적인 조직 전체 가드레일을 적용하는 유일한 방법입니다.

CLAUDE.md에 30줄짜리 절차. 절차는 스킬에 두세요. CLAUDE.md는 빌드 명령어, 모노레포 구조, 팀 컨벤션처럼 Claude가 항상 알고 있어야 할 사실을 위한 공간입니다. 배포 런북이나 보안 리뷰 체크리스트는 .claude/skills/에 두어 호출 시에만 본문이 로드되도록 해야 합니다.

경로 지정 없이 특정 API에만 적용되는 규칙. 규칙이 src/api/**에만 적용된다면, paths:로 범위를 지정해 관련 없는 작업 중에는 컨텍스트에서 제외하세요. 범위가 지정되지 않은 규칙은 CLAUDE.md에 내용을 넣는 것과 기계적으로 동일합니다. 항상 로드되고, 항상 토큰을 소비합니다.

개인 설정을 프로젝트 수준 CLAUDE.md 파일에 작성하는 경우. 파일 기반 방법에는 모두 사용자 수준 대응 파일이 있으며, 어느 저장소에 있든 모든 Claude Code 세션에서 로드됩니다. 개인 설정(항상 시맨틱 커밋 메시지 사용 등)은 로컬 파일에, 특정 코드베이스에 국한된 팀 전체 설정은 프로젝트 수준 파일에 두세요.

시작하기

환경 설정부터 병렬 세션 확장까지, Claude Code를 최대한 활용하기 위한 더 많은 팁과 패턴은 Claude Code 모범 사례 문서에서 확인할 수 있습니다.

이 방법들을 몇 가지 익히고 나면, 스킬·서브에이전트·훅·출력 스타일을 하나의 플러그인으로 묶어 팀원이나 프로젝트 간에 일관된 설정을 공유할 수 있습니다.