클로드코드 서브에이전트·스킬·훅, 각각 언제 쓰나요?

클로드코드(Claude Code)를 조금 쓰다 보면 비슷해 보이는 이름이 한꺼번에 등장합니다. 스킬, 서브에이전트, 훅, 커스텀 커맨드. 검색하면 각각의 설명은 나오는데, 정작 무엇을 언제 써야 하는지는 잘 안 나와요.

세 가지는 목적이 전부 다릅니다.

스킬       반복하는 절차를 저장해두고 불러 씀
서브에이전트  긴 작업을 따로 시키고 요약만 받음
훅         특정 순간에 무조건 실행되는 규칙

먼저 알아둘 것이 있습니다. 셋 다 안 만들어도 클로드코드는 잘 돌아갑니다. 뚝딱 수강생 대부분은 첫 프로젝트를 끝낼 때까지 하나도 만들지 않아요. 필요해지는 순간이 있고, 그 순간이 오기 전에 만들면 관리할 파일만 늘어납니다.

그전에: 그냥 규칙이라면 CLAUDE.md

셋 중 무엇을 고를지 고민하기 전에 확인할 것이 있습니다.

"이 프로젝트는 항상 이렇게 해줘"

→ CLAUDE.md

프로젝트에서 늘 지켜야 하는 사실과 규칙은 CLAUDE.md에 적으면 됩니다. 데이터베이스는 무엇을 쓰는지, 폴더 구조는 어떤지, 커밋 메시지는 어떤 형식인지 같은 것들이에요. 클로드코드는 대화를 시작할 때 이 파일을 읽습니다. 자세한 내용은 CLAUDE.md란?에 있어요.

CLAUDE.md의 한 항목이 사실이 아니라 절차로 자라났을 때, 그때가 스킬을 만들 시점입니다.

CLAUDE.md
→ "우리는 Supabase를 쓴다" (사실)

스킬
→ "배포하기 전에 1. 테스트 실행
   2. 빌드 3. 마이그레이션 확인" (절차)

스킬: 반복하는 절차를 저장해요

스킬은 SKILL.md라는 파일 하나로 만듭니다. 폴더를 만들고 그 안에 파일을 넣으면 끝이에요.

~/.claude/skills/<이름>/SKILL.md
→ 내 모든 프로젝트에서 사용

.claude/skills/<이름>/SKILL.md
→ 이 프로젝트에서만 사용

폴더 이름이 그대로 명령어가 됩니다. deploy 폴더를 만들면 /deploy로 실행할 수 있어요.

파일 안은 두 부분입니다. 위쪽 --- 사이에 이 스킬이 무엇이고 언제 쓰는지 적고, 아래에 실제 지시를 적습니다.

---
description: 배포 전 점검. 배포하기 전이나
  "배포해줘"라고 할 때 사용.
---

배포 전에 다음을 순서대로 확인해줘.

1. 테스트를 실행하고 전부 통과하는지 확인
2. 빌드가 성공하는지 확인
3. 적용하지 않은 마이그레이션이 있는지 확인
4. 하나라도 실패하면 배포하지 말고 알려줘

스킬을 부르는 방법은 두 가지입니다. 직접 /deploy라고 입력하거나, 클로드가 description을 보고 알아서 불러오게 두는 방식이에요. 배포처럼 결과가 되돌리기 어려운 작업은 클로드가 알아서 실행하면 곤란하니, disable-model-invocation: true를 넣어 직접 부를 때만 실행되게 할 수 있습니다.

스킬의 좋은 점은 필요할 때만 컨텍스트에 올라온다는 것입니다. 평소에는 설명 한 줄만 올라가 있고, 실제로 부를 때 전체 내용이 들어와요. 그래서 긴 참고 자료도 CLAUDE.md에 다 적는 것보다 스킬로 두는 편이 가볍습니다.

기존에 .claude/commands/ 폴더에 만들던 커스텀 커맨드는 스킬로 합쳐졌습니다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들고 똑같이 동작해요. 예전에 만든 파일은 그대로 쓰면 됩니다.

클로드 채팅의 스킬로 웹앱을 만들지 않고도 업무를 해결할 수 있는 경우는 바이브코딩을 시작하기 전에 클로드 스킬로 해결할 수 있는지 확인하세요에서 다뤘습니다.

서브에이전트: 지저분한 작업을 따로 맡겨요

서브에이전트는 자기만의 컨텍스트 윈도우에서 일하는 별도 대화입니다. 일을 맡기면 혼자 파일을 뒤지고 명령을 실행한 뒤, 결과 요약만 돌려줘요.

왜 필요한지는 상황으로 보면 명확합니다.

"이 프로젝트에서 결제 관련 코드가
어디에 흩어져 있는지 찾아줘"

→ 파일 40개를 읽음
→ 그 내용이 전부 내 대화에 쌓임
→ 정작 필요한 건 "이 파일 3개예요" 한 줄

읽은 파일 40개의 내용은 앞으로의 대화에 계속 따라다닙니다. 컨텍스트를 차지하고 판단을 흐리게 만들어요. 서브에이전트에 맡기면 그 40개를 읽는 일은 다른 컨텍스트에서 벌어지고, 내 대화에는 요약만 들어옵니다.

