👉 인터랙티브 교육자료 보기 — 풀 디자인 버전

하네스 엔지니어링 Vol.2 — 역할을 나누면, 품질이 달라진다

프롬프트 한 줄로 "리서처 해줘"가 아니라, 인프라로 역할을 고정하는 서브에이전트 하네스.

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

1편에서는 Hook으로 "뭘 할 수 있는지"를 제어했거든요. outline.md 없이 draft.md를 작성하려 하면 exit 2로 물리적으로 차단하는 식이었죠.

2편에서는 한 단계 더 나아가서, **"누가 하는지"**를 제어합니다.

Soft (프롬프트) vs Hard (하네스)

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개를 만드는 것만으로 역할 분리가 완성돼요.

시나리오: "가성비 미니PC TOP 5 추천" 블로그 글

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

researcher.md

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

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

creator.md

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

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

editor.md

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

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

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

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

👤 사용자: 가성비 미니PC TOP 5 추천 블로그 글 써줘

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

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

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

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

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

주목할 점은 creator가 WebSearch를 시도하려 해도 도구 자체가 없어서 실행이 불가능하다는 거예요. "검색하지 마"라고 프롬프트에 적는 것과는 차원이 다르죠.

05 — Level 2: 하네스는 레이어링된다

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

Level 2 editor.md

---
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 — 오케스트레이션 전체 흐름

1. 사용자 요청: "미니PC 추천 블로그 글 써줘"
2. 오케스트레이터 (Claude 메인 에이전트)
3. → 🔍 researcher (haiku): WebSearch → 스펙/가격 조사
4. → ✍️ creator (sonnet): Read → Write 초고 생성
5. → 🔴 editor (sonnet + hook): Read → Edit 교정
   • Hook 통과 → ✅ 최종 완성
   • Hook 실패 → ⛔ editor 재수정

07 — 핵심 정리: 하네스는 레이어링된다

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

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

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