Claude Code에는 CLAUDE.md

・규칙(Rules), 스킬(Skills), 서브 에이전트(Sub-agents), 커스텀 커맨드(Custom commands), 훅(Hooks) 등 다양한 커스텀 방법이 있습니다.

막상 사용하려고 하면 "결국 무엇을 사용해야 하지?"라며 고민하는 분들이 많을 것입니다. 저 자신도 처음에는 이러한 기능들의 구분 사용에 상당히 혼란을 겪었습니다.

하지만 이것들은 2가지 축으로 정리하면, 각각의 차이점과 사용 시점이 명확하게 보입니다. 이 기사에서는 그 2가지 축을 사용하여 6가지 기능의 전체상을 전달하겠습니다.

• 6가지 커스텀 기능을 정리하는 「2가지 축」
• 각 기능의 역할과 사용 시점 (회사의 조직에 비유하여 해설)
• 「확률론적으로 동작하는 기능」과 「결정론적으로 동작하는 기능」의 차이

혼란의 원인은 기능을 「낱개의 점」으로 외우려고 하는 데 있습니다. 다음 2가지 축에 따라 나열하면 길을 잃지 않게 됩니다.

축 1: 언제 읽히는가 (타이밍)

• 기동 시 항상 읽힘
• 조건부로 (반자동으로) 읽힘
• Claude가 「필요」하다고 판단했을 때만 읽힘
• 수동으로 명시적으로 호출
• 이벤트 발생 시 자동 실행

축 2: 누가 움직이는가 (실행 주체)

• Claude Code 본체 (메인 프로세스)가 움직임
• 별도 프로세스 (분신)가 움직임
• Claude Code와는 별개의 프로그램/스크립트가 움직임

「누가 움직이는가」로 나열하면 다음 3가지 그룹으로 나뉩니다.

이 기능들은 회사의 조직에 비유하면 이미지를 잡기 쉽습니다.

기능	조직에서의 비유	언제 읽히는가	누가 움직이는가
CLAUDE.md	경영 이념 · 취업 규칙	기동 시 항상	본체 (메인)
규칙 (Rules)	부서별 매뉴얼	조건부 · 반자동	본체 (메인)
스킬 (Skills)	사내 Wiki · 지식 베이스	Claude가 필요하다고 판단할 때	본체 (메인)
커스텀 커맨드 (Custom commands)	정형 업무 템플릿	수동으로 명시적으로 호출	본체 (메인)
서브 에이전트 (Sub-agents)	전문 팀 · 외부 컨설턴트	업무를 맡겼을 때	별도 프로세스 (분신)
훅 (Hooks)	자동화 시스템	이벤트 발생 시 자동	프로그램 / 스크립트

여기서부터는 하나씩 자세히 살펴보겠습니다.

Claude Code를 배우기 시작하며 가장 먼저 접하게 되는, 가장 친숙한 기능입니다.

CLAUDE.md는 기동 시 자동으로 반드시 읽히는 파일로, 조직으로 치면 「경영 이념 · 취업 규칙」에 해당합니다. 프로젝트 전체의 공통 규칙이나 규약, 코딩 규약 등을 적어두는 장소입니다.

# 코딩 규약
- 인덴트(Indent)는 공백 2개
- 커밋 메시지는 Conventional Commits를 따름

이렇게 해두면 프로젝트의 배경이나 약속 사항을 매번 설명하는 수고를 덜 수 있으며, Claude Code는 항상 그 규칙을 의식하며 작업해 줍니다.

주의점: 너무 길게 만들지 말 것

CLAUDE.md는 항상 읽히기 때문에, 내용이 너무 길어지면 컨텍스트 (즉, Claude의 머리)를 압박합니다. 규칙이 많다고 해서 무엇이든 적으면 되는 것이 아니라, 「정말로 항상 의식해주길 바라는 것」으로만 압축합시다. 개별적인 규칙은 이후의 기능들을 통해 필요할 때만 알려주는 것이 요령입니다.

CLAUDE.md의 비대화 문제를 비교적 간단하게 해결해 주는 것이 규칙(Rules) 파일입니다. .claude/rules에 두며, 조직으로 치면 「해당 부서에서만 필요한 매뉴얼」에 해당합니다.

포인트는 조건부 (반자동)로 읽힌다는 점입니다. path 필드에서 폴더명이나 확장자를 지정하면, 해당 파일을 읽거나 변경할 때만 규칙이 읽힙니다.

src/api/ 하위를 만졌을 때만 → API 개발 규칙을 읽어옴

• 테스트 파일을 작성할 때만 → 테스트에 관한 규칙을 읽어옴

「정말로 필요할 때만 규칙을 가르쳐줄」 수 있으므로, 컨텍스트 절약 관점에서 매우 유효합니다.

스킬(Skills)은 규칙과 조금 달라서, Claude 스스로가 「필요하다」고 자율적으로 판단했을 때만 읽는 것입니다. 조직으로 치면 「사내 Wiki · 지식 베이스」에 해당합니다.

읽어들이는 방식이 특징적입니다. 평소에는 「어디에 무엇이 적혀 있는지」에 대한 목차(설명문)만이 메모리에 상주하고 있다가, 필요해졌을 때 비로소 내용 전체, 혹은 단계적으로 필요한 부분만을 읽어들입니다.

그렇기 때문에 스킬(Skill)을 수백 개 등록해 두더라도 항상 읽히는 것은 목차와 설명문뿐입니다. 컨텍스트(Context)를 압박하지 않는다는 것이 장점입니다.

