4. Claude Code 확장 기능: 서브에이전트·스킬·훅 활용

Claude Code는 대화창 하나가 전부가 아니다. 작업을 더 잘 굴리는 세 개의 확장 장치가 있다. 스킬은 필요할 때 펼쳐 보는 작업 매뉴얼이고, 서브에이전트는 자기 책상에서 따로 일하고 결과만 보고하는 외주 직원이며, 훅은 조건이 맞으면 사람이 안 시켜도 무조건 작동하는 자동 센서다. 셋을 헷갈려 쓰면 설정이 엉키고, 제자리에 쓰면 메인 작업 흐름이 가벼워진다.

세 장치를 한눈에 비교하면 이렇다.

1 서브에이전트로 작업을 외주 직원에게 맡기기

서브에이전트는 메인 대화가 직접 하기엔 컨텍스트만 잡아먹는 일을 떼어 주는 별도 작업자다. 코드 리뷰, 테스트 수리, 로그 뒤지기 같은 일을 맡기면, 그 작업자가 자기 컨텍스트 안에서 일하고 결과만 가져온다. 메인 대화창에는 장황한 검색 기록이나 로그가 쌓이지 않는다. 여기서는 코드 리뷰 전담 서브에이전트 하나를 만들어 손에 남긴다.

1.1 작업 환경 준비

1. 터미널을 연다. Windows는 [시작]에서 cmd 또는 PowerShell, macOS는 ⌘+Space로 Spotlight를 열고 Terminal을 입력해 Enter 한다.
2. 실습용 프로젝트 폴더로 이동한다. 명령어 cd 프로젝트경로를 입력하고 Enter 한다. 예) cd ~/projects/demo.
3. Claude Code를 실행한다. 명령어 claude를 입력하고 Enter 한다.
4. 작업 기록용 메모장을 함께 연다. 폴더 안에 claude_확장_메모.txt 파일을 새로 만들어 둔다. 만든 서브에이전트·스킬·훅의 이름과 경로를 여기에 적어 나간다.

1.2 /agents로 서브에이전트 만들기

1. Claude Code 프롬프트(>)에 명령어 /agents를 입력하고 Enter 한다.
2. 메뉴가 뜨면 [Create new agent]를 선택한다. 방향키 ↑ ↓로 옮기고 Enter로 고른다.
3. 적용 범위를 묻는 화면에서 범위를 고른다.
   1. [Project]를 고르면 이 프로젝트에서만 쓴다(.claude/agents/에 저장).
   2. [Personal]을 고르면 내 모든 프로젝트에서 쓴다(~/.claude/agents/에 저장).
4. 설명(description)을 입력하는 칸에 이 서브에이전트를 언제 부를지 적는다. 아래 문장을 그대로 입력한다.

최근 변경한 코드의 가독성·버그·보안 문제를 검토하는 코드 리뷰 전담 에이전트. 사용자가 "리뷰", "검토해줘"라고 하면 사용한다.

1. 이어서 Claude가 이 설명을 바탕으로 시스템 프롬프트 초안을 만들어 보여 준다. 내용을 확인하고 Enter로 저장한다. 직접 고치려면 e를 눌러 편집기로 연다.

1.3 서브에이전트 파일 직접 열어 확인하기

/agents로 만든 결과가 실제로 어떤 파일인지 본다. 직접 손으로 만들 수도 있는 구조다.

1. 새 터미널 탭을 열거나, 편집기로 방금 만든 파일을 연다. 프로젝트 범위로 저장했다면 경로는 .claude/agents/code-reviewer.md 형태다.
2. 파일 맨 위 ---로 감싼 부분(YAML 프론트매터)을 확인한다. 아래 형태로 들어 있다.

---
name: code-reviewer
description: 최근 변경한 코드의 가독성·버그·보안 문제를 검토하는 코드 리뷰 전담 에이전트. 사용자가 "리뷰", "검토해줘"라고 하면 사용한다.
tools: Read, Grep, Glob
model: sonnet
---

당신은 코드 리뷰 전문가다. 최근 변경분을 읽고 가독성·버그·보안 관점에서
문제를 찾아 짧고 구체적으로 보고한다. 파일을 직접 고치지 않는다.

