시리즈: 클로드 코드 서브에이전트 완전정복 (총 9편) | 5편
리서치·문서화에 서브에이전트 활용하기 — Research→Write→Verify→Approve 패턴
리서치하고 문서를 쓸 때 서브에이전트를 어떻게 나누면 좋을지 막막하신가요? 이 글에서는 생성자와 검증자를 분리해야 하는 이유부터 Research, Write, Verify, Approve 4단계 아키텍처와 실전 하이브리드 패턴까지 차근차근 소개해 드려요.
Summary
- 가장 기본이 되는 원칙은 "생성하는 역할"과 "검증하는 역할"을 분리하는 거예요
- Research → Write → Verify → Approve 4단계가 리서치·문서화의 표준 아키텍처예요
- 비결정적 작업(초안/탐색)은 서브에이전트, 결정적 작업(검증/배포)은 워크플로로 나눠요
- 관측가능성을 위해 run_id/trace_id를 문서에도 남기는 습관을 들여야 해요
이 글의 대상
- 리서치나 문서 작성에 서브에이전트를 적용해 보고 싶은 분
- "한 에이전트한테 다 시키면 안 되나?"라고 고민 중인 분
- 문서화 자동화의 실전 패턴을 배우고 싶은 개발자
목차
- 왜 생성자와 검증자를 분리해야 하는가
- 4단계 아키텍처 상세 해부
- 워크플로가 필요한 이유 — 대화 vs 제어 구조
- 하이브리드 패턴 — 서브에이전트 + 워크플로 조합
- 관측가능성 — 추적 가능한 문서 만들기
- 실전 적용 시나리오
1. 왜 생성자와 검증자를 분리해야 하는가
한 에이전트한테 "리서치하고 문서 써 줘, 그리고 검증도 해 줘"라고 시키면 어떻게 될까요? 자기가 쓴 글을 자기가 검토하는 거예요. 사람도 자기 글의 오류를 잘 못 찾는데, AI도 마찬가지예요.
독립 컨텍스트에서 검증자가 돌아가면 생성자의 맥락에 영향을 받지 않아요. "이건 내가 쓴 거니까 맞을 거야"라는 편향 없이 순수하게 사실과 논리를 점검할 수 있는 거죠.
| 구분 | 단일 에이전트 | 생성/검증 분리 |
|---|---|---|
| 편향 | 자기 확증 편향 발생 | 독립 컨텍스트로 편향 차단 |
| 오류 발견율 | 낮음 | 높음 |
| 디버깅 | 어디서 잘못됐는지 불분명 | 단계별로 추적 가능 |
| 재시도 | 전체 다시 실행 | 실패한 단계만 재시도 |
가장 단순한 구조라도 최소한 "쓰는 쪽"과 "확인하는 쪽"은 분리하는 게 기본이에요.
2. 4단계 아키텍처 상세 해부
리서치·문서화에 최적화된 4단계 아키텍처를 살펴볼게요.
1단계: Researcher / Source Finder
역할: 근거가 될 자료를 수집해요.
- 허용 도구: Read, Grep, Glob, Web (읽기 전용)
- Write 권한은 절대 주지 않아요
- 산출물: 출처 목록 + 핵심 인용 + 요약
읽기 전용으로 제한하는 이유가 있어요. 리서치 단계에서 파일을 수정하면 원본 자료가 오염될 수 있거든요. 순수하게 "찾고 정리하는 것"만 하게 하는 거예요.
2단계: Writer
역할: 수집된 근거를 바탕으로 초안을 작성해요.
- 입력: Researcher가 수집한 출처 목록과 요약
- 허용 도구: Read, Write, Edit
- 산출물: 구조화된 초안 (근거 인용 포함)
Writer가 중요하게 해야 할 건 근거를 인용하는 구조화예요. 그냥 "~라고 한다"가 아니라 "출처 A에 따르면 ~이다"처럼 명확한 출처 표시를 해야 다음 단계에서 검증이 가능하거든요.
3단계: Critic / Verifier
역할: 초안의 사실, 출처, 논리를 독립적으로 검증해요.
- 독립 컨텍스트에서 실행 (Writer의 맥락을 모르는 상태)
- 허용 도구: Read, Task (추가 조사용)
- Write 권한은 주지 않아요
- 공격적 체크리스트로 검증
여기서 "공격적 체크리스트"란 뭐냐면, 검증자한테 "문제가 있다고 가정하고 찾아라"는 방향을 주는 거예요.
검증 체크리스트 예시:
- [ ] 모든 주장에 출처가 있는가?
- [ ] 출처 URL이 실제로 존재하는가?
- [ ] 숫자/통계가 출처와 일치하는가?
- [ ] 논리적 비약이 있는 문장이 있는가?
- [ ] 근거 없이 단정하는 표현이 있는가?4단계: Human 승인
역할: 최종 결재를 사람이 해요.
아무리 자동화해도 마지막 승인은 사람이 하는 게 좋아요. 특히 외부에 공개되는 문서, 법적 효력이 있는 문서, 조직의 의사결정 기록(ADR 등)은 반드시 사람이 확인해야 해요.
3. 워크플로가 필요한 이유 — 대화 vs 제어 구조
"그냥 서브에이전트끼리 대화시키면 안 돼요?" 라고 물어볼 수 있어요. 간단한 작업은 그래도 되지만, 승인, 감사 로그, 재시도 같은 요소가 들어오면 "대화"보다 "제어 구조"가 훨씬 강해요.
| 요소 | 대화 방식 | 워크플로(제어 구조) |
|---|---|---|
| 승인 게이트 | 구현 어려움 | 자연스러운 단계로 포함 |
| 감사 로그 | 수동으로 남겨야 함 | 단계별 자동 기록 |
| 재시도 | 전체를 다시 돌림 | 실패한 단계만 재실행 |
| 분기 처리 | 복잡한 프롬프트 필요 | 조건문으로 깔끔하게 처리 |
워크플로는 "Step 1 성공 → Step 2 실행, Step 1 실패 → 알림 후 대기"처럼 명확한 흐름 제어가 가능해요. 이건 대화만으로는 안정적으로 구현하기 어려워요.
4. 하이브리드 패턴 — 서브에이전트 + 워크플로 조합
실무에서 가장 추천하는 패턴은 하이브리드예요. 작업의 성격에 따라 서브에이전트와 워크플로를 나눠 쓰는 거죠.
기본 원칙은 이거예요:
- 비결정적 생성 (초안 작성, 탐색, 리서치) → 서브에이전트
- 결정적 검증 (체크리스트 점검, 배포, 커밋) → 워크플로
왜 이렇게 나누냐면, 생성 작업은 창의적이고 탐색적이라 에이전트의 자율성이 필요하고, 검증/배포 작업은 정해진 절차를 빠짐없이 따라야 하니까 제어 구조가 적합한 거예요.
하이브리드 흐름 예시:
[서브에이전트] Researcher → 출처 수집
↓
[서브에이전트] Writer → 초안 작성
↓
[워크플로] 검증 체크리스트 실행
↓ (통과)
[워크플로] 승인 게이트 → Human 확인
↓ (승인)
[워크플로] 최종 적용 (커밋/배포)서브에이전트가 읽기와 초안 작성을 담당하고, 워크플로가 검증과 적용을 담당하는 구조예요.
5. 관측가능성 — 추적 가능한 문서 만들기
문서 자동화에서 놓치기 쉬운 게 관측가능성(Observability)이에요. 나중에 "이 문서 누가 언제 어떤 근거로 만든 거야?"라는 질문에 답할 수 있어야 해요.
실전 팁은 이거예요:
- run_id: 워크플로 실행마다 고유 ID를 부여하고 문서 메타데이터에 남기기
- trace_id: 각 서브에이전트 호출마다 추적 ID를 기록
- 출처 매핑: 문서 내 모든 주장 → 출처 → 수집 시점을 역추적 가능하게
문서 메타데이터 예시:
---
run_id: doc-2025-0612-001
generated_by: research-write-verify-pipeline
researcher_trace: trace-abc123
writer_trace: trace-def456
verifier_trace: trace-ghi789
verified_at: 2025-06-12T14:30:00Z
approved_by: jayden
---이렇게 해두면 문서에 문제가 생겼을 때 어느 단계에서 오류가 발생했는지 바로 추적할 수 있어요.
6. 실전 적용 시나리오
이 패턴이 특히 빛나는 시나리오 세 가지를 소개할게요.
시나리오 1: 기술 블로그 시리즈 작성
- Researcher: 주제별 자료 수집
- Writer: 시리즈 구조에 맞춰 초안 작성
- Verifier: 사실 확인 + 시리즈 간 일관성 검증
- Human: 최종 검토 후 발행
시나리오 2: API 문서 자동 생성
- Researcher: 코드베이스에서 엔드포인트, 타입, 주석 수집
- Writer: OpenAPI 스펙이나 마크다운 문서로 구조화
- Verifier: 실제 코드와 문서 간 불일치 탐지
- Human: 리뷰 후 배포
시나리오 3: 경쟁 분석 보고서
- Researcher: 공개 자료에서 경쟁사 정보 수집
- Writer: 비교 분석 보고서 초안
- Verifier: 출처 검증 + 주장의 논리적 타당성 검토
- Human: 전략적 판단 후 공유
핵심 정리
1. 생성자와 검증자를 분리하면 자기 확증 편향을 차단할 수 있다
2. 4단계 표준 아키텍처: Research → Write → Verify → Approve
3. 비결정적 생성=서브에이전트, 결정적 검증/배포=워크플로로 나눠라
4. 하이브리드 패턴이 실무에서 가장 안정적이다
5. run_id/trace_id로 관측가능성을 확보하면 디버깅이 쉬워진다FAQ
Q. 간단한 문서도 4단계를 다 거쳐야 하나요?
A. 아니에요. 내부용 메모나 짧은 문서는 Writer + Verifier 2단계만으로도 충분해요. 4단계는 외부 공개 문서나 의사결정 기록처럼 정확성이 중요한 경우에 쓰는 거예요. 상황에 맞게 단계를 줄이거나 늘리면 돼요.
Q. Researcher가 웹 검색도 할 수 있나요?
A. 네, Web 도구나 WebFetch를 허용하면 가능해요. 다만 외부 정보는 신뢰도가 다양하니까 Verifier 단계에서 출처 검증을 더 꼼꼼히 해야 해요. 내부 문서만 쓰는 경우보다 검증 체크리스트를 강화하는 걸 추천해요.
Q. Writer가 Researcher 역할을 겸하면 안 되나요?
A. 기술적으로는 가능하지만 권장하지 않아요. 분리하면 Writer가 "자료 수집이 부족하다"는 판단을 내릴 수 있어서 품질이 올라가거든요. 겸하면 가진 자료 안에서 억지로 글을 완성하려는 경향이 생겨요.
Q. Verifier의 "공격적 체크리스트"는 어떻게 만들어요?
A. 핵심은 "통과시키려는 관점"이 아니라 "떨어뜨리려는 관점"으로 항목을 만드는 거예요. "출처가 있는가?"가 아니라 "출처가 없는 주장을 찾아라", "숫자가 맞는가?"가 아니라 "숫자가 틀린 곳을 찾아라"처럼요. 방향을 바꾸면 탐지율이 확 올라가요.
Q. 워크플로 없이 서브에이전트만으로도 승인 게이트를 구현할 수 있나요?
A. 프롬프트로 "승인받기 전까지 다음 단계로 넘어가지 마"라고 지시할 수는 있어요. 하지만 이건 "약한 제약"이라 무시될 수 있어요. 워크플로의 제어 구조는 "코드 수준의 강한 제약"이라 훨씬 안정적이에요.
Q. run_id는 어떻게 자동으로 붙이나요?
A. Hooks를 활용하면 돼요. 워크플로 시작 시 Hook에서 고유 ID를 생성하고, 각 서브에이전트 호출 시 환경 변수나 입력으로 전달하는 방식이에요. 8편 구현 가이드에서 자세히 다룰 예정이에요.
참고 자료 (References)
데이터 출처
| 출처 | 설명 | 링크 |
|---|---|---|
| Claude Code 서브에이전트 문서 | 서브에이전트 정의 및 설정 가이드 | code.claude.com |
| Claude Code Agent Teams | 멀티 에이전트 팀 구성 가이드 | code.claude.com |
| Anthropic 멀티에이전트 연구 | 멀티에이전트 리서치 시스템 사례 | anthropic.com |
핵심 인용
"Building effective AI research systems requires separating generation from verification — the same principle that makes code review valuable applies to AI-generated content."
— Anthropic Engineering Blog
다음 편 예고
[6편] ADR/RFC/설계서 작성 자동화 — 역할별 운영 템플릿과 실전 가이드
- ADR/RFC에 특화된 서브에이전트 역할 7가지와 권한 설정
- 스코퍼, 소스 파인더, 반박자 등 역할별 입출력 계약
- ADR 확장 템플릿(Evidence, Audit Log)과 실전 적용법