.claude/agents/web-researcher.md

SubAgent 강의 자료

실제 에이전트 파일로 배우는 SubAgent 설계 원칙
Claude Code SubAgent Pattern web-researcher
① 한국어 번역
② 구조 해부
③ 실행 흐름
④ 강의 핵심
R ## Role — 역할 정의

당신은 소프트웨어 개발을 지원하기 위해 온라인에서 관련성 높고 최신 정보를 찾는 데 탁월한 기술 리서처입니다. 공식 문서, 기술 블로그, 포럼을 능숙하게 탐색하여 모범 사례(Best Practices)와 솔루션을 찾아냅니다.

T ## Task — 임무 범위

기능 요청 파일(예: INITIAL.md)이 주어지면, 목적에 집중된 웹 리서치를 수행하여 "웹 리서치 리포트"를 작성합니다. 이 리포트는 라이브러리 문서, 모범 사례 등 외부 맥락 정보를 제공하여 기능 구현을 지원합니다.

P ## Process — 실행 절차
  1. 1
    요청 이해: 제공된 기능 파일($ARGUMENTS)을 읽어 언급된 핵심 기술, 라이브러리, 외부 API를 파악합니다.
  2. 2
    웹 리서치 수행: 웹 검색 도구를 사용하여 식별된 기술 관련 정보를 탐색합니다. 집중 영역:
    • 공식 문서: 라이브러리/API의 공식 문서 탐색. 작업과 관련된 특정 페이지나 섹션(API 엔드포인트, 특정 함수 사용법 등) 특정
    • 모범 사례: 지정된 기술로 기능 구현 시 모범 사례를 설명하는 아티클, 블로그 포스트, 포럼(Stack Overflow 등) 검색
    • 흔한 함정: 알려진 이슈, 버전 충돌, 피해야 할 일반적인 실수 탐색
  3. 3
    결과 합성: 리서치 결과를 간결하고 실행 가능한 리포트로 정리합니다. 전반적인 요약보다 직접 링크와 구체적이고 관련성 높은 정보를 우선시합니다.
O ## Output Format — 출력 형식 (고정 규약)

최종 출력은 반드시 아래 섹션이 포함된 Markdown 형식 리포트여야 합니다:

섹션 1 — Official Documentation (공식 문서)
공식 문서에서 가장 관련성 높은 페이지의 직접 URL 목록
섹션 2 — Implementation Guides & Examples (구현 가이드 & 예시)
유사 기능 구현 방법을 보여주는 고품질 튜토리얼, 아티클, 코드 저장소 링크
섹션 3 — Key Considerations & Gotchas (주요 고려사항 & 함정)
리서치에서 파악한 중요 포인트·잠재적 이슈·모범 사례 목록 (버전 호환성, 인증 방식, Rate Limiting 등)
● Role (역할) 섹션
페르소나 설정

"기술 리서처"라는 명확한 전문가 페르소나를 부여합니다. 이 한 문단이 에이전트가 어떤 관점·태도·어조로 작동할지를 결정합니다.

Role은 전문성의 경계를 만든다. "개발자"가 아닌 "리서처"이기 때문에 코드를 작성하지 않고 정보를 수집·정리한다.
● Task (임무) 섹션
입력·출력 정의

무엇을 입력받고(INITIAL.md) 무엇을 출력하는지(Web Research Report)를 단 두 문장으로 명시합니다.

입출력이 명확해야 메인 에이전트가 언제 이 SubAgent를 써야 하는지를 description만 보고 판단 가능하다.
● Process (절차) 섹션
실행 체계화

3단계 순서(이해 → 리서치 → 합성)로 작업을 구조화합니다. 각 단계에서 무엇에 집중해야 하는지를 하위 항목으로 명시합니다.

Process가 있으면 LLM이 임의로 순서를 바꾸지 않는다. 반복 가능하고 예측 가능한 결과를 만든다.
● Output Format (출력 형식) 섹션
결과 표준화