1. 각 필드의 뜻을 확인한다.
   1. name — 서브에이전트의 식별 이름. 호출할 때 이 이름을 쓴다.
   2. description — 언제 이 에이전트를 부를지. 자동 위임의 기준.
   3. tools — 쓸 수 있는 도구 목록. 이 줄을 통째로 빼면 모든 도구를 물려받는다.
   4. model — 쓸 모델. sonnet·opus·haiku 별칭이나 inherit(메인 대화와 같은 모델)을 적는다. 줄을 빼면 기본값을 따른다.
2. --- 아래 본문은 이 에이전트의 시스템 프롬프트다. 여기 적은 지시가 그 작업자의 행동 규칙이 된다.

1.4 서브에이전트 불러 쓰기

만든 서브에이전트를 실제로 호출하는 방법은 세 가지다. 통제 강도가 다르다.

1. 첫째, 자연어로 이름 부르기 — Claude가 위임할지 스스로 정한다. 프롬프트에 아래처럼 입력하고 Enter 한다.

code-reviewer 서브에이전트로 방금 바꾼 파일을 검토해줘.

1. 둘째, @-멘션으로 못박기 — 그 작업 한 번은 반드시 그 에이전트가 맡는다. @를 입력하면 뜨는 목록에서 code-reviewer를 ↑ ↓로 골라 Enter 한 뒤, 할 일을 이어 적는다.
2. 셋째, 세션 전체 고정 — 터미널 진입 시 claude --agent code-reviewer로 실행하면 그 세션 내내 이 에이전트의 프롬프트·도구·모델로 동작한다.

1.5 응용 — 내 작업용 서브에이전트 만들기

위에서 만든 흐름을 내 일에 맞는 서브에이전트로 한 번 더 만든다. 아래 프롬프트를 Claude Code 프롬프트(>)에 붙여 넣고 {중괄호}를 내 값으로 채운다.

다음 사양의 서브에이전트 파일을 .claude/agents/{에이전트이름}.md 로 만들어줘.
- 역할: {이 에이전트가 전담할 작업 한 줄}
- 자동 위임 조건(description): 사용자가 "{호출 표현1}", "{호출 표현2}"라고 할 때
- 허용 도구(tools): {Read, Grep, Glob 등 / 읽기만이면 쓰기 도구 제외}
- 모델(model): {haiku=잔일 / sonnet=일반 / opus=무거운 판단 / inherit=메인과 동일}
시스템 프롬프트 본문에는 이 에이전트가 지켜야 할 행동 규칙을 평어체로 적어줘.
파일을 직접 수정하면 안 되는 에이전트면 "파일을 고치지 않는다"를 규칙에 넣어줘.

1. {에이전트이름} — 영문 소문자·하이픈. 예) test-runner, doc-writer.
2. {이 에이전트가 전담할 작업 한 줄} — 예) 실패한 테스트를 찾아 원인을 고치고 다시 돌린다.
3. {호출 표현1}, {호출 표현2} — 내가 평소 쓰는 말. 예) 테스트 고쳐줘, 빌드 깨진 거 봐줘.
4. {tools} — 읽기 전용이면 Read, Grep, Glob. 고쳐야 하면 Read, Edit, Write, Bash를 더한다.
5. {model} — 위 표 기준으로 고른다.

채운 예시 한 벌은 이렇다.

다음 사양의 서브에이전트 파일을 .claude/agents/test-runner.md 로 만들어줘.
- 역할: 실패한 테스트를 찾아 원인을 고치고 다시 돌린다
- 자동 위임 조건(description): 사용자가 "테스트 고쳐줘", "빌드 깨진 거 봐줘"라고 할 때
- 허용 도구(tools): Read, Edit, Write, Bash
- 모델(model): sonnet
시스템 프롬프트 본문에는 이 에이전트가 지켜야 할 행동 규칙을 평어체로 적어줘.

2 스킬로 반복 절차를 지식으로 박기

