하네스 엔지니어링 Vol.2 — 서브에이전트로 역할 분리하기

01 — 지난 이야기

Vol.1 리캡:
행동을 제한하다

1편에서는 Hook으로 "뭘 할 수 있는지"를 제어했습니다.
2편에서는 서브에이전트로 "누가 하는지"를 제어합니다.

📋

Vol.1 — Hook

행동 제한

outline.md 없이 draft.md를 작성하면 exit 2로 물리적 차단. "뭘 할 수 있는지"를 강제한다.

비유: 출입문에 카드키 — 자격 없으면 문이 안 열린다

🎭

Vol.2 — 서브에이전트

역할 분리

researcher는 검색만, creator는 작성만, editor는 수정만. tools 필드가 역할을 강제한다.

비유: 조직도에 직무 기술서 — 담당 업무 외 권한이 없다

← Vol.1 교육자료 보기

02 — 핵심 개념

세 명의 전문가,
각자의 도구

서브에이전트는 .claude/agents/ 폴더에 마크다운 파일 하나로 정의합니다. YAML frontmatter의 tools 필드가 그 에이전트의 권한 범위를 결정하거든요.

🔍

researcher

WebSearch, WebFetch, Read, Grep
Write ✕ Edit ✕
검색은 하되, 파일은 못 건드린다

✍️

creator

Read, Write
WebSearch ✕ Edit ✕
전달받은 자료만으로 초고를 작성한다

🔴

editor

Read, Edit
Write ✕ WebSearch ✕
기존 파일만 수정한다, 새 파일 생성 불가

핵심: 각 서브에이전트는 자기 도구 밖의 행동을 할 수 없다. 프롬프트가 아니라 tools 필드가 강제한다.

03 — Level 1

tools 제한으로
역할을 고정하기

.claude/agents/ 폴더에 마크다운 파일 3개를 만드는 것만으로 역할 분리가 완성됩니다.

Level 1 — tools only

시나리오: 블로그 글 제작 파이프라인

"가성비 미니PC TOP 5 추천" 블로그 글을 3명의 전문가가 분업합니다.

.claude/agents/
  researcher.md ← 조사 전담 (WebSearch, Read)
  creator.md ← 작성 전담 (Read, Write)
  editor.md ← 교정 전담 (Read, Edit)

.claude/agents/researcher.md
---
name: researcher
description: 주제에 대한 정보를 웹에서 조사하고 정리하는 리서치 전담 에이전트.
tools: Read, Grep, Glob, WebSearch, WebFetch
model: haiku
---

주어진 주제에 대해 웹 검색과 자료 분석을 수행한다.
조사 결과를 구조화된 마크다운으로 정리하여 반환한다.
파일을 직접 생성하거나 수정하지 않는다.

.claude/agents/creator.md
---
name: creator
description: 리서치 결과를 바탕으로 블로그 글 초고를 작성하는 에이전트.
tools: Read, Write
model: sonnet
---

전달받은 조사 자료를 바탕으로 블로그 글 초고를 작성한다.
웹 검색을 하지 않는다 — 전달받은 자료만 사용한다.
자연스러운 구어체로 작성한다.

.claude/agents/editor.md
---
name: editor
description: 작성된 초고의 문체, 맞춤법, 팩트를 검수하는 편집 에이전트.
tools: Read, Edit
model: sonnet
---

초고를 읽고 문체 일관성, 맞춤법, 논리적 흐름을 검수한다.
Edit 도구로 기존 파일만 수정한다. 새 파일을 만들지 않는다.

04 — 실습

실제로 돌려보면
이렇게 흘러갑니다

"가성비 미니PC TOP 5 추천 블로그 글 써줘"라고 요청하면, Claude가 자동으로 세 서브에이전트에 순서대로 위임합니다.

Claude Code — 서브에이전트 오케스트레이션

👤

가성비 미니PC TOP 5 추천 블로그 글 써줘

researcher에게 위임합니다 — 최신 미니PC 정보를 조사합니다.

── researcher 서브에이전트 ──

🔍

WebSearch "2026 가성비 미니PC 추천"
WebFetch 상세 스펙 페이지 분석
→ 5개 모델 스펙/가격 비교표 정리 완료