주의점: 설명문이 핵심

읽어들일지 여부는 목차와 설명문을 바탕으로 Claude가 자동으로 판단합니다. 따라서 설명문이 모호하거나 목차로서 부적절하면, 필요할 때 읽어들이지 못하는 경우가 있습니다. 또한, 목차와 설명문 자체는 기동 시에 읽히므로, 이것이 너무 길어지면 결국 컨텍스트를 압박하게 된다는 점에도 주의해야 합니다.

여기서부터는 「규칙(Rule)」이 아니라, 동작하는 타이밍이나 역할에 관한 이야기입니다.

서브 에이전트(Sub-agent)는 메인 Claude Code와는 별개로 움직이는 분신 같은 것입니다. 평소 직접 대화하고 있는 Claude Code를 「메인」이라고 한다면, 복제된 독립적인 Claude Code가 분신으로서 움직이는 이미지입니다. 조직으로 치면 「전문 팀 · 외부 컨설턴트」의 위치입니다.

가장 큰 포인트는 메인의 컨텍스트와는 완전히 독립하여 작업한다는 것입니다.

예를 들어 「이 기능의 구현이 어딘가에 있었던 것 같다」라고 느낄 때, 「해당 소스 코드를 찾아두어」라고 분신에게 의뢰하고, 결과만을 보고받을 수 있습니다. 메인의 대화 흐름을 흐리지 않고 컨텍스트를 절약할 수 있으며, 나아가 여러 개를 병렬로 동시 실행하는 것도 가능합니다.

100개 이상의 파일로 구성된 코드베이스를 조사할 때 등, 대규모 조사일수록 그 혜택이 커집니다. 저도 대규모 조사나 비슷한 코드를 찾을 때는 서브 에이전트에게 맡기는 경우가 많습니다.

커스텀 커맨드(Custom Command)는 프롬프트를 /명령어이름 형태로 호출할 수 있는 기능입니다. 조직으로 치면 「신청서 · 보고서 포맷을 미리 준비해 두는 것」과 같은, 정형 업무의 템플릿화에 해당합니다.

서브 에이전트와의 큰 차이점은 자동으로 호출되지 않고, 명시적으로 실행한다는 점입니다.

# 예: 변경 내용으로부터 커밋 메시지를 제안받는 커맨드
/suggest-commit

단 하나의 커맨드로 복잡한 지시를 실행하고 싶을 때 유용합니다. 나아가 커맨드 안에 스킬이나 서브 에이전트의 이름 · 사용처를 적어 두면, 그것들을 명시적으로 호출할 수 있으므로 적은 노력으로 매끄럽게 연계할 수 있습니다.

마지막은 훅(Hook)입니다. 조금 어렵게 말하면 「라이프사이클 이벤트(Lifecycle Event)에서 자동으로 실행되는 커맨드」입니다. 직접 작성한 스크립트 등도 실행할 수 있어 범용성이 높은 기능입니다.

조직으로 치면 「자동화 시스템」입니다. 예를 들어 아침에 컴퓨터를 켜면 (=이벤트), 출근 도장이 자동으로 찍히는 (=실행되는 처리) 것과 같은 이미지입니다.

여기서의 포인트는 **결정론적(Deterministic)**이라는 것입니다. 설정한 처리는 확실하게 100% 실행되며, AI의 판단에 의존하지 않습니다.

훅을 이해하는 데 있어 중요한 것이 바로 이 차이입니다.

CLAUDE.md나 규칙에 적은 지시는 Claude가 AI로서 머리로 판단하여, 학습 결과로부터 「확률적으로 맞을 것 같으면 실행한다」라는 **확률론적(Probabilistic)**인 방식으로 움직입니다. 「제대로 지시했는데 실행해주지 않았다」라는 경험을 해본 분들도 많을 것입니다. 유연한 반면, 확실하게 실행된다는 보장은 없습니다.

반면 훅은 결정론적이며, 특정 이벤트에 기반하여 확실하게 커맨드나 스크립트를 실행합니다. 유연성은 낮지만 확실성을 취한다는 특징이 있습니다.

「유연함을 취할 것인가, 확실함을 취할 것인가」에 따라 구분해서 사용하면 좋습니다.

Claude Code의 6가지 커스터마이징 기능은 「누가 움직이는가」, 「언제 읽히는가」라는 두 가지 축으로 정리하면 혼란을 줄일 수 있습니다.

누가 움직이는가

• 본체(메인)가 움직임 (4개) … CLAUDE.md / 규칙(Rule) / 스킬(Skill) / 커스텀 커맨드
• 별도 프로세스(분신)가 움직임 … 서브 에이전트
• 프로그램 / 스크립트가 움직임 … 훅

언제 읽히는가

• 상시 / 조건부로 반자동 / Claude의 판단으로 필요할 때 / 수동 / 이벤트로 자동

마지막으로 보충 설명 하나를 덧붙입니다. 스킬 (Skill)과 서브 에이전트 (Sub-agent)는 "Claude가 필요하다고 판단했을 때 또는 요청받았을 때" 작동하지만, 프롬프트 (Prompt) 내에서 "이 스킬을 사용해" 또는 "이 서브 에이전트를 사용해"라고 명시적으로 지정하면 거의 확실하게 호출할 수 있습니다. 조금 까다로운 부분일 수 있지만, 이를 기억해 두면 연동이 훨씬 원활해집니다.

각각의 역할을 이해하여, CLAUDE.md를 비대하게 만들지 않고 현명하게 커스텀 (Customize) 해 나갑시다.