출력 형식을 고정 템플릿으로 강제합니다. "MUST"라는 표현으로 반드시 따라야 함을 명시합니다.

다운스트림 에이전트(코드 작성 에이전트 등)가 파싱 없이 결과를 바로 소비 가능하다.
  web-researcher.md — 원본 (구조 하이라이트) 
# Agent: Web Researcher

## Role                          ← 📌 페르소나 (1~2문장으로 충분)

You are a technical researcher who excels at finding relevant,
up-to-date information online to support software development...

## Task                          ← 📌 입출력 계약 (무엇을 받아 무엇을 줄지)

Given a feature request file (e.g., `INITIAL.md`), your task is to
conduct targeted web research and produce a "Web Research Report"...

## Process                       ← 📌 실행 절차 (순서 고정)

1. **Understand the Request**: Read the provided feature file (`$ARGUMENTS`)...
2. **Conduct Web Research**: Use your web search tool...
   - **Official Documentation**: Find the official docs...
   - **Best Practices**: Search for articles, blog posts...
   - **Common Pitfalls**: Look for known issues...
3. **Synthesize Findings**: Organize your research...

## Output Format               ← 📌 출력 규약 (MUST = 강제)

Your final output MUST be a markdown-formatted report with:

#### 1. Official Documentation
#### 2. Implementation Guides & Examples
#### 3. Key Considerations & Gotchas
실제 호출 시나리오 — "React Query 기능 추가" 요청

각 단계를 클릭하면 상세 설명을 볼 수 있습니다

U
사용자 요청
"React Query를 사용한 데이터 fetching 기능을 추가해 줘"
사용자는 단지 원하는 것만 말한다. 어떤 라이브러리 버전을 쓸지, 문서가 어디 있는지 알 필요가 없다. 메인 에이전트가 판단을 시작한다.
M
메인 에이전트 — SubAgent 선택 description 매칭
메인 에이전트가 .claude/agents/ 디렉토리의 에이전트 description을 스캔. "web researcher"가 기술 리서치 작업에 적합하다고 판단.
자동 선택 기준:
에이전트의 description 필드와 현재 작업의 성격이 매칭될 때 자동 위임됩니다. 명시적으로 요청할 수도 있습니다:
  • "Use the web-researcher subagent to research React Query"
  • 또는 메인 에이전트가 스스로 판단하여 호출
①
SubAgent 시작 — 요청 이해 독립 컨텍스트
메인 에이전트로부터 INITIAL.md 파일 경로를 전달받아 읽기 시작. React Query, TanStack Query, fetching 패턴 등 핵심 기술 식별.
컨텍스트 격리:
SubAgent는 완전히 새로운 컨텍스트 창에서 시작합니다. 메인 에이전트의 긴 대화 히스토리를 물려받지 않아 $ARGUMENTS로 넘겨받은 정보만 갖습니다.
  • 메인 에이전트 컨텍스트 오염 없음
  • 빠르고 가벼운 실행 가능
②
SubAgent — 웹 리서치 수행 web_search 도구
공식 문서(tanstack.com), 모범 사례 아티클, Stack Overflow의 흔한 함정 등을 순서대로 탐색. 수십 개의 검색 결과를 처리.
탐색 범위 (Process 섹션에 정의됨):
  • 공식 문서: tanstack.com/query/v5/docs 특정 페이지
  • 모범 사례: "React Query best practices 2025" 검색
  • 흔한 함정: "React Query v5 breaking changes", "stale time pitfalls"
이 모든 탐색 과정이 메인 에이전트 컨텍스트에 쌓이지 않는다.
③
SubAgent — 리포트 합성 Output Format 준수
수집한 정보를 고정된 Output Format(3개 섹션)에 맞게 정리. 일반 요약보다 직접 링크와 구체적 정보를 우선.
Output Format의 위력:
출력 형식이 고정되어 있으므로, 다음에 실행될 코드 작성 SubAgent는 파싱 로직 없이 바로:
  • 섹션 1에서 공식 문서 URL 추출
  • 섹션 3에서 버전·인증 주의사항 확인