── creator 서브에이전트 ──

✍️

조사 자료 기반 초고 작성 중...
Write → mini-pc-top5.md 생성
⚠️ WebSearch 시도? → 도구 없음!

── editor 서브에이전트 ──

🔴

Read → 초고 검토
"~합니다" 반복 → Edit으로 구어체 수정
⚠️ Write 새 파일 생성? → 도구 없음!

── 완료 ──

✅ 블로그 글 완성. 3명의 전문가가 분업하여 mini-pc-top5.md를 제작했습니다.

주목할 점: creator가 WebSearch를 시도하려 해도 도구 자체가 없어서 실행이 불가능합니다. "검색하지 마"라고 프롬프트에 적는 것과는 차원이 다른 거죠 — tools 필드가 물리적으로 막고 있거든요.

05 — Level 2

하네스는
레이어링된다

tools 제한만으로도 강력하지만, model과 hooks를 추가하면 더 정교한 하네스를 만들 수 있습니다. Vol.1의 Hook이 서브에이전트 안에서 다시 등장하는 거죠.

Level 2 — tools + model + hooks Level 1 vs Level 2 비교 인포그래픽

제어 축	Level 1	Level 2
`tools`	✅ 역할별 도구 제한	✅ 동일
`model`	❌ 전부 동일 모델	✅ haiku / sonnet 차등
`hooks`	❌ 없음	✅ editor에 윤문 hook

Level 2의 editor는 이렇게 진화합니다:

.claude/agents/editor.md — Level 2
---
name: editor
description: 초고의 문체, 맞춤법, 팩트를 검수하는 편집 에이전트.
tools: Read, Edit
model: sonnet
hooks:
  PostToolUse:
    - matcher: "Edit"
      hooks:
        - type: prompt
          prompt: |
            방금 수정된 내용을 검토하라.
            1. "~합니다/~됩니다"만 반복하지 않는가
            2. 콜론(:) 뒤에 바로 불릿 목록이 오지 않는가
            3. 자연스러운 구어체가 유지되는가
            기준 미달 시 'deny'를 반환하라.
---

초고를 읽고 문체 일관성, 맞춤법, 논리적 흐름을 검수한다.
Edit 도구로 기존 파일만 수정한다.

💰

Model 차등

비용 최적화

researcher는 haiku(빠르고 저렴)로 대량 검색, creator와 editor는 sonnet(고품질)으로 글 작성. 역할에 맞는 모델을 매칭하면 비용과 품질을 동시에 잡을 수 있어요.

🔗

Vol.1 × Vol.2

Hook + 서브에이전트

editor 안에 PostToolUse hook을 걸면, 매 수정마다 윤문 품질을 자동 검증합니다. Vol.1의 행동 제한이 Vol.2의 역할 분리 안에서 다시 작동하는 거죠.

06 — 아키텍처

오케스트레이션
전체 흐름

사용자의 요청은 오케스트레이터(메인 에이전트)를 거쳐 세 서브에이전트로 순서대로 위임됩니다.

사용자 요청

"미니PC 추천 블로그 글 써줘"

오케스트레이터

Claude 메인 에이전트

🔍 researcher (haiku)

WebSearch → 스펙/가격 조사

✍️ creator (sonnet)

Read → Write 초고 생성

🔴 editor (sonnet) + hook

Read → Edit 교정

hook 실패

⛔ editor 재수정

hook 통과

✅ 최종 완성

07 — 마무리

핵심 정리

하네스는 레이어링된다

Vol.1에서 Hook으로 행동을 제한하고, Vol.2에서 서브에이전트로 역할을 분리했습니다. 이 둘을 조합하면 — 누가, 무엇을, 어떻게 하는지를 모두 인프라 수준에서 강제하는 완성형 하네스가 됩니다.

역할 분리 (서브에이전트) + 행동 제한 (Hook) = 프로덕션 하네스

서브에이전트 설정 파일은 .claude/agents/ 폴더에 저장됩니다.
자세한 문법은 공식 문서를 참고하세요.

Vol.1 리캡:행동을 제한하다