클로드 코드 서브에이전트 완전정복 (총 9편) | 8편 구현 가이드 — 서브에이전트 정의 파일, 훅, 체크포인트 실전 설정

시리즈: 클로드 코드 서브에이전트 완전정복 (총 9편) | 8편

구현 가이드 — 서브에이전트 정의 파일, 훅, 체크포인트 실전 설정

서브에이전트 개념은 이해했는데 막상 정의 파일은 어떻게 만들고, 훅은 어디에 걸고, 체크포인트는 어떻게 설정하는지 감이 안 잡히시죠. frontmatter 기반 역할 선언부터 I/O 계약, 로깅과 차단과 승인 훅, 복원 장치까지 실전 구현을 단계별로 안내해 드려요.

Summary

• 서브에이전트 정의 파일은 frontmatter 기반 마크다운으로, 역할을 코드처럼 버전 관리할 수 있어요
• I/O 계약을 통해 서브에이전트의 입력과 출력 형식을 표준화하면 자동 검증이 가능해져요
• 훅(Hooks)의 3대 용도는 로깅, 차단, 승인 연동이에요
• 체크포인트는 변경 전후 상태를 복원할 수 있게 해서 높은 자율성 운영의 리스크를 줄여줘요

이 글의 대상

• 서브에이전트를 직접 구현하려는 개발자
• 기존 서브에이전트 설정을 체계적으로 정리하고 싶은 실무자
• 훅과 체크포인트로 안전한 운영 환경을 만들고 싶은 팀

목차

• 구현의 세 축: 정의 파일, 훅, 체크포인트
• 서브에이전트 정의 파일 작성법
• I/O 계약 — 입력과 출력의 표준화
• 훅(Hooks)의 3대 용도
• 체크포인트 — 안전한 복원 장치
• 구현 체크리스트
• 핵심 정리
• FAQ
• 참고 자료 (References)
• 다음 편 예고

---

구현의 세 축: 정의 파일, 훅, 체크포인트

한 줄 요약: 서브에이전트 구현은 "역할 정의 → 자동화/안전장치 → 복원 체계" 세 단계로 이루어져요.

서브에이전트를 실제로 운영하려면 세 가지가 필요해요.

구성 요소	역할	비유
정의 파일	에이전트의 역할, 권한, 도구를 선언	채용 공고 + 업무 매뉴얼
훅(Hooks)	도구 호출 전후에 자동 실행되는 스크립트	사무실 출입 카드 + CCTV
체크포인트	변경 전 상태를 저장하고 복원하는 장치	게임의 세이브 포인트

이 세 가지가 맞물려야 "역할이 명확하고, 자동으로 통제되며, 문제 시 되돌릴 수 있는" 안전한 서브에이전트 운영이 가능해요.

---

서브에이전트 정의 파일 작성법

한 줄 요약: frontmatter(YAML 헤더)로 메타데이터를 선언하고, 본문에 시스템 프롬프트를 작성하는 마크다운 파일이에요.

정의 파일의 핵심은 "역할을 코드처럼 관리한다"는 거예요. Git에 넣어서 버전 관리하고, PR로 리뷰하고, 변경 이력을 추적할 수 있어요.

표준 구조

---
name: evidence-verifier
description: "초안의 사실 주장을 검증하는 역할"
model: sonnet
tools: Read, Web, Grep, Glob, Task
permissionMode: default
maxTurns: 8
memory: project
---

You are an evidence verifier. For each factual claim in the draft:
1. Locate the original source
2. Verify the claim matches the source
3. Flag any unsupported claims

Output JSON:
{
  "issues": [
    {
      "claim": "검증 대상 주장",
      "location": "문서 내 위치",
      "severity": "high|medium|low",
      "evidence_required": "필요한 근거",
      "suggested_fix": "수정 제안"
    }
  ],
  "pass": true/false
}

frontmatter 필드 설명