에이전트 간 표준화된 핸드오프가 가능해진다.
R
메인 에이전트 — 결과 수신 최종 결과만 반환
메인 에이전트는 SubAgent의 중간 과정(수십 번의 검색)을 모두 건너뛰고, 최종 Web Research Report만 받아 다음 단계(구현)에 활용.
컨텍스트 절약 효과:
SubAgent가 30번의 웹 검색을 했더라도 메인 에이전트에는 최종 리포트 텍스트(~2000토큰)만 전달됩니다. 메인 에이전트의 컨텍스트 창이 고갈되지 않아 전체 워크플로우를 더 오래 유지할 수 있습니다.
🔒
컨텍스트 격리
SubAgent의 작업 과정이 메인 에이전트 컨텍스트에 쌓이지 않음
⚡
병렬 실행 가능
여러 SubAgent를 동시에 실행해 작업 시간을 단축할 수 있음
♻️
재사용 가능
한번 만든 web-researcher는 모든 프로젝트의 모든 기능 요청에 재사용
LESSON 01

SubAgent는 전문가 직원이다

web-researcher.md는 "리서치만 하는 직원"의 채용 공고와 같다. 역할이 좁고 명확할수록 일관된 결과를 만든다.

  • 한 에이전트 = 한 가지 책임
  • 코딩·리서치·테스트를 섞지 않는다
  • 전문화가 품질과 예측 가능성을 높인다
LESSON 02

$ARGUMENTS 가 입력 계약이다

메인 에이전트가 SubAgent를 호출할 때 넘기는 값이 $ARGUMENTS다. 명확한 입력 계약이 있어야 자동 위임이 작동한다.

  • 파일 경로, 기술명, 요구사항 등 전달 가능
  • 입력이 불명확하면 결과도 불명확해진다
  • Task 섹션에 입력 형식을 명시하라
LESSON 03

Output Format이 다운스트림 품질을 결정한다

고정된 3개 섹션 구조 덕분에 다음 에이전트(코드 작성)가 리포트를 즉시 파싱할 수 있다.

  • 섹션 구조를 명시적으로 정의하라
  • "MUST"로 형식 준수를 강제하라
  • 다운스트림 소비를 고려해 설계하라
LESSON 04

Process가 블랙박스를 없앤다

순서가 명시된 3단계 Process 덕분에 에이전트가 임의로 행동하지 않는다. 실행이 추적 가능하고 디버깅이 쉬워진다.

  • 단계별 순서를 명확히 기술하라
  • 각 단계의 집중 영역을 하위 항목으로
  • 재현 가능한 결과 = 신뢰 가능한 에이전트
SubAgent 설계 — Do / Don't
✓ 좋은 설계
  • 역할을 한 문장으로 설명 가능한가
  • 입력($ARGUMENTS)이 명확한가
  • 출력 형식이 고정되어 있는가
  • 도구 접근이 필요한 것만 허용했는가
  • 다른 프로젝트에서도 재사용 가능한가
✕ 나쁜 설계
  • 리서치 + 코딩 + 테스트를 한 에이전트에
  • 출력이 "알아서 써줘" 수준으로 모호함
  • Process 없이 자유롭게 판단하도록 방치
  • 모든 도구 권한을 아무 이유 없이 부여
  • 특정 프로젝트에만 종속된 하드코딩
4

web-researcher.md가 보여주는 완벽한 SubAgent 구조

Role(페르소나) → Task(입출력 계약) → Process(실행 절차) → Output Format(결과 표준화). 이 4개 섹션만 제대로 작성해도, 메인 에이전트는 언제 이 에이전트를 써야 하는지, 어떻게 호출하는지, 무엇을 돌려받는지를 자동으로 판단할 수 있다.