클로드코드에는 기본 서브에이전트가 이미 들어 있습니다.

그래서 서브에이전트를 직접 만들지 않아도 클로드는 필요할 때 알아서 이들에게 맡깁니다. 작업 중에 "Explore 에이전트를 실행 중"이라는 표시를 본 적이 있다면 그게 이거예요.

직접 만드는 건 같은 성격의 일을 반복해서 시킬 때입니다. 파일은 .claude/agents/ 폴더에 만들고, 위쪽에 이름과 설명을 적습니다.

---
name: db-checker
description: 마이그레이션과 스키마 변경을 검토.
  스키마를 바꾼 뒤에 사용.
tools: Read, Glob, Grep
---

너는 데이터베이스 변경을 검토하는 역할이다.
스키마 변경이 기존 데이터를 잃게 만들 수 있는지,
되돌릴 수 있는지 확인하고 위험한 부분을 지적해라.

tools로 쓸 수 있는 도구를 제한할 수 있다는 점이 중요합니다. 위 예시는 읽기 도구만 줬으니 이 에이전트는 파일을 고칠 수 없어요. "검토만 하고 손대지는 말라"는 요청을 도구 제한으로 적용하는 방식입니다.

훅: 정해진 순간에 실행해요

스킬과 서브에이전트는 클로드가 내용을 읽고 판단해 실행합니다. 훅은 특정 사건이 생겼을 때 미리 정한 프로그램을 실행합니다.

포매터 실행과 위험한 명령 차단처럼 매번 같은 방식으로 처리해야 하는 일에 잘 맞아요.

스킬 "배포 전에 테스트를 실행해줘"
→ 클로드가 판단해서 실행

훅 "파일을 수정한 뒤 포매터 실행"
→ 파일 편집 도구가 실행되면 정해진 명령 실행

프로젝트에서 함께 쓸 훅은 .claude/settings.json에 적습니다. 내 컴퓨터의 모든 프로젝트에서 사용할 훅은 ~/.claude/settings.json에 둬요. 어떤 순간에 무엇을 실행할지 지정하는 방식입니다.

예를 들어 클로드가 파일 편집 도구를 사용한 뒤 프로젝트의 포맷 명령을 실행하려면 .claude/settings.json에 다음처럼 적습니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run format"
          }
        ]
      }
    ]
  }
}

Edit|Write는 클로드가 Edit 또는 Write 도구를 사용했을 때만 일치합니다. Bash 명령이 직접 바꾼 파일까지 모두 감지하는 설정은 아니에요. 저장한 뒤 /hooks를 실행하면 훅이 올바른 이벤트 아래에 등록됐는지 확인할 수 있습니다.

실제로 많이 쓰는 용도는 두 가지입니다.

정리 자동화 — 파일을 수정할 때마다 포매터를 돌리거나 타입 검사를 실행합니다. 매번 "포맷도 맞춰줘"라고 말할 필요가 없어져요.

사고 방지 — 위험한 명령을 실행하기 직전에 막습니다. PreToolUse 훅은 도구 실행을 중단시킬 수 있어서, 파일을 지우는 명령이나 운영 데이터베이스에 직접 연결하는 명령을 차단하는 데 씁니다. 배포 전에는 훅 설정만 믿지 말고 웹앱 보안 체크리스트로 권한과 운영 환경도 함께 확인하세요.

두 번째는 삭제나 운영 환경 접근 같은 위험한 작업을 다룰 때 특히 중요합니다. 같은 위험을 반복해서 확인하고 있다면 PreToolUse 훅으로 실행 전에 막는 편이 좋습니다.

다만 훅은 설정 파일을 직접 다뤄야 해서 셋 중 진입 장벽이 가장 높습니다. 처음부터 만들 필요는 없고, 같은 사고를 두 번 겪었을 때 만들면 됩니다.

무엇을 쓸지 고르는 기준

한 문장으로 줄이면 이렇습니다.

알아야 하는 것 → CLAUDE.md
해야 하는 것   → 스킬
대신 해줄 것   → 서브에이전트
막아야 하는 것 → 훅

처음부터 만들지 마세요

정리해두고 이렇게 말하는 게 이상하게 들릴 수 있지만, 순서가 중요합니다.

1. 그냥 대화로 시작
2. 반복되는 규칙이 생기면 CLAUDE.md
3. 반복되는 절차가 생기면 스킬
4. 같은 사고를 두 번 겪으면 훅

설정을 먼저 갖추고 시작하면 관리할 파일이 늘어난 만큼 클로드가 읽어야 할 것도 늘어납니다. 정작 무엇이 반복되는 일인지는 몇 주 써봐야 알 수 있어요.

각 기능의 전체 설정 항목은 공식 문서에 정리돼 있습니다. 스킬 (새 탭에서 열림), 서브에이전트 (새 탭에서 열림), 훅 (새 탭에서 열림) 문서를 필요할 때 열어보세요.

먼저 익힐 것은 이런 확장 기능이 아니라 기본 동작입니다. 처음에 익힐 슬래시 커맨드와 /clear·/compact 차이부터 손에 붙이면, 이 셋 중 무엇이 필요한지는 자연스럽게 보입니다.