08. 서브에이전트, 커스텀 커맨드, 훅

전문가 AI 위임, 반복 프롬프트 자동화, 이벤트 기반 스크립트 실행을 이해한다.

1. 서브에이전트 (Sub Agent) 개요

서브에이전트란?

서브에이전트는 메인 컨텍스트와 독립적으로 동작하는 전문가 AI다. 메인 에이전트(사용자가 직접 대화하는 Claude Code)가 복잡하거나 전문적인 작업을 만났을 때, 해당 작업을 서브에이전트에게 위임한다. 서브에이전트는 자신만의 독립 컨텍스트에서 작업을 수행하고, 결과만 메인 에이전트에게 돌려준다.

왜 서브에이전트가 필요한가? 메인 에이전트의 컨텍스트 윈도우에는 한계가 있다. 대화가 길어지고 작업이 복잡해지면 컨텍스트가 점점 쌓이고, 모델의 정확도가 떨어진다. 서브에이전트는 이 문제를 근본적으로 해결한다.

메인 에이전트와 서브에이전트의 동작 흐름

이 다이어그램에서 핵심은 서브에이전트의 작업 과정이 메인 컨텍스트를 차지하지 않는다는 점이다. 서브에이전트가 파일을 읽고, 분석하고, 작성하는 모든 중간 과정은 서브에이전트의 독립 컨텍스트에서만 일어난다. 메인 에이전트에는 최종 결과만 돌아오므로 메인 컨텍스트가 오염되지 않는다.

서브에이전트의 핵심 특성

특성	설명
독립 컨텍스트	메인 에이전트와 별도의 컨텍스트 윈도우에서 동작한다. 서로의 중간 과정을 공유하지 않는다
전문화	특정 역할(PRD 작성, 코드 리뷰 등)에 최적화된 프롬프트와 규칙을 가진다
위임 기반	메인 에이전트가 필요할 때 호출하고, 결과만 받아온다
컨텍스트 보호	서브에이전트의 작업이 아무리 많아도 메인 컨텍스트의 토큰을 소비하지 않는다

서브에이전트를 사용해야 하는 상황

서브에이전트가 특히 유용한 상황은 다음과 같다:

문서 작성 - PRD, 기술 설계 문서, API 명세서 등 구조화된 문서를 작성할 때. 문서 작성은 많은 컨텍스트를 소비하는 작업이므로 메인 컨텍스트에서 하면 이후 작업에 영향을 준다.
코드 분석 - 대규모 코드베이스의 아키텍처를 분석하거나, 복잡한 버그의 원인을 추적할 때. 수십 개의 파일을 읽어야 하는 작업은 서브에이전트에게 맡기는 것이 효율적이다.
반복 패턴 작업 - 여러 컴포넌트에 동일한 패턴을 적용하거나, 일괄 리팩토링을 수행할 때.
검증 작업 - 작성된 문서나 코드의 기술적 정확성을 별도로 검증할 때.

2. 서브에이전트 생성 방법

기본 구조

서브에이전트는 .claude/agents/ 디렉토리에 마크다운 파일로 정의한다. 각 마크다운 파일이 하나의 서브에이전트가 된다. 파일 내에 역할, 규칙, 출력 형식 등을 프롬프트 엔지니어링 기법으로 작성한다.

프로젝트 루트/
  .claude/
    agents/
      prd-generator.md       # PRD 생성 전문가
      prd-validator.md       # PRD 검증 전문가
      startup-cleaner.md     # 프로젝트 초기화 전문가
      nextjs-developer.md    # Next.js 개발 전문가

/agent 명령어로 생성하기

서브에이전트를 만드는 가장 간단한 방법은 Claude Code 대화 안에서 /agent 명령어를 사용하는 것이다.

/agent

이 명령어를 실행하면 Claude Code가 대화형으로 에이전트의 이름, 역할, 규칙을 물어보고, .claude/agents/ 디렉토리에 마크다운 파일을 자동 생성한다.

직접 마크다운 파일을 작성해도 된다. 중요한 것은 파일 안에 역할 정의, 행동 규칙, 출력 형식을 명확하게 기술하는 것이다.

서브에이전트 마크다운 파일 구조

서브에이전트 파일은 일반적으로 다음과 같은 구조를 따른다:

markdown