스킬은 "이 작업은 이렇게 한다"는 절차를 글로 적어 둔 파일이다. 서브에이전트와 달리 별도 작업자를 띄우지 않는다. 지금 대화와 같은 컨텍스트 안에서, 필요할 때 그 지침이 추가로 펼쳐질 뿐이다. 매번 똑같은 설명을 복사해 붙여 넣던 일을 한 번 적어 두고 재사용한다. 여기서는 "회의록 정리" 스킬 하나를 만든다.

2.1 스킬 폴더 만들기

1. 터미널에서 스킬 폴더를 만든다. 명령어 mkdir -p .claude/skills/meeting-notes를 입력하고 Enter 한다.
2. 폴더가 만들어졌는지 확인한다. 명령어 ls .claude/skills를 입력하고 Enter 하면 목록에 meeting-notes가 보인다.

2.2 SKILL.md 작성

1. 편집기로 새 파일 .claude/skills/meeting-notes/SKILL.md를 만든다.
2. 아래 내용을 그대로 적고 저장한다. 저장 단축키는 Ctrl+S(macOS는 ⌘+S).

---
name: meeting-notes
description: 회의 메모를 결정사항·할 일·다음 안건 세 부분으로 정리한다. 사용자가 "회의록 정리", "회의 메모 다듬어줘"라고 하면 사용한다.
---

# 회의록 정리 절차

회의 메모를 받으면 아래 세 부분으로 나눠 정리한다.

1. 결정사항 — 회의에서 확정된 것만. 한 줄씩 번호로.
2. 할 일 — 담당자와 마감일을 함께. "담당자: 일 (마감)" 형식.
3. 다음 안건 — 다음 회의로 넘긴 것.

평어체로 적고, 결정 안 난 잡담은 빼고 핵심만 남긴다.

1. 파일 맨 위 --- 안의 두 필드를 확인한다.
   1. name — 스킬 이름. 폴더 이름과 같게 맞춘다.
   2. description — 이 스킬을 언제 펼칠지. 서브에이전트와 마찬가지로 이게 자동 호출의 방아쇠다.

2.3 스킬 자동 호출 확인

1. Claude Code 프롬프트로 돌아온다. 회의 메모처럼 보이는 글을 던지며 정리를 시킨다. 아래처럼 입력하고 Enter 한다.

회의 메모 정리해줘.
- A안으로 가기로 함
- 디자인은 김대리가 금요일까지
- 예산 얘기는 다음에

1. 이어서 Claude가 meeting-notes 스킬을 펼쳐, 결정사항·할 일·다음 안건 세 부분으로 나눠 답하는지 본다.

2.4 응용 — 내 절차를 스킬로 만들기

내가 매번 반복하는 작업 하나를 스킬로 박는다. 아래 프롬프트를 Claude Code에 붙여 넣고 {중괄호}를 채운다.

다음 절차를 스킬로 만들어줘. 파일은 .claude/skills/{스킬이름}/SKILL.md 로 만들고
맨 위에 name, description 프론트매터를 넣어줘.
- 스킬 이름(name): {스킬이름}
- 자동 호출 조건(description): 사용자가 "{호출 표현1}", "{호출 표현2}"라고 할 때
- 절차 본문: {이 작업을 어떤 순서로 처리하는지 단계별로}
- 출력 형식: {결과를 어떤 형태로 내놓아야 하는지}
본문은 평어체로 적어줘.

1. {스킬이름} — 영문 소문자·하이픈. 예) commit-msg, pr-summary.
2. {호출 표현1}, {호출 표현2} — 내가 평소 쓰는 말. 예) 커밋 메시지 만들어줘.
3. {절차 본문} — 평소 손으로 하던 순서를 그대로. 예) 변경 파일을 보고 한 줄 요약 + 상세 3줄로 쓴다.
4. {출력 형식} — 예) 제목 줄 50자 이내, 본문은 글머리표 3개.

채운 예시 한 벌은 이렇다.