필드	필수	설명
name	O	에이전트 식별자 (영문 소문자, 하이픈 사용)
description	O	역할 요약 (한 줄)
model	-	사용할 모델 (haiku, sonnet, opus 등). 기본값은 프로젝트 설정 따름
tools	O	이 에이전트가 쓸 수 있는 도구 목록
permissionMode	-	권한 수준 (default, strict 등)
maxTurns	-	최대 실행 턴 수 (무한 루프 방지)
memory	-	메모리 범위 (project, session 등)

역할별 정의 파일 예시

팀에서 자주 쓰는 역할 세 가지를 정리해 볼게요.

역할	model	tools	maxTurns	핵심 규칙
Researcher	haiku	Web, Grep, Read	12	URL + 인용 스니펫 필수
Writer	sonnet	Read, Write, Glob	10	출처 없는 주장 금지
Verifier	sonnet	Read, Web, Grep	8	JSON으로 검증 결과 출력

Researcher는 탐색 범위가 넓으니 턴을 넉넉히 주되, 저비용 모델(Haiku)을 쓰는 거예요. Writer는 품질이 중요하니 Sonnet을, Verifier는 정확한 판단이 필요하니 역시 Sonnet을 쓰는 거죠. 이게 7편에서 말한 모델 라우팅이에요.

---

I/O 계약 — 입력과 출력의 표준화

한 줄 요약: 서브에이전트의 1차 출력은 JSON으로 받고, 메인 에이전트가 마크다운 등 최종 포맷으로 변환하는 구조가 안전해요.

서브에이전트가 자유 형식으로 출력하면 후처리가 어려워요. 그래서 I/O 계약을 정해두는 거예요.

흐름

서브에이전트 → JSON 출력 → 메인 에이전트 → 마크다운 렌더링 → 자동 검사

자동 검사 항목

서브에이전트의 JSON 출력을 받은 후, 메인 에이전트(또는 검사 스크립트)가 자동으로 확인하는 항목이에요.

검사 항목	설명	실패 시 조치
스키마 검증	JSON이 정해진 형식을 따르는지	재생성 요청
링크 유효성	URL이 200 응답을 반환하는지	링크 수정 또는 제거
필수 섹션	요구한 모든 섹션이 포함됐는지	누락 섹션 보완 요청
인용 매칭	claim에 대응하는 evidence가 있는지	출처 보강 요청

이렇게 하면 "사람이 일일이 눈으로 확인"하는 부담을 크게 줄일 수 있어요. 물론 최종 검토는 사람이 하는 게 안전하지만, 기계적인 검증은 자동화하는 거죠.

---

훅(Hooks)의 3대 용도

한 줄 요약: 훅은 로깅, 차단, 승인 연동 세 가지 목적으로 쓰이며, 에이전트의 행동을 자동으로 통제하는 핵심 장치예요.

훅은 Claude Code에서 특정 이벤트(도구 호출 전후, 작업 완료 등)에 자동으로 실행되는 스크립트예요. 서브에이전트와 함께 쓰면 아주 강력한 안전장치가 돼요.

용도 1: 로깅

목적: 모든 도구 호출, URL 접근, 산출물 체크섬, 토큰 소비를 기록해요.

기록해야 할 핵심 필드:

trace_id    → 실행 전체를 추적하는 고유 ID
agent_id    → 어떤 서브에이전트가 실행했는지
tool_name   → 어떤 도구를 호출했는지
input       → 도구에 전달한 입력
output_hash → 산출물의 체크섬 (변조 감지용)
tokens_used → 이 호출에서 소비한 토큰
timestamp   → 호출 시각

7편에서 말한 "검증/감사 불능" 실패 모드를 예방하는 핵심이 바로 이 로깅 훅이에요.

용도 2: 차단

목적: 허용되지 않은 도구, 도메인, 민감 파일 접근을 사전에 차단해요.

차단 규칙 예시:

차단 대상	규칙	예시
도구 제한	허용목록(allowlist)에 없는 도구 호출 차단	Researcher가 Write 도구 호출 시 차단
도메인 제한	허용된 도메인 외 접근 차단	허용목록 외 URL 차단
파일 보호	민감 경로 접근 차단	.env, credentials.json 접근 차단

용도 3: 승인 연동

목적: 고위험 작업은 사람의 승인 없이 실행하지 못하도록 해요.