# 에이전트 이름

## 역할
이 에이전트가 무엇을 하는지 명확하게 정의한다.

## 규칙
- 반드시 지켜야 할 원칙들
- 하지 말아야 할 행동들
- 출력 형식 제약 조건들

## 작업 절차
1. 첫 번째 단계
2. 두 번째 단계
3. ...

## 출력 형식
최종 결과물의 형식을 정의한다.

핵심은 구체적이고 명확한 지시다. "좋은 문서를 작성해라"보다 "아래 표 형식에 맞추어 각 기능의 ID, 설명, 우선순위를 포함한 문서를 작성해라"가 훨씬 좋은 결과를 낸다.

3. 서브에이전트 실전 예시

전체 에이전트 파이프라인

실제 프로젝트에서는 여러 서브에이전트를 파이프라인처럼 연결하여 사용한다. 아래 다이어그램은 제품 개발 과정에서 각 서브에이전트가 어떤 역할을 맡는지 보여준다.

PRD Generator (제품 요구사항 문서 생성 전문가)

PRD Generator는 사용자의 아이디어를 체계적인 제품 요구사항 문서로 변환하는 서브에이전트다.

.claude/agents/prd-generator.md 예시:

markdown

# PRD Generator

## 역할
제품 요구사항 문서(PRD)를 체계적으로 작성하는 전문가다.
사용자의 아이디어를 분석하여 구조화된 PRD를 생성한다.

## 규칙
- 모든 기능에 고유 ID를 부여한다 (예: F-001, F-002)
- ID를 통해 기능 누락을 방지한다
- 사용자가 언급하지 않은 기능을 임의로 추가하지 않는다 (환각 방지)
- 기술적으로 불가능한 기능을 약속하지 않는다
- 각 기능의 우선순위를 P0(필수) ~ P3(희망)으로 분류한다

## 작업 절차
1. 프로젝트 배경과 목적을 정리한다
2. 타겟 사용자를 정의한다
3. 사용자 여정(User Journey)을 단계별로 기술한다
4. 핵심 기능을 표 형식으로 정리한다
5. 비기능 요구사항(성능, 보안 등)을 추가한다

## 출력 형식

### 프로젝트 배경
[프로젝트의 목적과 배경]

### 타겟 사용자
[사용자 정의와 페르소나]

### 사용자 여정
| 단계 | 행동 | 화면 | 비고 |
|------|------|------|------|

### 핵심 기능 명세
| ID | 기능명 | 설명 | 우선순위 | 담당 |
|----|--------|------|----------|------|
| F-001 | | | P0 | |

### 비기능 요구사항
| 항목 | 기준 | 측정 방법 |
|------|------|-----------|

핵심 포인트:

ID 부여 규칙 - 모든 기능에 F-001 같은 고유 ID를 부여한다. 이렇게 하면 개발 과정에서 "F-003 기능 구현 완료"처럼 추적이 가능하고, 빠진 기능이 없는지 확인할 수 있다.
환각 방지 규칙 - "사용자가 언급하지 않은 기능을 임의로 추가하지 않는다"라는 명시적 규칙이 있다. LLM은 도움이 되려는 경향 때문에 요청하지 않은 기능을 추가하는 경우가 있다. 이를 규칙으로 방지한다.
표 형식 강제 - 출력 형식을 표로 고정하면 일관성 있는 문서가 생성된다.

PRD Validator (PRD 검증 전문가)

PRD Validator는 작성된 PRD의 기술적 실현 가능성을 검증하는 서브에이전트다. PRD Generator가 문서를 작성한 후, Validator가 해당 문서를 받아서 검증한다.

.claude/agents/prd-validator.md 예시:

markdown

# PRD Validator

## 역할
작성된 PRD 문서의 기술적 실현 가능성을 검증한다.
실제 프로젝트 코드를 분석하여 PRD의 각 기능이 구현 가능한지 확인한다.

## 핵심 원칙
- API 기능을 추측하지 않는다. 실제 코드와 문서에서 확인된 것만 기준으로 삼는다.
- 외부 서비스 연동이 필요한 기능은 해당 서비스의 API 문서를 반드시 확인한다.
- "아마 가능할 것이다"는 판단을 하지 않는다. 확실하지 않으면 "검증 필요"로 표시한다.