다음 절차를 스킬로 만들어줘. 파일은 .claude/skills/commit-msg/SKILL.md 로 만들고
맨 위에 name, description 프론트매터를 넣어줘.
- 스킬 이름(name): commit-msg
- 자동 호출 조건(description): 사용자가 "커밋 메시지 만들어줘", "커밋 문구 뽑아줘"라고 할 때
- 절차 본문: 변경된 파일을 확인하고 무엇이 왜 바뀌었는지 파악한 뒤 메시지를 쓴다
- 출력 형식: 제목 줄 50자 이내, 빈 줄 하나, 본문 글머리표 3개
본문은 평어체로 적어줘.

3 훅으로 규칙을 자동 강제하기

스킬·서브에이전트는 Claude가 "쓸지 말지"를 판단한다. 훅은 다르다. 정해진 순간이 오면 사람이 안 시켜도, Claude가 판단하기도 전에 무조건 셸 명령을 실행한다. 모델 해석에 기대지 않는 결정론적 장치라, "절대 어기면 안 되는 규칙"을 박을 때 쓴다. 여기서는 위험한 셸 명령을 실행 전에 막는 안전장치 훅을 만든다.

3.1 settings.json 열기

1. 편집기로 파일 .claude/settings.json을 연다. 없으면 새로 만든다.
2. 파일이 비어 있으면 빈 객체 {} 한 줄만 넣고 시작한다. 이미 내용이 있으면 맨 바깥 중괄호 안에 hooks 항목을 더한다.

3.2 위험 명령 차단 훅 작성

1. settings.json에 아래 내용을 적는다. 셸 명령(Bash)을 실행하기 직전에 검사해 위험 패턴이 보이면 막는 훅이다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' | grep -qE 'rm -rf|DROP TABLE' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}

1. 코드를 넣었으면 파일을 저장한다(Ctrl+S).
2. 구조를 한 겹씩 확인한다.
   1. PreToolUse — 언제 작동할지 정하는 이벤트 이름. 도구를 실행하기 직전이다.
   2. matcher — 어떤 도구에서 작동할지. "Bash"는 셸 명령일 때만 건다. "Edit|Write"처럼 정규식으로 여러 도구를 묶을 수 있다.
   3. type — 훅 종류. command(셸 명령) 외에 prompt·agent·http·mcp_tool 다섯 가지가 있다.
   4. command — 실제로 실행할 셸 명령. 훅 입력은 stdin 으로 들어오는 JSON 이며 tool_input.command 필드를 검사한다. 여기서는 jq로 그 필드를 꺼내 위험 패턴이 잡히면 exit 2로 막고, 아니면 exit 0으로 통과시킨다.

3.3 훅 동작 확인

1. Claude Code를 종료했다 다시 실행한다. 설정 파일은 시작할 때 읽히므로, 고친 뒤에는 다시 켠다.
2. 프로젝트 범위 훅이면 처음 한 번 승인 화면이 뜬다. 내가 적은 훅이 맞는지 확인하고 [Allow]를 고른다.
3. 위험 명령을 일부러 시켜 본다. 프롬프트에 rm -rf 로 임시폴더 지워줘라고 입력해 Enter 한 뒤, 실행이 막히는지 본다.

3.4 응용 — 내 규칙을 훅으로 만들기

내가 "항상 이렇게 됐으면" 하는 자동 규칙 하나를 훅으로 박는다. 아래 프롬프트를 Claude Code에 붙여 넣고 {중괄호}를 채운다.

.claude/settings.json 에 추가할 훅 설정을 만들어줘.
- 이벤트: {PreToolUse=실행 전 검사·차단 / PostToolUse=실행 후 자동 처리}
- 대상 도구(matcher): {Bash / Edit|Write 등}
- 하고 싶은 동작: {언제 무엇을 자동으로 / 무엇을 막을지}
- 차단이 필요하면 PreToolUse에서 조건이 맞을 때 exit 2 로 막아줘.
기존 settings.json 내용을 지우지 말고 hooks 항목만 더하는 형태로 만들어줘.

1. {이벤트} — 막고 싶으면 PreToolUse, 끝난 뒤 처리하고 싶으면 PostToolUse.
2. {matcher} — 셸 명령은 Bash, 파일 편집은 Edit|Write.
3. {하고 싶은 동작} — 예) 파일을 고칠 때마다 자동으로 포매터를 돌린다.