PreToolUse 훅을 활용하는 거예요. 에이전트가 고위험 도구(파일 삭제, 외부 API 호출, 배포 관련 등)를 호출하려고 하면, 훅이 먼저 동작해서 승인 요청을 보내요. 승인이 떨어져야만 실제 도구가 실행되죠.

에이전트 → 고위험 도구 호출 시도
  → PreToolUse 훅 동작
    → 승인 요청 발송 (Slack, 이메일 등)
      → 승인 → 도구 실행
      → 거부 → 차단 + 로그 기록

이 세 가지 훅을 조합하면 7편에서 다룬 보안 침범, 비용 폭증, 감사 불능 문제를 상당 부분 자동으로 대응할 수 있어요.

---

체크포인트 — 안전한 복원 장치

한 줄 요약: 체크포인트는 서브에이전트가 변경을 가하기 전 상태를 저장해서, 문제가 생겼을 때 되돌릴 수 있게 해주는 장치예요.

서브에이전트에게 높은 자율성을 줄수록 리스크도 커져요. 코드를 대량으로 수정하거나, 문서를 재작성하거나, 설정을 변경할 때 "원래대로 돌릴 수 있는지"가 핵심이에요.

체크포인트가 필요한 상황

상황	위험	체크포인트 효과
코드 대량 수정	빌드 깨짐, 테스트 실패	수정 전 상태로 복원
문서 재작성	기존 내용 유실	이전 버전 복원
설정 변경	서비스 장애	변경 전 설정 복원
병렬 에이전트 충돌	파일 덮어쓰기	충돌 전 상태로 복원

운영 팁

• 자동 체크포인트: 서브에이전트 실행 시작 시 자동으로 현재 상태를 저장
• 수동 체크포인트: 중요한 중간 단계에서 명시적으로 저장
• 보관 주기: 최근 N회 체크포인트만 유지하고, 오래된 건 정리

체크포인트가 있으면 서브에이전트에게 좀 더 과감한 작업을 맡길 수 있어요. "실패해도 되돌릴 수 있다"는 안전망이 있으니까요.

---

구현 체크리스트

한 줄 요약: 서브에이전트를 처음 구현할 때 이 체크리스트를 따라가면 빠짐없이 설정할 수 있어요.

□ 1. 역할 정의 파일 작성 (name, description, model, tools, maxTurns)
□ 2. 시스템 프롬프트에 출력 포맷(JSON 스키마) 명시
□ 3. I/O 계약 정의 (입력 형식, 출력 스키마, 자동 검사 항목)
□ 4. 로깅 훅 설정 (trace_id, agent_id, tool_calls, tokens)
□ 5. 차단 훅 설정 (도구 allowlist, 도메인 제한, 민감 파일 보호)
□ 6. 고위험 도구에 승인 훅 연동
□ 7. 체크포인트 자동 생성 설정
□ 8. 테스트 실행 후 로그 확인
□ 9. 정의 파일을 Git에 커밋 (버전 관리 시작)

처음부터 완벽하게 할 필요 없어요. 13번(정의 파일 + I/O 계약)부터 시작하고, 운영하면서 49번을 점진적으로 추가하는 게 현실적이에요.

---

핵심 정리

1. 서브에이전트 정의 파일 = frontmatter(메타데이터) + 시스템 프롬프트, Git으로 버전 관리
2. I/O 계약: 1차 출력은 JSON → 메인이 렌더링 → 스키마/링크/섹션 자동 검사
3. 훅의 3대 용도: 로깅(추적), 차단(안전), 승인(통제) — 7편의 실패 모드 예방 수단
4. 체크포인트: 변경 전 상태 저장 → 문제 시 복원 → 높은 자율성의 안전망
5. 구현 순서: 정의 파일 → I/O 계약 → 훅 → 체크포인트 → Git 관리

---

FAQ

Q. 정의 파일은 어디에 저장하는 게 좋아요?

A. 프로젝트 루트의 .claude/agents/ 같은 디렉토리에 모아두는 걸 추천해요. Git으로 버전 관리하면 변경 이력도 추적되고, PR 리뷰로 역할 변경을 팀원들이 검토할 수도 있어요.