## 검증 항목
1. 각 기능의 기술적 구현 가능성
2. 기존 코드베이스와의 호환성
3. 필요한 외부 의존성
4. 예상 구현 난이도
5. 잠재적 기술 부채

## 출력 형식
| ID | 기능명 | 검증 결과 | 위험도 | 비고 |
|----|--------|-----------|--------|------|

핵심 포인트:

"추측하지 않는다" - 이것이 Validator의 가장 중요한 원칙이다. Generator가 작성한 기능이 실제로 가능한지를 코드 기반으로 확인한다. API 기능을 추측하면 나중에 구현 불가능한 기능이 PRD에 남게 된다.
위험도 분류 - 각 기능의 위험도를 표시하여, 어떤 기능부터 프로토타입을 만들어야 하는지 우선순위를 잡을 수 있다.

Startup Cleaner (프로젝트 초기화 전문가)

Startup Cleaner는 Starter Kit이나 템플릿 프로젝트를 깨끗하게 초기화하는 서브에이전트다. 새 프로젝트를 시작할 때 기존 템플릿의 예제 코드, 더미 데이터, 불필요한 설정을 제거하고 빈 상태로 만든다.

.claude/agents/startup-cleaner.md 예시:

markdown

# Startup Cleaner

## 역할
Starter Kit 템플릿 프로젝트를 깨끗하게 초기화한다.
예제 코드, 더미 데이터, 불필요한 설정을 제거하고
새 프로젝트를 시작할 수 있는 깨끗한 상태를 만든다.

## 작업 절차 (Chain of Thought)

아래 단계를 순서대로 따라 진행한다. 각 단계를 완료한 후 다음 단계로 넘어간다.

### 1단계: 현재 상태 분석
- 프로젝트 구조를 파악한다
- 어떤 Starter Kit/템플릿인지 확인한다
- 예제 코드와 실제 설정 코드를 구분한다

### 2단계: 제거 대상 식별
- 예제 컴포넌트, 페이지
- 더미 데이터, 목업 API
- 예제 테스트 파일
- 사용하지 않는 의존성

### 3단계: 핵심 보존 대상 확인
- 빌드 설정 (next.config.js, tsconfig.json 등)
- 패키지 매니저 설정 (package.json의 scripts)
- 린트/포맷터 설정
- 환경 변수 템플릿 (.env.example)

### 4단계: 초기화 실행
- 제거 대상을 삭제한다
- 빈 페이지/컴포넌트로 교체한다
- 의존성을 정리한다 (불필요한 패키지 제거)
- 빌드가 통과하는지 확인한다

## 규칙
- 반드시 빌드 성공을 확인한 후 작업을 완료한다
- git 히스토리는 건드리지 않는다
- .env 파일은 삭제하지 않는다 (민감 정보 포함 가능)

핵심 포인트:

Chain of Thought (COT) 프롬프트 엔지니어링 - 작업 절차를 명시적인 단계로 나누어 지시한다. LLM에게 "생각의 연쇄"를 강제하면, 단계를 건너뛰거나 중요한 확인을 빠뜨리는 것을 방지할 수 있다. "분석 -> 식별 -> 확인 -> 실행" 순서를 따르도록 하면 예제 코드를 지우면서 설정 파일까지 지우는 실수를 방지한다.
빌드 확인 강제 - 마지막에 빌드가 통과하는지 확인하도록 규칙을 넣었다. 초기화 후 빌드가 깨지면 의미가 없다.

Next.js Developer (개발 전문가)

Next.js Developer는 특정 기술 스택에 최적화된 코딩 서브에이전트다.

.claude/agents/nextjs-developer.md 예시:

markdown

# Next.js Developer

## 역할
Next.js App Router 기반 풀스택 개발 전문가다.
PRD에 정의된 기능을 구현한다.

## 기술 스택
- Next.js 15 (App Router)
- TypeScript (strict mode)
- Tailwind CSS
- Prisma ORM
- NextAuth.js

## 코딩 규칙
- Server Component를 기본으로 사용한다
- Client Component는 최소한으로 제한한다 ("use client" 최소화)
- 모든 API 라우트에 입력 유효성 검사를 포함한다 (Zod 사용)
- 에러 처리는 error.tsx와 not-found.tsx를 활용한다
- 데이터 페칭은 Server Action을 우선 사용한다