채운 예시 한 벌은 이렇다.

.claude/settings.json 에 추가할 훅 설정을 만들어줘.
- 이벤트: PostToolUse
- 대상 도구(matcher): Edit|Write
- 하고 싶은 동작: 파일을 고치거나 새로 쓸 때마다 자동으로 prettier 포매터를 돌린다
기존 settings.json 내용을 지우지 말고 hooks 항목만 더하는 형태로 만들어줘.

막히면 — AI 코치에게 묻기

이 문서에서 익힌 Claude Code의 서브에이전트·스킬·훅을 제자리에 만들어 쓰는 법을 내 상황에 적용하다 막히면, 아래를 대화형 AI(ChatGPT·Claude·Gemini)에 붙여 넣어 실습 코치로 삼는다. 답을 한꺼번에 받지 말고 한 단계씩 풀어 간다.

너는 Claude Code 확장 기능 실습 코치다. 나는 서브에이전트(.claude/agents)·스킬(.claude/skills/SKILL.md)·훅(.claude/settings.json) 세 장치의 차이와 제자리를 배웠고, 내 작업에 맞는 장치 하나를 골라 직접 만들어 동작시키려 한다. 답을 통째로 주지 말고 한 단계씩 물어 내가 직접 하게 한다.

[코칭 방식]
1. 먼저 내가 자동화하려는 작업과 셋 중 어느 장치를 고르려는지 묻는다.
2. 막힌 원인을 한 가지 짚어 준다. 완성된 파일·설정 전체를 통째로 주지 않는다.
3. 다음 한 단계만 제시하고, 내가 해 본 결과를 말하면 확인 질문을 던진다.
4. 마지막에 장치 선택이 맞는지(반복 지침은 스킬, 무거운 별도 작업은 서브에이전트, 강제 규칙은 훅) 점검 질문을 한다.

[내 상황]
- 지금까지 한 것: {한것}
- 막힌 지점·메시지: {막힌점}
- 내 소재: {소재}

준비됐으면 "자동화하려는 작업과 고른 장치는 무엇인가?"라고만 답한다.

1. {한것} — 지금까지 진행한 단계, 예: /agents로 코드 리뷰 서브에이전트를 만들고 description을 적었다.
2. {막힌점} — 막힌 부분이나 받은 메시지, 예: 자연어로 불러도 Claude가 그 에이전트로 위임하지 않는다.
3. {소재} — 적용할 내 자료·주제, 예: 커밋 메시지를 매번 같은 형식으로 뽑는 작업.

채운 예시 한 벌은 이렇다.

너는 Claude Code 확장 기능 실습 코치다. 나는 서브에이전트(.claude/agents)·스킬(.claude/skills/SKILL.md)·훅(.claude/settings.json) 세 장치의 차이와 제자리를 배웠고, 내 작업에 맞는 장치 하나를 골라 직접 만들어 동작시키려 한다. 답을 통째로 주지 말고 한 단계씩 물어 내가 직접 하게 한다.

[코칭 방식]
1. 먼저 내가 자동화하려는 작업과 셋 중 어느 장치를 고르려는지 묻는다.
2. 막힌 원인을 한 가지 짚어 준다. 완성된 파일·설정 전체를 통째로 주지 않는다.
3. 다음 한 단계만 제시하고, 내가 해 본 결과를 말하면 확인 질문을 던진다.
4. 마지막에 장치 선택이 맞는지(반복 지침은 스킬, 무거운 별도 작업은 서브에이전트, 강제 규칙은 훅) 점검 질문을 한다.

[내 상황]
- 지금까지 한 것: .claude/skills/commit-msg/SKILL.md를 만들고 name과 description을 적었다.
- 막힌 지점·메시지: "커밋 메시지 만들어줘"라고 해도 스킬 형식대로 안 나온다.
- 내 소재: 커밋 메시지를 제목 50자·본문 글머리표 3개 형식으로 뽑는 작업.

준비됐으면 "자동화하려는 작업과 고른 장치는 무엇인가?"라고만 답한다.