에이전트 팀 구성 — 리서치·코딩·검증 AI를 나눠 협업시키는 법

:::callout type=info 이 가이드는 Claude Code 1.x / Agent SDK 기준입니다 (2026-04). 도구 업데이트 시 검토 필요. :::

AI를 한 명만 쓰는 시대는 지났다. 복잡한 프로젝트를 하나의 AI 세션에서 처리하면 컨텍스트가 오염되고, 역할이 섞이고, 품질이 저하된다. 리서치는 리서처에게, 코딩은 코더에게, 검증은 테스터에게. 역할을 나누고 전문화된 AI 에이전트 팀을 구성하면 더 빠르고 신뢰할 수 있는 결과를 얻는다. 팀 구성의 핵심은 단순하다. 에이전트마다 하나의 역할, 하나의 책임이다.

왜 에이전트를 나눠야 하는가

하나의 AI 세션에 모든 역할을 맡기면 두 가지 문제가 생긴다.

첫째, 컨텍스트 오염. 리서치 결과, 코드, 테스트 결과가 섞이면 AI가 맥락을 잃는다. 둘째, 역할 충돌. 코드를 작성한 AI가 같은 코드를 검증하면 자신의 오류를 못 잡는 경향이 있다. 에이전트 분리는 이 두 문제를 구조적으로 해결한다.

에이전트 팀 구조

기본 3-에이전트 팀:

| 에이전트 | 역할 | 입력 | 출력 | |---|---|---|---| | researcher | 외부 정보 수집·분석 | 조사 요청 | 리서치 리포트 | | coder | 기능 구현 | 스펙 + 리서치 결과 | 코드 파일 | | tester | 코드 검증·QA | 코드 + 요구사항 | PASS / BLOCK 판정 |

규모가 커지면 designer, devops, content-writer 에이전트를 추가한다.

준비물

• Claude Code CLI (최신 버전)
• .claude/commands/ 디렉터리 (플러그인 방식)
• 구현할 작업 시나리오
• 예상 시간: 40분

1단계 — 에이전트 정의 파일 작성

각 에이전트를 마크다운 파일로 정의한다. .claude/commands/ 디렉터리에 저장한다.

.claude/commands/researcher.md:

# researcher

## 역할

외부 정보를 수집·분석해 리서치 리포트를 작성하는 에이전트.

## 원칙

- WebSearch와 WebFetch를 사용해 실제 소스를 확인한다
- 추측 금지. 출처를 명시한다
- 결과물은 "요약 / 주요 발견 / 권장 접근법" 3섹션으로 구성한다

## 출력

마크다운 리포트 (300~500자)

.claude/commands/tester.md:

# tester

## 역할

코드와 기능을 검증해 PASS 또는 BLOCK을 판정하는 에이전트.

## 판정 기준

- PASS: 요구사항 충족 + 에러 처리 정상 + silent catch 없음
- BLOCK: 위 조건 중 하나라도 미충족

## 원칙

- "좋아 보인다" 같은 모호한 평가 금지
- BLOCK 시 구체적인 이유와 수정 방향을 명시한다
- 테스트 실행 결과를 근거로 판정한다

2단계 — 오케스트레이터 에이전트 정의

에이전트들을 조율하는 오케스트레이터를 정의한다. 오케스트레이터는 작업을 분해하고 적절한 에이전트에게 위임한다.

.claude/commands/orchestrator.md:

# orchestrator

## 역할

작업을 받아 researcher, coder, tester에게 순서대로 위임하고 결과를 취합하는 에이전트.

## 위임 순서

1. 외부 정보가 필요하면 → researcher 먼저
2. 구현 → coder (researcher 결과 첨부)
3. 검증 → tester (coder 결과 첨부)
4. BLOCK 판정 시 → coder에게 재작업 요청

## 금지

- 직접 코드 작성 X (coder에게 위임)
- 직접 검증 X (tester에게 위임)

3단계 — 위임 실행

Claude Code의 슬래시 명령으로 에이전트를 순서대로 호출한다.

/researcher Notion API의 데이터베이스 조회 엔드포인트 스펙을 조사해라.
반환 타입과 필터 파라미터 구조를 중점적으로 확인해라.

researcher의 결과를 받은 후 coder에게 전달한다.

/coder 다음 리서치 결과를 바탕으로 fetchNotionRecords 함수를 구현해라:
[researcher 결과 붙여넣기]

coder 결과가 나오면 tester에게 넘긴다.

/tester 다음 코드가 아래 요구사항을 만족하는지 검증해라:

- 날짜순 정렬 정상 동작
- 네트워크 오류 시 throw
- silent catch 없음

[coder 결과 붙여넣기]

결과 확인

tester가 PASS를 반환하면 해당 기능 구현이 완료된 것이다. BLOCK이 반환되면 BLOCK 이유를 coder에게 전달하고 재작업을 요청한다. 이 루프를 두 번 이상 반복해도 BLOCK이 해소되지 않으면 요구사항을 재검토하거나 사람이 개입한다.

에이전트 팀 운영 팁

• 역할 경계를 명확히: 각 에이전트의 금지 행동을 정의 파일에 명시한다
• 결과를 다음 에이전트에 전달: 컨텍스트를 요약해서 넘기되, 원본 결과 전체를 첨부한다
• BLOCK 판정 기준을 구체화: "정상이 아닌" 것이 아니라 "silent catch가 있다", "에러 처리 누락" 등 항목별로 판정 기준을 정의한다

다음 단계

3-에이전트 기본 팀이 안정화되면 콘텐츠 생성, 디자인 검토, SEO 분석 등 도메인별 전문 에이전트를 추가한다. 에이전트 팀이 커질수록 오케스트레이터의 위임 규칙을 더 명확하게 정의하는 것이 중요하다. MCP를 각 에이전트에 연결하면 에이전트가 외부 도구까지 직접 다룰 수 있는 풀 자동화 팀이 완성된다.

관련 가이드: 테스트-자동화 / mcp-입문 / 플러그인-만들기