## 파일 구조 규칙
- app/ 디렉토리에 라우팅 파일만 배치한다
- 비즈니스 로직은 lib/ 디렉토리에 분리한다
- 재사용 컴포넌트는 components/ 디렉토리에 배치한다
- 타입 정의는 types/ 디렉토리에 모은다

## 구현 절차
1. PRD에서 해당 기능의 요구사항을 확인한다
2. 필요한 파일을 생성/수정한다
3. 타입을 먼저 정의한다
4. 서버 로직을 구현한다
5. UI 컴포넌트를 구현한다
6. 에러 처리를 추가한다

핵심 포인트:

기술 스택 명시 - 사용할 프레임워크와 라이브러리를 명확히 지정한다. 이렇게 하면 서브에이전트가 다른 기술을 혼용하는 것을 방지한다.
코딩 규칙 구체화 - "Server Component를 기본으로 사용한다", "Client Component는 최소화한다" 같은 구체적인 규칙이 있어야 일관된 코드가 나온다. 규칙이 없으면 서브에이전트는 매번 다른 패턴으로 코드를 작성할 수 있다.

4. 서브에이전트 사용법

서브에이전트 호출

서브에이전트는 Claude Code 대화 안에서 @agent/에이전트명 형식으로 호출한다.

@agent/prd-generator 사용자 인증 기능에 대한 PRD 문서를 작성해주세요

@agent/ 뒤에 오는 이름은 .claude/agents/ 디렉토리의 마크다운 파일명(확장자 제외)과 일치해야 한다.

.claude/agents/prd-generator.md    →  @agent/prd-generator
.claude/agents/prd-validator.md    →  @agent/prd-validator
.claude/agents/startup-cleaner.md  →  @agent/startup-cleaner
.claude/agents/nextjs-developer.md →  @agent/nextjs-developer

호출 예시

PRD 생성 요청:

@agent/prd-generator
온라인 도서 관리 시스템의 PRD를 작성해주세요.
핵심 기능은 다음과 같습니다:
- 도서 등록 및 검색
- 사용자 대출/반납 관리
- 연체 알림
- 관리자 대시보드

PRD 검증 요청:

@agent/prd-validator
방금 생성된 PRD 문서를 검증해주세요.
특히 외부 API 연동 부분의 기술적 실현 가능성을 중점적으로 확인해주세요.

프로젝트 초기화:

@agent/startup-cleaner
이 Next.js 프로젝트를 초기화해주세요.
create-next-app으로 생성된 기본 예제 코드를 모두 제거해주세요.

기능 구현:

@agent/nextjs-developer
PRD의 F-001(도서 등록) 기능을 구현해주세요.

새 에이전트 인식

.claude/agents/ 디렉토리에 새 마크다운 파일을 추가한 후에는 Claude Code 세션을 종료하고 다시 시작해야 한다. 현재 실행 중인 세션에서는 새로 추가된 에이전트를 인식하지 못한다.

bash

# 세션 종료 후 재시작
exit
claude

서브에이전트 실행 중 기다리기

서브에이전트는 독립 컨텍스트에서 작업하므로, 메인 에이전트는 서브에이전트의 작업이 끝날 때까지 대기한다. 이 대기 시간은 작업의 복잡도에 따라 수초에서 수분까지 걸릴 수 있다. 뒤에서 다룰 Hook 시스템을 활용하면, 서브에이전트 작업이 완료되었을 때 알림을 받을 수 있다.

5. 커스텀 커맨드 (Custom Command)

커스텀 커맨드란?

커스텀 커맨드는 자주 사용하는 프롬프트를 미리 저장해 두는 단축키다. 매번 같은 지시를 타이핑하는 대신, /명령어명 형태로 한 번에 실행한다.

서브에이전트와의 차이를 명확히 이해해야 한다:

항목	서브에이전트	커스텀 커맨드
실행 위치	독립 컨텍스트	메인 컨텍스트
컨텍스트 영향	메인 컨텍스트에 영향 없음	메인 컨텍스트를 사용함
저장 위치	`.claude/agents/`	`.claude/commands/`
호출 방식	`@agent/이름`	`/이름`
용도	복잡한 전문 작업 위임	반복 프롬프트 단축

