멀티에이전트 워크플로 직접 구축 팬아웃 검증 합성 패턴 실전, Claude Code 3역할 셋업

멀티에이전트 워크플로를 직접 만들 때 핵심은 “AI를 여러 개 켜는 것”이 아니라, 작업을 나누고, 결과를 검증하고, 마지막에 하나로 합치는 규칙을 먼저 정하는 것입니다. 제가 가장 안정적으로 본 구조는 코디네이터 1개, 팬아웃 작업 에이전트 2~4개, 검증 에이전트 1개, 합성 단계 1개입니다.

작은 기능 하나를 골라 구현·테스트·리뷰 에이전트로 나눠 실행하고, 합성 전 검증 로그를 확인해보세요.

Claude Code, Cursor, OpenAI Codex CLI 같은 도구를 섞을 수 있지만 처음에는 Claude Code와 Git worktree만으로도 충분합니다. 같은 파일을 동시에 고치게 하지 말고, 각 에이전트가 “패치” 또는 “리포트”를 남기게 만드는 것이 실패율을 크게 줄입니다.

왜 팬아웃-검증-합성 패턴이 필요한가

단일 AI 에이전트에게 “기능 만들고 테스트하고 리팩터링까지 해줘”라고 맡기면 초반에는 빠릅니다. 문제는 중간부터 스스로 만든 가정을 검증하지 않고 계속 진행한다는 점입니다.

팬아웃은 같은 목표를 여러 관점으로 쪼개는 방식입니다. 예를 들어 한 에이전트는 구현만, 다른 에이전트는 테스트만, 또 다른 에이전트는 보안·엣지케이스만 봅니다. 이후 검증 단계에서 타입체크, 테스트, 린트, 요구사항 충족 여부를 확인하고, 합성 단계에서 쓸 만한 결과만 병합합니다.

제가 쓴 기본 셋업

로컬 프로젝트 기준으로는 아래 구성이 가장 단순했습니다. 복잡한 오케스트레이터부터 붙이지 않고, Git branch 또는 worktree로 충돌을 줄이는 방식입니다.

• 코디네이터: Claude Code. 요구사항을 쪼개고 각 에이전트 지시문을 생성
• 작업 에이전트 A: 구현 담당. UI나 API 코드만 수정
• 작업 에이전트 B: 테스트 담당. Vitest, Playwright, Jest 테스트 추가
• 작업 에이전트 C: 리뷰 담당. 보안, 성능, 예외 케이스 리포트 작성
• 검증: pnpm test, pnpm typecheck, ESLint, GitHub Actions
• 합성: Claude Code가 diff를 읽고 최종 패치 후보만 선택

n8n이나 LangGraph를 쓰면 자동화는 더 좋아지지만, 처음부터 붙이면 디버깅 포인트가 늘어납니다. 먼저 터미널과 Git으로 흐름을 손에 익힌 뒤 자동화하는 편이 낫습니다.

실전 예시: Next.js 문의 폼 기능 만들기

가상의 예로, Next.js 앱에 문의 폼을 추가한다고 해보겠습니다. 코디네이터에게 먼저 이렇게 지시합니다.

목표: Next.js 앱에 문의 폼을 추가한다.
제약: 기존 디자인 시스템을 유지하고, 서버 액션에서 입력 검증을 한다.
산출물: 구현 diff, 테스트 diff, 리뷰 리포트를 분리한다.
금지: 같은 파일을 여러 에이전트가 동시에 수정하지 않는다.

그다음 구현 에이전트는 app/contact와 컴포넌트만 다룹니다. 테스트 에이전트는 폼 검증 실패, 성공 메시지, 빈 값 제출을 확인합니다. 리뷰 에이전트는 스팸 방지, 개인정보 문구, 서버 측 검증 누락을 따로 적습니다.

마지막 합성 단계에서는 “가장 많은 코드를 만든 결과”가 아니라 “테스트를 통과하고 요구사항을 덜 깨는 결과”를 선택합니다. 이 기준이 없으면 멀티에이전트는 생산성 도구가 아니라 충돌 제조기가 됩니다.

도구별로 어디까지 맡기면 좋은가

추천 대상: 이렇게 나눠 쓰면 좋습니다