Q. model 필드를 생략하면 어떻게 돼요?

A. 프로젝트 설정의 기본 모델이 적용돼요. 하지만 역할별로 명시적으로 지정하는 걸 권장해요. 탐색은 Haiku, 판단은 Sonnet처럼 모델 라우팅을 하면 비용 절감 효과가 커요.

Q. maxTurns는 어떤 기준으로 설정해요?

A. 역할의 복잡도에 따라 달라요. 단순 검증(Verifier)은 58턴, 탐색(Researcher)은 1015턴, 복잡한 작성(Writer)은 8~12턴 정도가 적당해요. 처음에는 넉넉하게 잡고, 실제 사용 데이터를 보면서 줄여나가는 게 좋아요.

Q. I/O 계약이 꼭 JSON이어야 하나요?

A. 반드시 JSON일 필요는 없지만, JSON이 자동 검증하기 가장 편해요. 스키마 검증 라이브러리가 풍부하고, 파싱이 쉽고, 다른 시스템과 연동하기도 좋거든요. 마크다운이나 YAML로 출력받을 수도 있지만, 자동 검사의 신뢰성이 떨어져요.

Q. 훅은 직접 스크립트를 작성해야 해요?

A. 네, 현재는 쉘 스크립트나 실행 가능한 프로그램을 직접 작성해야 해요. 하지만 로깅, 차단 같은 기본 패턴은 몇 줄이면 돼요. 커뮤니티에서 공유하는 훅 템플릿도 점점 늘어나고 있어요.

Q. 체크포인트가 Git 커밋과 뭐가 달라요?

A. Git 커밋은 의도적으로 만드는 "완성된 스냅샷"이고, 체크포인트는 에이전트가 작업 중 자동으로 만드는 "임시 복원 지점"이에요. Git은 이력을 남기는 데 초점이고, 체크포인트는 빠른 롤백에 초점이 있어요. 둘 다 쓰는 게 가장 안전해요.

Q. 정의 파일을 변경하면 기존 실행에 영향이 있어요?

A. 이미 실행 중인 서브에이전트에는 영향이 없어요. 다음에 새로 호출할 때부터 변경된 정의 파일이 적용돼요. 그래서 정의 파일을 Git으로 관리하면 "언제 어떤 버전의 역할 정의로 실행됐는지"도 추적할 수 있어요.

Q. 하나의 정의 파일에 여러 역할을 넣어도 돼요?

A. 권장하지 않아요. 한 파일에 한 역할이 원칙이에요. 역할을 분리해야 권한도 분리되고, 모델 라우팅도 가능하고, 문제 발생 시 어떤 역할에서 문제가 생겼는지 바로 알 수 있어요.

---

참고 자료 (References)

데이터 출처

출처	설명	링크
Claude Code 서브에이전트 문서	서브에이전트 정의 파일 구조와 운영 공식 가이드	code.claude.com
Claude Code Hooks	훅 설정, 이벤트 타입, 활용 패턴 공식 가이드	code.claude.com
Anthropic 멀티에이전트 연구 시스템	멀티에이전트 아키텍처 설계와 비용 시사점	anthropic.com
Anthropic 자율 에이전트 블로그	Claude Code 자율 운영 모드와 권한 설정	anthropic.com
CloudZero FinOps for Claude	Claude 기반 에이전트의 비용 최적화 전략	cloudzero.com
IBM Agentic AI Security	에이전틱 AI의 보안 위험과 대응 프레임워크	ibm.com

핵심 인용

"Treating agent roles as versionable configuration — not just prompt text — enables the same review, rollback, and audit workflows teams already use for code."
— Claude Code 서브에이전트 문서 핵심 취지 요약

---

다음 편 예고

[9편] 조직에 서브에이전트 도입하기 — 파일럿에서 거버넌스까지 로드맵

• 2주 파일럿으로 가장 작은 성공을 만드는 방법
• 6~8주에 걸친 표준화와 조직 자산화 전략
• 상시 거버넌스 체계 구축을 위한 3단계 로드맵