커스텀 커맨드는 메인 컨텍스트에서 실행되므로, 실행 결과가 현재 대화의 컨텍스트에 쌓인다. 간단한 반복 작업에 적합하고, 컨텍스트를 많이 소비하는 복잡한 작업에는 서브에이전트가 더 적합하다.

커스텀 커맨드 생성

.claude/commands/ 디렉토리에 마크다운 파일을 만든다.

프로젝트 루트/
  .claude/
    commands/
      review.md        # 코드 리뷰 명령어
      test-plan.md     # 테스트 계획 명령어
      commit-msg.md    # 커밋 메시지 생성 명령어
      refactor.md      # 리팩토링 체크리스트

커스텀 커맨드 예시

코드 리뷰 커맨드 (.claude/commands/review.md):

markdown

현재 브랜치에서 변경된 모든 파일을 리뷰해주세요.

## 리뷰 기준
1. 버그 가능성: 논리적 오류, null 처리 누락, 경계값 문제
2. 보안: 인증/인가 누락, 입력 유효성 검사, SQL 인젝션
3. 성능: 불필요한 렌더링, N+1 쿼리, 메모리 누수
4. 코드 품질: 네이밍 일관성, 중복 코드, 테스트 커버리지

## 출력 형식
각 파일에 대해 다음 형식으로 리뷰 결과를 작성해주세요:

### 파일명
- [심각도: 높음/중간/낮음] 이슈 설명
- 수정 제안

사용법:

/review

이렇게 입력하면 review.md의 내용이 프롬프트로 자동 전달된다.

커밋 메시지 생성 커맨드 (.claude/commands/commit-msg.md):

markdown

현재 staged된 변경 사항을 분석하여 커밋 메시지를 작성해주세요.

## 커밋 메시지 규칙
- 제목은 50자 이내, 명령형으로 작성
- 본문은 72자에서 줄바꿈
- 변경 이유(why)를 본문에 포함
- 관련 이슈 번호가 있으면 참조

테스트 계획 커맨드 (.claude/commands/test-plan.md):

markdown

현재 변경된 코드에 대한 테스트 계획을 작성해주세요.

## 포함 항목
1. 단위 테스트 대상 함수/메서드 목록
2. 각 테스트의 입력/기대 출력 정의
3. 엣지 케이스 식별
4. 통합 테스트 시나리오
5. 테스트 우선순위 (필수/권장/선택)

커스텀 커맨드 인자 전달

커스텀 커맨드에 인자를 전달할 수도 있다. 마크다운 파일 안에서 $ARGUMENTS를 사용하면 된다.

markdown

<!-- .claude/commands/explain.md -->
다음 파일을 분석하고 설명해주세요: $ARGUMENTS

## 분석 관점
1. 이 파일의 역할
2. 주요 함수/클래스의 책임
3. 외부 의존성
4. 개선 가능한 부분

사용법:

/explain src/auth/middleware.ts

$ARGUMENTS 자리에 src/auth/middleware.ts가 들어간다.

6. 훅 (Hook) 시스템

훅이란?

훅은 특정 이벤트가 발생했을 때 자동으로 실행되는 스크립트다. Claude Code의 동작 중 특정 시점에 사용자 정의 스크립트를 끼워 넣을 수 있다. 이벤트 기반 자동화의 핵심이다.

훅의 동작 흐름

훅 이벤트 종류

이벤트	발생 시점	주요 용도
PreToolUse	도구가 실행되기 직전	특정 도구 사용을 차단하거나, 실행 전 전처리
PostToolUse	도구 실행이 완료된 직후	실행 결과를 로깅하거나, 후처리 자동화
Notification	Claude Code가 알림을 보낼 때	데스크톱 알림, 사운드 재생
Stop	Claude Code의 턴이 끝날 때	작업 완료 알림, 후속 처리

settings.json에서 훅 설정

훅은 settings.json 파일에서 설정한다. settings.json은 여러 위치에 둘 수 있지만, 프로젝트 단위 설정은 .claude/settings.json에, 사용자 전역 설정은 ~/.claude/settings.json에 배치한다.

기본 구조:

json

{
  "hooks": {
    "이벤트명": [
      {
        "matcher": "매칭 조건 (선택)",
        "command": "실행할 명령어"
      }
    ]
  }
}

훅 실전 예시