혼자 SaaS를 만드는 개발자라면 구현 1개, 테스트 1개, 리뷰 1개만으로 충분합니다. Claude Code를 중심에 두고 GitHub Actions로 검증을 붙이는 구성이 가장 현실적입니다.

팀에서 PR 리뷰 병목이 있는 경우에는 리뷰 에이전트를 강화하세요. 보안, 성능, 마이그레이션 위험, 접근성처럼 사람이 놓치기 쉬운 항목을 체크리스트화하면 효과가 납니다.

자동화에 익숙한 빌더라면 n8n이나 Make로 “이슈 생성 → 에이전트 실행 → 테스트 결과 Slack 전송”까지 묶을 수 있습니다. 다만 코드 수정 자체보다 실패 로그를 잘 남기는 것이 더 중요합니다.

가장 자주 막히는 지점

1. 에이전트가 서로 같은 파일을 고친다

이 문제가 제일 흔합니다. 해결책은 역할이 아니라 파일 소유권으로 나누는 것입니다. 구현 담당은 컴포넌트, 테스트 담당은 테스트 파일, 리뷰 담당은 마크다운 리포트처럼 산출물을 분리하세요.

2. 검증 없이 합성한다

AI가 “완료했습니다”라고 말해도 빌드가 깨질 수 있습니다. 합성 전에는 최소한 pnpm lint, pnpm typecheck, pnpm test 중 프로젝트에 맞는 명령을 실행하게 하세요.

3. 프롬프트가 너무 추상적이다

“좋게 개선해줘”는 멀티에이전트에 맞지 않습니다. “입력값 검증 추가”, “테스트 3개 작성”, “보안 리스크만 보고서로 정리”처럼 결과물이 보이는 지시가 필요합니다.

바로 쓰는 운영 규칙

처음 도입할 때는 하루짜리 실험으로 충분합니다. 새 기능 전체가 아니라 작은 버그 수정이나 폼 하나를 대상으로 삼으세요.

1. 작업 목표와 성공 조건을 5줄 이내로 적는다.
2. 에이전트별 파일 범위와 금지 행동을 정한다.
3. 각 결과를 diff 또는 리포트로 남기게 한다.
4. 검증 명령을 실행한 로그만 합성 후보로 삼는다.
5. 최종 병합은 사람이 한 번 읽고 결정한다.

이 흐름을 2~3번 반복하면 어느 부분을 자동화해도 되는지 보입니다. 그때 n8n, GitHub Actions, Slack 알림을 붙여도 늦지 않습니다.

FAQ

Q. 꼭 LangGraph 같은 프레임워크가 필요한가요?

아닙니다. 실전 초반에는 Git worktree, Claude Code, 테스트 명령만으로도 충분합니다. 프레임워크는 반복 실행과 상태 관리가 필요해질 때 도입하는 편이 좋습니다.

Q. 에이전트는 몇 개가 적당한가요?

대부분의 개인 프로젝트는 3개가 적당합니다. 구현, 테스트, 리뷰로 나누면 병렬성은 생기고 관리 부담은 과하지 않습니다.

Q. 비용이 많이 들지 않나요?

큰 리팩터링을 무작정 병렬 실행하면 비용이 늘 수 있습니다. 작은 태스크로 쪼개고, 검증 실패 시 중단하도록 설계하면 낭비를 줄일 수 있습니다. 실제 비용은 모델, 토큰, 실행 시간에 따라 달라집니다.

마무리 액션: 오늘은 새 도구를 더 설치하기보다, 현재 프로젝트에서 “테스트 가능한 작은 기능” 하나를 고르세요. 그리고 구현·테스트·리뷰 세 역할로 나눠 실행한 뒤, 합성 전에 반드시 로그를 확인해보면 됩니다.

관련 링크

• AI 에이전트 하네스 엔지니어링 입문 결정적 오케스트레이션 직접 짜기: 에이전트를 ‘믿는’ 대신 묶어두는 법
• ai 코딩 구독 요금 비교: Claude Code·Cursor·Copilot, 빌드용으로 돈값 하는 조합
• ai 코딩 에이전트 테스트 자동화, 생성 코드 믿고 배포하려면 제가 두는 5개 게이트
• 관련 태그 더 보기
• 카테고리 더 보기
• 검색 결과 더 보기
• 참고 링크