1. 작업 완료 시 알림음 재생

서브에이전트에게 복잡한 작업을 위임하면 수분이 걸릴 수 있다. 이 시간에 다른 일을 하다가, 작업이 끝나면 소리로 알려주는 훅이다.

json

{
  "hooks": {
    "Stop": [
      {
        "command": "afplay /System/Library/Sounds/Glass.aiff"
      }
    ]
  }
}

macOS의 afplay 명령어로 시스템 사운드를 재생한다. 서브에이전트 작업이 완료되어 Claude Code의 턴이 끝나면 "딩" 소리가 난다. Linux에서는 paplay, Windows에서는 PowerShell 명령어로 대체한다.

2. Notification 이벤트에 알림 연결

json

{
  "hooks": {
    "Notification": [
      {
        "command": "osascript -e 'display notification \"Claude Code 알림\" with title \"작업 알림\"'"
      }
    ]
  }
}

macOS의 osascript를 사용하여 시스템 알림을 표시한다.

3. 특정 도구 실행 전 로깅

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo \"[$(date)] Bash 명령 실행됨\" >> ~/.claude/tool-log.txt"
      }
    ]
  }
}

Bash 도구가 실행될 때마다 로그 파일에 기록한다. 어떤 명령이 언제 실행되었는지 추적할 수 있다.

4. 파일 수정 후 자동 포맷팅

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ]
  }
}

Write 또는 Edit 도구로 파일이 수정된 후 자동으로 Prettier를 실행하여 코드를 포맷팅한다.

훅 작성 시 주의사항

훅 스크립트는 빠르게 실행되어야 한다. 훅이 느리면 Claude Code 전체 흐름이 지연된다. 무거운 작업은 백그라운드(&)로 실행하거나 별도 스크립트로 분리한다.
에러 처리를 반드시 포함한다. 훅 스크립트가 실패하면 Claude Code의 동작에 영향을 줄 수 있다. || true를 붙여 실패해도 계속 진행되도록 하거나, 적절한 에러 핸들링을 추가한다.
PreToolUse 훅의 차단 기능은 신중하게 사용한다. 잘못된 차단 규칙은 Claude Code가 필요한 도구를 사용하지 못하게 만들 수 있다.

7. 메인 에이전트 vs 서브에이전트 비교

상세 비교

비교 표

항목	메인 에이전트	서브에이전트
컨텍스트	사용자와 공유하는 하나의 컨텍스트	독립된 별도 컨텍스트
속도	빠름 (별도 초기화 불필요)	느림 (새 컨텍스트 생성 및 초기화 필요)
정확도	컨텍스트가 많이 쌓이면 저하 가능	독립적이라 안정적으로 유지
컨텍스트 소비	작업 과정 전체가 컨텍스트에 누적	결과만 메인 컨텍스트에 반환
용도	간단한 질문, 빠른 수정, 일반 작업	복잡한 문서 작성, 대규모 분석, 전문 작업
커스터마이징	CLAUDE.md로 프로젝트 수준 지침	에이전트별 전용 프롬프트와 규칙
호출 방식	직접 대화	`@agent/이름` 형식으로 위임

언제 무엇을 사용할까?

메인 에이전트가 적합한 경우:

간단한 질문: "이 함수의 역할이 뭐야?"
작은 수정: "이 변수명을 camelCase로 바꿔줘"
빠른 확인: "이 테스트가 왜 실패하는지 봐줘"
대화 흐름이 중요한 작업: 여러 단계에 걸쳐 점진적으로 결정하는 작업

서브에이전트가 적합한 경우:

문서 작성: PRD, 기술 설계서, API 명세 등
대규모 분석: 코드베이스 아키텍처 분석, 의존성 감사
반복 패턴 적용: 여러 파일에 동일한 패턴 적용
독립적 검증: 작성된 결과물의 품질 검증
컨텍스트를 많이 사용하는 작업: 수십 개 파일을 읽어야 하는 작업

8. 실전 팁

서브에이전트 운영 팁

1. 서브에이전트는 며칠에 걸쳐 보완한다

서브에이전트의 마크다운 파일은 한 번 작성하고 끝이 아니다. 실제로 사용하면서 부족한 부분, 잘못된 부분, 추가해야 할 규칙을 발견하게 된다. 이런 피드백을 반복적으로 반영하면서 점진적으로 완성도를 높인다.

1일차: 기본 역할과 규칙 정의
2일차: 실제 사용 후 환각 방지 규칙 추가
3일차: 출력 형식 구체화
4일차: 엣지 케이스 대응 규칙 추가
5일차: 불필요한 규칙 제거, 핵심 규칙 강화

2. 메인 컨텍스트보다 서브에이전트가 더 정확한 경우가 많다

메인 에이전트와 오래 대화하면 컨텍스트에 다양한 정보가 쌓인다. 이 상태에서 복잡한 작업을 요청하면, 컨텍스트 안의 여러 정보가 간섭하여 정확도가 떨어질 수 있다. 서브에이전트는 깨끗한 상태에서 시작하므로 해당 작업에만 집중할 수 있어 더 정확한 결과를 낸다.

3. Hook과 서브에이전트를 조합한다

서브에이전트에게 시간이 걸리는 작업을 위임하고, Hook으로 완료 알림을 설정한다. 대기하는 동안 다른 작업을 하거나 휴식을 취하고, 알림이 오면 결과를 확인한다.

json

{
  "hooks": {
    "Stop": [
      {
        "command": "afplay /System/Library/Sounds/Hero.aiff"
      }
    ]
  }
}

4. 에이전트 파이프라인을 설계한다

하나의 큰 작업을 여러 서브에이전트로 나누어 처리한다.

사용자: @agent/prd-generator 도서 관리 시스템 PRD 작성해줘
       → (PRD 문서 생성)

사용자: @agent/prd-validator 방금 만든 PRD를 검증해줘
       → (기술적 검증 및 피드백)

사용자: @agent/startup-cleaner Next.js 템플릿을 초기화해줘
       → (깨끗한 프로젝트 준비)

사용자: @agent/nextjs-developer PRD의 F-001 기능을 구현해줘
       → (기능 구현)

각 서브에이전트가 자기 전문 분야에만 집중하므로, 전체적으로 더 높은 품질의 결과물이 나온다.

커스텀 커맨드 운영 팁

1. 팀 공유가 가능하다

.claude/commands/ 디렉토리를 git에 커밋하면, 팀 전체가 동일한 커스텀 커맨드를 사용할 수 있다. 코드 리뷰 기준, 커밋 메시지 규칙 등을 팀 차원에서 통일할 수 있다.

2. 작은 단위로 만든다

하나의 커스텀 커맨드에 너무 많은 기능을 넣지 않는다. /review는 코드 리뷰만, /test-plan은 테스트 계획만, /commit-msg는 커밋 메시지만 담당하도록 역할을 분리한다.

훅 운영 팁

1. 개발 환경에 맞는 알림을 설정한다

운영체제	알림음 명령어	데스크톱 알림 명령어
macOS	`afplay /System/Library/Sounds/Glass.aiff`	`osascript -e 'display notification "..." with title "..."'`
Linux	`paplay /usr/share/sounds/...`	`notify-send "제목" "내용"`
WSL/Windows	`powershell.exe [console]::beep(800,200)`	`powershell.exe -c "New-BurntToastNotification ..."`

2. 훅은 가볍게 유지한다

훅 스크립트가 무거우면 Claude Code의 전체 응답 속도에 영향을 준다. 알림음 재생이나 간단한 로깅 정도가 적절하다. 복잡한 처리가 필요하면 별도 스크립트 파일로 분리하고 백그라운드로 실행한다.

json

{
  "hooks": {
    "Stop": [
      {
        "command": "/path/to/my-notification-script.sh &"
      }
    ]
  }
}

9. 전체 생태계 정리

서브에이전트, 커스텀 커맨드, 훅은 각각 독립적인 기능이지만, 조합하면 강력한 자동화 워크플로우를 구축할 수 있다.

핵심 정리

개념	저장 위치	호출 방식	실행 컨텍스트	핵심 용도
서브에이전트	`.claude/agents/*.md`	`@agent/이름`	독립 컨텍스트	전문 작업 위임, 컨텍스트 보호
커스텀 커맨드	`.claude/commands/*.md`	`/이름`	메인 컨텍스트	반복 프롬프트 단축
훅	`settings.json`	이벤트 기반 자동 실행	스크립트 환경	자동화, 알림, 전후 처리

이 세 가지를 조합하면

커스텀 커맨드 (/review)로 코드 리뷰를 빠르게 시작한다.
리뷰 결과에서 복잡한 리팩토링이 필요하면 서브에이전트 (@agent/refactorer)에게 위임한다.
서브에이전트 작업이 완료되면 훅이 알림음을 재생하여 사용자에게 알린다.
사용자는 결과를 확인하고, 다시 /review로 변경 사항을 검증한다.

이 사이클이 자연스러워지면, Claude Code가 단순한 도구가 아니라 개발 프로세스 전체를 자동화하는 시스템이 된다.

다음 챕터(09. 개발 워크플로우)에서는 PRD 작성부터 배포까지의 전체 개발 프로세스를 Claude Code로 어떻게 진행하는지 체계적으로 다룬다.

08. 서브에이전트, 커스텀 커맨드, 훅 ​

1. 서브에이전트 (Sub Agent) 개요 ​

서브에이전트란? ​

메인 에이전트와 서브에이전트의 동작 흐름 ​

서브에이전트의 핵심 특성 ​

서브에이전트를 사용해야 하는 상황 ​

2. 서브에이전트 생성 방법 ​

기본 구조 ​

/agent 명령어로 생성하기 ​

서브에이전트 마크다운 파일 구조 ​

3. 서브에이전트 실전 예시 ​

전체 에이전트 파이프라인 ​

PRD Generator (제품 요구사항 문서 생성 전문가) ​

PRD Validator (PRD 검증 전문가) ​

Startup Cleaner (프로젝트 초기화 전문가) ​

Next.js Developer (개발 전문가) ​

4. 서브에이전트 사용법 ​

서브에이전트 호출 ​

호출 예시 ​

새 에이전트 인식 ​

서브에이전트 실행 중 기다리기 ​

5. 커스텀 커맨드 (Custom Command) ​

커스텀 커맨드란? ​

커스텀 커맨드 생성 ​

커스텀 커맨드 예시 ​

커스텀 커맨드 인자 전달 ​

6. 훅 (Hook) 시스템 ​

훅이란? ​

훅의 동작 흐름 ​

훅 이벤트 종류 ​

settings.json에서 훅 설정 ​

훅 실전 예시 ​

훅 작성 시 주의사항 ​

7. 메인 에이전트 vs 서브에이전트 비교 ​

상세 비교 ​

비교 표 ​

언제 무엇을 사용할까? ​

8. 실전 팁 ​

서브에이전트 운영 팁 ​

커스텀 커맨드 운영 팁 ​

훅 운영 팁 ​

9. 전체 생태계 정리 ​

핵심 정리 ​

이 세 가지를 조합하면 ​

08. 서브에이전트, 커스텀 커맨드, 훅

1. 서브에이전트 (Sub Agent) 개요

서브에이전트란?

메인 에이전트와 서브에이전트의 동작 흐름

서브에이전트의 핵심 특성

서브에이전트를 사용해야 하는 상황

2. 서브에이전트 생성 방법

기본 구조

/agent 명령어로 생성하기

서브에이전트 마크다운 파일 구조

3. 서브에이전트 실전 예시

전체 에이전트 파이프라인

PRD Generator (제품 요구사항 문서 생성 전문가)

PRD Validator (PRD 검증 전문가)

Startup Cleaner (프로젝트 초기화 전문가)

Next.js Developer (개발 전문가)

4. 서브에이전트 사용법

서브에이전트 호출

호출 예시

새 에이전트 인식

서브에이전트 실행 중 기다리기

5. 커스텀 커맨드 (Custom Command)

커스텀 커맨드란?

커스텀 커맨드 생성

커스텀 커맨드 예시

커스텀 커맨드 인자 전달

6. 훅 (Hook) 시스템

훅이란?

훅의 동작 흐름

훅 이벤트 종류

settings.json에서 훅 설정

훅 실전 예시

훅 작성 시 주의사항

7. 메인 에이전트 vs 서브에이전트 비교

상세 비교

비교 표

언제 무엇을 사용할까?

8. 실전 팁

서브에이전트 운영 팁

커스텀 커맨드 운영 팁

훅 운영 팁

9. 전체 생태계 정리

핵심 정리

이 세 가지를 조합하면