Claude Code 서브 에이전트로 E2E 테스트 자동화 생산성 10배 높이기 - Playwright 완벽 활용 가이드

여러분, Playwright 기반 E2E 테스트는 제품 품질을 지키는 데 정말 중요합니다. 그런데 시나리오 기획, 코드 작성, 실패 원인 분석을 전부 사람이 직접 처리하면 금방 병목이 되죠. Claude Code의 서브 에이전트 기능을 활용하면 이 과정을 역할별 에이전트로 나누고 병렬로 처리할 수 있습니다.

결론부터 말하면, 핵심은 역할을 쪼개는 겁니다. 이 글에서는 Claude Code 서브 에이전트로 Playwright E2E 테스트 자동화 파이프라인을 설계하는 방법을 다룹니다. 단순히 AI에게 테스트 코드를 작성시키는 수준을 넘어, Planner, Generator, Healer처럼 역할을 분리한 에이전트가 테스트 기획부터 복구까지 처리하는 구조를 설명합니다.

이 글을 읽으면 얻을 수 있는 것

• Claude Code 서브 에이전트의 개념과 작동 원리: 단일 AI와 다르게 역할을 분담하여 복잡한 작업을 처리하는 시스템 설계 방식 이해
• Playwright E2E 테스트 자동화 완전 구축: 테스트 기획부터 코드 생성, 검증, 자동 복구까지 모든 단계를 에이전트로 자동화하는 실전 구현 방법
• 병렬 처리로 생산성 극대화: 여러 개의 서브 에이전트를 동시에 실행하여 작업 속도를 최소 10배 이상 높이는 구체적인 기법
• 의존성 관리와 그룹화 전략: 테스트 간 충돌을 방지하고 안전하게 병렬 실행하는 그룹화 방법론
• 컨텍스트 윈도우 효율 최적화: 메인 에이전트의 컨텍스트를 절약하면서 대규모 작업을 처리하는 아키텍처 설계
• 실패한 테스트 자동 복구 시스템: Healer 에이전트를 활용한 자동 디버깅 및 수정 흐름 구축
• 실무에 바로 적용 가능한 3개 에이전트 설정: Planner, Generator, Healer 에이전트의 구체적인 설정과 활용법

Claude Code 서브 에이전트란? 시스템으로 설계하는 AI 개발 파이프라인

서브 에이전트의 핵심 개념

Claude Code의 서브 에이전트(subagent)는 단순히 “여러 개의 AI를 동시에 실행”하는 기능이 아닙니다. 제가 더 중요하게 보는 건 이겁니다. 하나의 AI에게 모든 업무를 맡기는 대신, 역할을 전문화해서 분담하고 병렬로 실행한다는 것. 이건 개발 파이프라인을 시스템으로 설계하는 접근 방식이라고 봅니다.

전통적인 AI 활용 방식에서는 하나의 프롬프트에 모든 요구사항을 담아 단일 AI에게 요청합니다. 이 방식은 작업이 복잡해질수록 다음과 같은 문제가 발생합니다:

1. 컨텍스트 윈도우 고갈: 모든 정보를 단일 세션에 담다 보면 컨텍스트 한계에 빠르게 도달합니다.
2. 역할 혼란: AI가 여러 가지 역할을 동시에 수행하면서 각 단계의 품질이 떨어집니다.
3. 순차 처리의 비효율: 모든 작업을 하나씩 처리하므로 시간이 오래 걸립니다.
4. 에러 복구 어려움: 중간에 실패하면 전체 프로세스를 다시 시작해야 합니다.

서브 에이전트 아키텍처의 장점

서브 에이전트를 활용하면 이러한 문제를 근본적으로 해결할 수 있습니다:

1. 역할 전문화

각 에이전트는 하나의 명확한 역할만 수행합니다. 예를 들어 Planner 에이전트는 테스트 시나리오 기획만, Generator 에이전트는 코드 생성만, Healer 에이전트는 에러 복구만 담당합니다. 이렇게 역할을 분리하면 각 에이전트는 자신의 작업에만 집중할 수 있어 품질이 높아집니다.

2. 병렬 처리를 통한 속도 향상

메인 에이전트는 여러 개의 서브 에이전트를 동시에 실행할 수 있습니다. 예를 들어 50개의 테스트를 작성해야 한다면, 하나의 에이전트가 순차적으로 처리하는 대신 12개의 Generator 에이전트를 병렬로 실행하여 작업 시간을 12배 단축할 수 있습니다.

3. 독립적인 컨텍스트 윈도우

가장 중요한 장점 중 하나는 각 서브 에이전트가 독립적인 컨텍스트 윈도우를 가진다는 점입니다. 메인 에이전트의 컨텍스트는 오케스트레이션(조율)에만 사용되고, 실제 작업에 필요한 상세 정보는 각 서브 에이전트가 자체 컨텍스트에서 관리합니다. 이렇게 하면 대규모 작업을 처리할 때도 메인 에이전트의 컨텍스트가 고갈되지 않습니다.

4. 에러 격리와 복구

하나의 서브 에이전트에서 에러가 발생해도 다른 에이전트에는 영향을 주지 않습니다. 실패한 작업만 재시도하거나 Healer 에이전트로 복구할 수 있습니다.

서브 에이전트를 활용하기 좋은 시나리오

서브 에이전트는 다음과 같은 상황에서 특히 효과적입니다:

• 반복적이고 독립적인 작업: 여러 개의 테스트 코드 작성, 다수의 API 엔드포인트 구현, 컴포넌트 생성 등
• 역할이 명확히 분리 가능한 작업: 기획 → 구현 → 검증처럼 단계가 구분되는 파이프라인
• 대규모 작업: 컨텍스트 윈도우를 효율적으로 관리해야 하는 대량 작업
• 안전성이 중요한 작업: 기존 코드에 영향을 주지 않는 테스트 작성이나 문서 생성

Playwright E2E 테스트 자동화를 위한 3가지 에이전트

이 글에서는 Playwright 테스트 자동화를 위해 세 가지 전문화된 서브 에이전트를 구축합니다. 각 에이전트는 파이프라인의 한 단계를 담당하며, 순차적으로 실행되면서 완전한 E2E 테스트 시스템을 구성합니다.

1. Planner 에이전트: 테스트 계획 수립

역할: 웹 애플리케이션의 테스트 계획을 수립하는 전략가

주요 기능:

• 브라우저 탐색: Playwright로 실제 브라우저를 열어 애플리케이션의 UI와 동작을 직접 확인
• 인터페이스 분석: 페이지의 요소, 네비게이션, 상태 변화 등을 체계적으로 분석
• 사용자 플로우 매핑: 실제 사용자의 동선과 인터랙션 패턴을 파악
• 테스트 시나리오 설계: 기능 검증, 에지 케이스, 에러 처리 등을 포함한 포괄적인 시나리오 도출
• 계획 문서 작성: 마크다운 형식으로 구조화된 테스트 계획 문서 생성

Planner 에이전트는 개발자가 직접 애플리케이션을 탐색하며 테스트 케이스를 구상하는 과정을 자동화합니다. 브라우저를 실제로 제어하면서 모든 페이지와 기능을 확인하고, 어떤 시나리오를 테스트해야 할지 체계적으로 정리합니다.

예를 들어 영화 정보 사이트라면, 인기 영화 목록 조회, 장르별 필터링, 영화 상세 페이지 이동, 검색 기능, 페이지네이션 등 모든 사용자 시나리오를 식별하고 각각에 대한 테스트 케이스를 생성합니다.

2. Generator 에이전트: 테스트 코드 생성

역할: 테스트 계획을 실제 Playwright 코드로 변환하는 실행자

주요 기능:

• 테스트 계획 읽기 및 분석: Planner가 생성한 마크다운 문서를 파싱하여 각 시나리오의 요구사항 파악
• 브라우저 실제 동작 실행: 계획된 시나리오를 브라우저에서 직접 실행하며 정확한 셀렉터와 동작 순서 확인
• 실행 로그 기반 코드 생성: 실제로 실행한 인터랙션을 바탕으로 정확하고 안정적인 Playwright 코드 작성
• 테스트 파일 작성: 프로젝트 구조에 맞는 파일명과 경로로 테스트 파일 생성
• Best Practice 적용: Playwright의 권장 패턴(예: getByRole, waitFor 등)을 자동 적용

Generator 에이전트는 단순히 프롬프트만 보고 코드를 생성하는 것이 아니라, 실제로 브라우저를 조작하며 동작을 확인한 후 코드로 변환합니다. 이렇게 하면 셀렉터가 잘못되거나 타이밍 이슈가 발생할 가능성을 크게 줄일 수 있습니다.

또한 Generator 에이전트는 여러 개를 병렬로 실행할 수 있도록 설계되어 있습니다. 50개의 테스트 시나리오가 있다면, 의존성이 없는 시나리오끼리 그룹화하여 12개의 Generator 에이전트를 동시에 실행함으로써 작업 속도를 대폭 향상시킬 수 있습니다.

3. Healer 에이전트: 테스트 디버깅 및 복구

역할: 실패한 테스트를 자동으로 수정하는 의사

주요 기능:

• 실패한 테스트 식별: 테스트 실행 결과를 분석하여 실패한 케이스와 에러 메시지 추출
• 테스트 디버깅: 실패 원인을 파악하기 위해 브라우저에서 재실행하며 로그와 스크린샷 수집
• 에러 원인 분석: 타임아웃, 셀렉터 변경, 비동기 타이밍 이슈, 데이터 의존성 등 실패 유형 분류
• 테스트 코드 수정: 원인에 맞는 수정(셀렉터 변경, 대기 시간 추가, 조건 로직 개선 등) 적용
• 재검증: 수정한 테스트를 다시 실행하여 통과 여부 확인

Healer 에이전트는 테스트 유지보수의 핵심입니다. Generator가 완벽한 테스트를 한 번에 생성하는 것이 이상적이지만, 실제로는 UI 변경, 네트워크 타이밍, 데이터 가변성 등으로 인해 일부 테스트가 실패할 수 있습니다. Healer 에이전트는 이런 실패를 자동으로 감지하고 수정하여, 테스트가 지속 가능하게 유지되도록 만듭니다.

Healer 에이전트 역시 병렬 실행이 가능하므로, 여러 파일에서 동시에 실패한 테스트들을 한 번에 처리할 수 있습니다.

에이전트 설치 및 설정

서브 에이전트 설치 방법

Claude Code에서 Playwright 서브 에이전트를 설치하는 과정은 간단합니다. 설치 명령어를 Claude Code 세션에 입력하면 자동으로 .claude/agents/ 디렉토리에 세 가지 에이전트 설정 파일이 생성됩니다.

# Claude Code 세션에서 설치 명령어 실행

설치가 완료되면 .claude/agents/ 디렉토리 아래에 다음 파일들이 생성됩니다:

.claude/
  agents/
    playwright-planner.md
    playwright-generator.md
    playwright-healer.md

각 파일은 마크다운 형식으로 작성된 에이전트 설정입니다. 에이전트의 역할, 사용할 도구, 작업 절차, 출력 형식 등이 구조화되어 있습니다.

에이전트 설정 파일 구조

에이전트 설정 파일은 다음과 같은 섹션으로 구성됩니다:

1. Role(역할): 에이전트가 수행할 핵심 역할 정의

2. Tools(도구): 사용 가능한 도구 목록 (예: Playwright, 파일 읽기/쓰기, Bash 실행 등)

3. Workflow(작업 흐름): 단계별 작업 절차와 의사결정 규칙

4. Output Format(출력 형식): 생성할 결과물의 형식과 저장 경로

5. Constraints(제약사항): 에이전트가 준수해야 할 규칙과 금지 사항

프로젝트별 커스터마이징

제공된 에이전트는 기본 템플릿이므로, 프로젝트의 특성에 맞게 커스터마이징할 수 있습니다:

• 테스트 파일 경로: 프로젝트의 디렉토리 구조에 맞게 테스트 파일 저장 경로 수정
• 네이밍 컨벤션: 팀의 테스트 파일 명명 규칙 적용
• 추가 검증 규칙: 프로젝트 특유의 검증 로직(예: 접근성 체크, 성능 측정) 추가
• 에러 처리 전략: 특정 에러 유형에 대한 대응 방식 정의

실전 적용: 영화 정보 사이트 E2E 테스트 자동화

이제 실제 프로젝트에 서브 에이전트를 적용하는 전체 과정을 단계별로 같이 보겠습니다. 예제로 쓸 애플리케이션은 영화 정보를 제공하는 웹 서비스인데, 인기 영화, 장르별 필터링, 영화 상세 페이지 같은 기능을 갖고 있습니다.

사전 준비: Ralph Loop 모드 실행

서브 에이전트를 활용한 대규모 작업에서는 Ralph Loop 모드를 사용하는 것을 강력히 권장합니다. Ralph Loop 모드는 Claude Code의 자동 실행 모드로, 에이전트가 사용자의 허락을 일일이 받지 않고 작업을 연속적으로 수행할 수 있습니다.

왜 Ralph Loop 모드를 사용해야 하는가?

1. 병렬 처리 효율성: 12개의 Generator 에이전트가 동시에 실행될 때, 각 에이전트마다 승인을 기다리면 병렬 처리의 이점이 사라집니다.
2. 테스트 코드의 안전성: 테스트 코드는 프로덕션 코드에 직접적인 영향을 주지 않으므로, 자동 실행해도 위험이 낮습니다.
3. 생산성 극대화: 한 번의 승인으로 전체 파이프라인이 자동으로 실행되므로 개발자는 결과만 확인하면 됩니다.

Ralph Loop 모드로 Claude Code를 실행하려면:

claude --loop

1단계: Planner 에이전트로 테스트 시나리오 기획

첫 번째 단계는 Planner 에이전트를 호출하여 테스트 계획을 수립하는 것입니다. 메인 에이전트(사용자가 대화하는 세션)에서 다음과 같이 요청합니다:

퍼슨 페이지 테스트 시나리오 작성해줘.
playwright-planner 에이전트를 호출해서 작업하도록 해.

이 요청을 받으면 메인 에이전트는 playwright-planner 서브 에이전트를 실행합니다. Planner 에이전트는 다음 작업을 수행합니다:

브라우저 탐색 및 분석

Planner는 Playwright를 사용하여 실제 브라우저를 열고 지정된 페이지(예: /person/:id)를 방문합니다. 그리고 다음 정보를 수집합니다:

• 페이지에 표시되는 모든 UI 요소 (제목, 이미지, 버튼, 링크 등)
• 사용자가 수행할 수 있는 모든 인터랙션 (클릭, 입력, 스크롤 등)
• 페이지의 데이터 소스 (API 호출, 라우팅 파라미터 등)
• 다른 페이지로의 네비게이션 경로

시나리오 도출

수집한 정보를 바탕으로 Planner는 테스트해야 할 시나리오를 체계적으로 정리합니다. 예를 들어:

• 기본 렌더링 검증: 페이지가 정상적으로 로드되고 필수 요소가 모두 표시되는지
• 데이터 표시 검증: 배우 이름, 프로필 이미지, 출연 작품 목록 등이 올바르게 표시되는지
• 인터랙션 검증: 출연 작품을 클릭하면 해당 영화 페이지로 이동하는지
• 에지 케이스: 존재하지 않는 배우 ID로 접근 시 에러 처리가 되는지
• 반응형 디자인: 모바일 뷰포트에서도 정상 동작하는지

계획 문서 작성

Planner는 도출한 시나리오를 마크다운 문서로 정리하여 저장합니다. 문서는 다음과 같은 구조를 가집니다:

# Person Page 테스트 계획

## 1. 기본 렌더링 검증

- 배우 이름이 표시되는지 확인
- 프로필 이미지가 로드되는지 확인
- 출연 작품 목록이 표시되는지 확인

## 2. 데이터 정확성 검증

- API로부터 받은 데이터와 화면 표시 내용이 일치하는지 확인
  ...

실제 프로젝트에서는 Planner가 50개 이상의 상세한 시나리오를 생성할 수 있습니다. 이렇게 많은 시나리오를 사람이 직접 기획하려면 몇 시간이 걸리지만, Planner 에이전트는 몇 분 안에 완료합니다.

2단계: 시나리오 그룹화 (의존성 분리)

Planner가 50개의 시나리오를 생성했다면, 이제 이것을 Generator 에이전트로 코드화해야 합니다. 하지만 50개의 테스트를 하나의 에이전트가 순차적으로 작성하면 시간이 오래 걸립니다.

병렬 처리를 위해 여러 개의 Generator 에이전트를 동시에 실행하려면, 테스트 간 의존성 충돌이 발생하지 않도록 시나리오를 그룹화해야 합니다.

의존성 충돌이란?

여러 테스트가 동일한 리소스(데이터베이스, 파일, API 상태 등)를 동시에 수정하거나 공유하면 예상치 못한 결과가 발생할 수 있습니다. 예를 들어:

• 테스트 A가 특정 영화를 “좋아요” 상태로 변경
• 동시에 실행된 테스트 B가 같은 영화의 “좋아요” 상태를 확인
• 테스트 B는 A의 변경 때문에 예상과 다른 결과를 얻음

그룹화 전략

메인 에이전트에게 다음과 같이 요청합니다:

테스트 시나리오를 분석해서 테스트 코드를 병렬로 작성 가능하도록 의존성이 겹치지 않는 시나리오를 그룹화해줘.

같은 페이지나 같은 컴포넌트를 테스트하더라도 완전히 다른 기능을 테스트하는 경우에는 병렬 처리 가능.
상태를 공유하거나 순차적으로 실행해야 되는 테스트는 같은 그룹으로 묶어줘.

메인 에이전트는 각 시나리오의 특성을 분석하여 그룹을 나눕니다:

그룹 1: 읽기 전용 테스트

• 페이지 렌더링 검증
• 데이터 표시 확인
• 네비게이션 링크 검증

그룹 2: 필터링 기능 테스트

• 장르별 필터 적용
• 정렬 옵션 변경
• 검색 기능

그룹 3: 인터랙션 테스트

• 좋아요 버튼 클릭
• 리뷰 작성
• 공유 기능

…

실제 프로젝트에서는 12개 그룹으로 나뉘었으며, 각 그룹은 독립적으로 실행 가능한 시나리오들로 구성됩니다.

3단계: Generator 에이전트로 테스트 코드 병렬 생성

이제 그룹화된 시나리오를 바탕으로 실제 Playwright 테스트 코드를 생성합니다. 핵심은 여러 개의 Generator 에이전트를 동시에 실행하여 작업 속도를 최대화하는 것입니다.

메인 에이전트에게 다음과 같이 요청합니다:

playwright-generator 에이전트를 활용해서 그룹별로 병렬로 에이전트를 띄워서 테스트 코드를 작성해줘.

병렬 실행 메커니즘

메인 에이전트는 12개 그룹 각각에 대해 독립적인 Generator 서브 에이전트를 생성합니다. 각 서브 에이전트는:

1. 할당받은 그룹의 시나리오만 읽음
2. 독립적인 컨텍스트 윈도우에서 작업
3. 다른 에이전트와 간섭 없이 브라우저 조작 및 코드 생성
4. 완료 후 결과를 메인 에이전트에게 보고

실행 과정 시각화

Claude Code 인터페이스에서는 12개의 브라우저 창이 동시에 열리며, 각각 다른 테스트 시나리오를 실행하는 모습을 확인할 수 있습니다. 각 Generator 에이전트는:

• 브라우저를 열고 해당 페이지로 이동
• 시나리오에 정의된 인터랙션을 순서대로 실행
• 각 단계에서 필요한 셀렉터와 액션을 기록
• 실행 로그를 바탕으로 Playwright 코드 작성
• 테스트 파일로 저장 (예: person-page-group-1.spec.ts)

생성된 코드 예시

import { test, expect } from '@playwright/test';

test.describe('Person Page - 기본 렌더링', () => {
  test('배우 이름과 프로필 이미지가 표시된다', async ({ page }) => {
    await page.goto('/person/123');

    const actorName = page.getByRole('heading', { level: 1 });
    await expect(actorName).toBeVisible();

    const profileImage = page.getByRole('img', { name: /profile/i });
    await expect(profileImage).toBeVisible();
  });

  test('출연 작품 목록이 표시된다', async ({ page }) => {
    await page.goto('/person/123');

    const movieList = page.getByRole('list', { name: /filmography/i });
    await expect(movieList).toBeVisible();

    const movies = page.getByRole('listitem');
    await expect(movies).toHaveCount(10);
  });
});

작업 시간 비교

• 순차 처리: 50개 테스트 × 5분 = 250분 (약 4시간)
• 병렬 처리 (12개 에이전트): 50개 테스트 ÷ 12 ≈ 4.2개/에이전트 × 5분 = 약 21분
• 효율 향상: 약 12배 속도 향상

실제로는 일부 그룹이 더 빨리 완료되고, 메인 에이전트의 조율 시간이 추가되므로 정확히 12배는 아니지만, 최소 10배 이상의 생산성 향상을 체감할 수 있습니다.

4단계: 테스트 실행 및 결과 확인

모든 테스트 코드가 생성되면, Playwright를 실행하여 테스트를 수행합니다:

npx playwright test person-page

Playwright는 생성된 55개의 테스트를 7개의 워커(worker)로 병렬 실행합니다. 테스트 결과를 확인하면:

• 통과: 대부분의 테스트가 성공적으로 통과
• 실패: 일부 테스트에서 타임아웃, 셀렉터 불일치 등의 이유로 실패

왜 일부 테스트가 실패하는가?

Generator 에이전트가 최선을 다해 코드를 작성하지만, 다음과 같은 이유로 일부 테스트는 실패할 수 있습니다:

• 네트워크 타이밍: API 응답이 예상보다 느려서 타임아웃 발생
• 동적 셀렉터: 렌더링 시점에 따라 셀렉터가 변경되는 경우
• 데이터 의존성: 테스트 데이터가 예상과 다른 경우
• UI 변경: 코드 작성 후 UI가 약간 변경된 경우

이런 실패를 수동으로 하나씩 디버깅하고 수정하는 것은 매우 번거롭습니다. 여기서 Healer 에이전트가 등장합니다.

5단계: Healer 에이전트로 실패한 테스트 자동 복구

실패한 테스트를 자동으로 수정하기 위해 Healer 에이전트를 호출합니다:

실패한 테스트 케이스에 대해서 playwright-healer 에이전트를 사용해서 수정해줘.
Healer 에이전트는 병렬로 띄워서 처리해.

Healer 에이전트의 작동 방식

1. 실패한 테스트 식별: Playwright 실행 결과를 파싱하여 실패한 테스트 파일과 에러 메시지 추출
2. 에러 원인 분석: 각 실패 유형을 분류
   • 타임아웃 → 대기 시간 증가 또는 대기 조건 변경
   • 셀렉터 불일치 → 브라우저에서 실제 요소 확인 후 셀렉터 수정
   • Assertion 실패 → 예상값과 실제값 비교하여 로직 수정
3. 코드 수정: 원인에 맞는 수정 적용
4. 재검증: 수정한 테스트를 다시 실행하여 통과 확인

병렬 복구 실행

실패한 테스트가 8개 파일에 분산되어 있다면, 메인 에이전트는 8개의 Healer 서브 에이전트를 동시에 실행합니다. 각 Healer는 할당받은 파일의 실패한 테스트만 집중적으로 처리합니다.

예를 들어 타임아웃으로 실패한 테스트의 경우:

수정 전:

test('영화 상세 정보가 표시된다', async ({ page }) => {
  await page.goto('/movie/123');
  const title = page.getByRole('heading', { level: 1 });
  await expect(title).toBeVisible(); // 타임아웃 발생
});

Healer 에이전트가 적용한 수정:

test('영화 상세 정보가 표시된다', async ({ page }) => {
  await page.goto('/movie/123');
  await page.waitForLoadState('networkidle'); // API 응답 대기 추가
  const title = page.getByRole('heading', { level: 1 });
  await expect(title).toBeVisible({ timeout: 10000 }); // 타임아웃 연장
});

복구 결과

모든 Healer 에이전트가 작업을 완료한 후, 테스트를 다시 실행하면:

npx playwright test person-page

결과: 55개 테스트 모두 통과 ✅

이제 완전히 작동하는 E2E 테스트 스위트(suite)가 완성되었습니다. 처음부터 끝까지 사람이 직접 코드를 작성하지 않고도, 세 가지 에이전트가 협력하여 포괄적이고 안정적인 테스트를 구축했습니다.

병렬 처리의 핵심: 의존성 관리와 컨텍스트 격리

서브 에이전트를 병렬로 실행하여 생산성을 극대화하려면, 두 가지 핵심 원칙을 이해하고 적용해야 합니다.

의존성 관리: 안전한 병렬 실행을 위한 그룹화

의존성 충돌 예시

다음 두 테스트를 동시에 실행한다고 가정해 봅시다:

• 테스트 A: 사용자가 영화를 “좋아요” 리스트에 추가
• 테스트 B: 사용자의 “좋아요” 리스트가 비어 있는지 확인

만약 테스트 A와 B가 동시에 실행되면, 테스트 B는 A가 추가한 영화 때문에 실패할 수 있습니다. 이런 충돌을 방지하려면:

해결 방법 1: 그룹 분리

상태를 변경하는 테스트(A)와 상태를 확인하는 테스트(B)를 다른 그룹으로 분리하여, 서로 다른 에이전트가 순차적으로 실행하도록 합니다.

해결 방법 2: 격리된 데이터 사용

각 테스트가 독립적인 사용자 계정이나 테스트 데이터를 사용하도록 설정합니다. 예를 들어 테스트 A는 user-001 계정을, 테스트 B는 user-002 계정을 사용하면 충돌이 발생하지 않습니다.

그룹화 기준 정리

상황	병렬 가능 여부	그룹화 전략
읽기 전용 테스트	✅ 가능	모두 동일 그룹
다른 페이지 테스트	✅ 가능	페이지별 그룹
다른 사용자 계정 사용	✅ 가능	동일 그룹 가능
동일 리소스 수정	❌ 불가능	별도 그룹 (순차 실행)
선행 조건이 있는 테스트	❌ 불가능	의존 순서대로 그룹화

컨텍스트 격리: 메인 에이전트의 컨텍스트 절약

Claude Code를 포함한 모든 LLM은 컨텍스트 윈도우 한계를 가지고 있습니다. 하나의 세션에서 너무 많은 정보를 다루면 컨텍스트가 고갈되어 더 이상 작업을 진행할 수 없습니다.

문제 상황: 메인 에이전트에서 모든 작업 수행

만약 메인 에이전트가 50개의 테스트를 모두 직접 작성한다면:

1. 각 테스트 시나리오 분석 → 컨텍스트 사용
2. 브라우저 실행 로그 → 컨텍스트 사용
3. 생성된 코드 → 컨텍스트 사용
4. 에러 메시지와 수정 과정 → 컨텍스트 사용

50개의 테스트를 모두 처리하기도 전에 컨텍스트 한계에 도달합니다.

해결: 서브 에이전트로 컨텍스트 분산

서브 에이전트를 사용하면:

• 메인 에이전트: 오케스트레이션만 담당 (“Generator 12개 실행”, “Healer 8개 실행” 등의 메타 정보만 보유)
• 각 서브 에이전트: 자신의 독립적인 컨텍스트에서 상세 작업 수행

예를 들어:

• 메인 에이전트 컨텍스트: “그룹 1은 Generator-1에게 할당, 그룹 2는 Generator-2에게 할당…”
• Generator-1 컨텍스트: “그룹 1의 5개 시나리오 분석, 브라우저 실행, 코드 생성…”
• Generator-2 컨텍스트: “그룹 2의 4개 시나리오 분석, 브라우저 실행, 코드 생성…”

이렇게 하면 메인 에이전트는 컨텍스트를 최소한으로만 사용하고, 실제 작업 부담은 서브 에이전트들이 분산하여 처리합니다.

컨텍스트 사용량 비교

방식	메인 컨텍스트 사용량	전체 작업 가능 규모
메인 에이전트만 사용	100%	제한적 (10~20개 테스트)
서브 에이전트 사용	10~20% (조율만)	대규모 (50~100개 이상)

이것이 서브 에이전트가 대규모 작업에 필수적인 이유입니다.

실무 적용 시 고려사항과 Best Practice

1. 에이전트 선택 기준: 언제 서브 에이전트를 써야 하는가

서브 에이전트를 사용하면 좋은 경우:

• 반복적이고 독립적인 작업이 10개 이상
• 작업이 명확한 단계로 분리 가능 (기획 → 구현 → 검증)
• 병렬 처리로 속도 향상이 필요
• 컨텍스트 윈도우가 부족할 것으로 예상
• 테스트 작성, 문서 생성, 반복 리팩토링 등 프로덕션에 직접 영향이 적은 작업

메인 에이전트만 사용하면 되는 경우:

• 작업이 3~5개 이하로 단순
• 작업 간 강한 의존성이 있어 순차 실행 필수
• 실시간 피드백과 조율이 빈번히 필요
• 프로덕션 코어 로직 작성처럼 신중한 검토가 필요

2. Ralph Loop 모드 활용 전략

Ralph Loop 모드는 강력하지만, 모든 상황에 적합하지는 않습니다.

Ralph Loop 모드를 써도 안전한 경우:

• 테스트 코드 작성 (프로덕션 코드에 영향 없음)
• 문서 생성
• 스크립트나 도구 개발
• 리팩토링 후 기존 테스트로 검증 가능한 작업

Ralph Loop 모드를 피해야 하는 경우:

• 데이터베이스 마이그레이션
• 프로덕션 API 엔드포인트 수정
• 인프라 설정 변경
• 보안 관련 코드

권장 접근:

초기에는 Ralph Loop 없이 한두 번의 작업을 직접 확인하며 에이전트의 동작을 이해한 후, 패턴이 안정적이라고 판단되면 Ralph Loop을 활성화하세요.

3. 에러 처리 및 복구 전략

Healer 에이전트가 해결하지 못하는 경우

Healer 에이전트도 완벽하지 않습니다. 다음과 같은 상황에서는 수동 개입이 필요할 수 있습니다:

• 근본적인 버그: 테스트 코드가 아니라 애플리케이션 자체에 버그가 있는 경우
• 잘못된 테스트 설계: 테스트 시나리오 자체가 잘못 기획된 경우
• 환경 문제: 테스트 환경 설정이나 데이터 준비가 부족한 경우

이런 경우 Healer는 여러 번 시도 후 실패를 보고합니다. 개발자는 실패 원인을 분석하고, Planner 단계로 돌아가 시나리오를 수정하거나 애플리케이션 버그를 먼저 해결해야 합니다.

점진적 복구 전략

1. 1차 복구: Healer 에이전트 자동 실행
2. 2차 복구: 실패한 테스트만 수동 검토 후 Healer 재시도
3. 3차 복구: 시나리오 재검토 또는 애플리케이션 수정

4. 지속 가능한 테스트 유지 전략

테스트는 한 번 작성하고 끝이 아니라, 애플리케이션과 함께 지속적으로 유지보수되어야 합니다.

정기적인 Healer 실행

UI 변경이나 기능 수정 후 기존 테스트가 깨질 수 있습니다. CI/CD 파이프라인에서 테스트 실패가 감지되면, Healer 에이전트를 자동으로 실행하도록 설정할 수 있습니다.

점진적 확장

처음부터 모든 페이지와 기능을 테스트하려고 하지 마세요. 다음 순서로 점진적으로 확장하는 것이 좋습니다:

1. 핵심 사용자 플로우 (예: 로그인, 주문, 결제)
2. 자주 깨지는 기능 (예: 폼 검증, 파일 업로드)
3. Edge Case (예: 에러 처리, 빈 상태)
4. 전체 기능

에이전트 설정 개선

프로젝트를 진행하며 에이전트 설정 파일을 지속적으로 개선하세요:

• 반복되는 에러 패턴을 Healer에 학습
• 프로젝트의 컴포넌트 패턴을 Generator에 반영
• 자주 테스트하는 시나리오를 Planner에 템플릿화

5. 팀 협업과 에이전트 공유

에이전트 설정 파일(.claude/agents/)을 Git 저장소에 커밋하여 팀원과 공유하세요. 이렇게 하면:

• 팀 전체가 동일한 테스트 생성 프로세스를 사용
• 에이전트 설정 개선이 팀 전체에 즉시 반영
• 코드 리뷰와 함께 테스트 자동화 전략도 리뷰 가능

실전 예제: 다른 프로젝트에 적용하기

영화 정보 사이트 외에도 서브 에이전트는 다양한 프로젝트에 적용할 수 있습니다. 몇 가지 예를 살펴보겠습니다.

E-Commerce 사이트

Planner가 도출할 시나리오:

• 상품 검색 및 필터링
• 장바구니 추가/수정/삭제
• 주문 프로세스 (배송지 입력, 결제 수단 선택, 주문 확인)
• 주문 내역 조회
• 리뷰 작성 및 조회

그룹화 전략:

• 그룹 1: 상품 조회 (병렬 가능)
• 그룹 2: 장바구니 관리 (사용자별 격리)
• 그룹 3: 주문 프로세스 (순차 실행)

SaaS 대시보드

Planner가 도출할 시나리오:

• 로그인/로그아웃
• 대시보드 위젯 렌더링
• 데이터 필터링 및 정렬
• 설정 페이지 수정
• API 키 생성 및 관리

그룹화 전략:

• 그룹 1: 읽기 전용 위젯 (병렬 가능)
• 그룹 2: 사용자 설정 (계정별 격리)
• 그룹 3: API 키 관리 (순차 실행)

소셜 미디어 플랫폼

Planner가 도출할 시나리오:

• 피드 렌더링 및 무한 스크롤
• 게시물 작성/수정/삭제
• 좋아요 및 댓글
• 팔로우/언팔로우
• 알림 표시

그룹화 전략:

• 그룹 1: 피드 조회 (병렬 가능)
• 그룹 2: 게시물 CRUD (사용자별 격리)
• 그룹 3: 인터랙션 (병렬 가능, 게시물별 격리)

서브 에이전트의 확장 가능성: 테스트를 넘어서

이 글에서는 E2E 테스트 자동화에 초점을 맞췄지만, 서브 에이전트의 활용 범위는 훨씬 넓습니다.

1. 다국어 지원 자동화

구조:

• Extractor 에이전트: 코드에서 모든 하드코딩된 텍스트 추출
• Translator 에이전트: 텍스트를 여러 언어로 번역 (병렬 실행)
• Applier 에이전트: 번역된 텍스트를 i18n 파일로 적용

2. 문서 생성 자동화

구조:

• Analyzer 에이전트: 코드베이스 분석 및 API/컴포넌트 목록 추출
• Writer 에이전트: 각 API/컴포넌트에 대한 문서 작성 (병렬 실행)
• Linker 에이전트: 문서 간 크로스 레퍼런스 생성 및 목차 구성

3. 마이그레이션 자동화

구조:

• Mapper 에이전트: 기존 코드와 새 프레임워크의 대응 관계 분석
• Converter 에이전트: 파일별로 코드 변환 (병렬 실행)
• Validator 에이전트: 변환된 코드의 동작 검증

4. 리팩토링 자동화

구조:

• Pattern Detector 에이전트: 리팩토링 대상 패턴 식별
• Refactor 에이전트: 각 패턴에 대한 리팩토링 수행 (병렬 실행)
• Test Runner 에이전트: 기존 테스트로 리팩토링 검증

직접 만든 2인 구성: 시나리오 분석가와 E2E 테스터

Planner, Generator, Healer 같은 기본 에이전트 대신, 서브 에이전트를 직접 두 개만 만들어도 같은 흐름을 만들 수 있습니다. 메인 에이전트는 오케스트레이터 역할만 하고, 분석과 구현을 서로 다른 서브 에이전트에게 나눠 맡기는 구조죠.

Claude Code 메인 에이전트
→ E2E 시나리오 분석가 서브 에이전트 (Playwright MCP로 앱을 직접 사용)
→ 테스트 시나리오 목록 생성
→ Playwright E2E 테스터 서브 에이전트 여러 개 병렬 실행
→ 테스트 코드 통합 → 실행 및 실패 수정

시나리오 분석가는 테스트 코드를 바로 쓰지 않습니다. 메모 CRUD, 검색, 필터링처럼 사용자가 어떤 기능을 어떤 순서로 쓰는지 먼저 관찰하고, 테스트해야 할 흐름을 정리하는 게 이 단계의 핵심입니다.

병렬로 맡길 때는 경계와 데이터 격리를 같이 알려준다

서브 에이전트를 설명 필드로 자동 호출하게 두기보다, 역할 이름을 명시해서 부르는 편이 결과가 안정적입니다. 그리고 병렬로 띄울 때는 에이전트마다 맡을 범위와 테스트 데이터 규칙을 같이 적어줘야 합니다. 여러 에이전트가 같은 서비스에서 동시에 데이터를 만들고 지우면, 한 테스트가 만든 메모를 다른 테스트가 삭제하는 식으로 검증이 꼬이거든요.

세 개의 Playwright E2E 테스터 서브 에이전트를 병렬로 실행해 줘.
각 에이전트는 서로 다른 테스트 파일을 작성하고,
테스트 데이터 이름에는 고유 접두사를 붙여 충돌을 피해야 해.

제가 말하고 싶은 건 이겁니다. 병렬 에이전트 워크플로우에서는 작업을 나누는 것만큼 의존성을 분리하는 게 중요합니다. 고유한 테스트 데이터, 독립된 fixture, 시나리오별 격리 상태가 없으면 병렬화가 오히려 실패를 늘립니다.

마치며: 시스템으로 생각하는 AI 활용

Claude Code의 서브 에이전트는 단순히 “AI를 더 많이 쓰는 방법”이 아닙니다. 제가 말하고 싶은 건, 이게 개발 워크플로우를 시스템으로 설계하는 방식이라는 점입니다. 역할을 전문화하고, 작업을 병렬화하고, 컨텍스트를 효율적으로 관리하면, 사람 혼자서는 몇 시간이 걸릴 작업을 몇 분 안에 끝낼 수 있습니다.

핵심 원칙 요약:

1. 역할 전문화: 하나의 에이전트는 하나의 명확한 역할만 수행
2. 병렬 처리: 의존성이 없는 작업은 동시에 실행하여 속도 극대화
3. 컨텍스트 격리: 메인 에이전트는 조율만, 상세 작업은 서브 에이전트가 분산 처리
4. 안전한 그룹화: 의존성 충돌을 방지하는 전략적 그룹화
5. 지속 가능성: 한 번 설정하면 계속 개선하며 사용할 수 있는 구조

실천 단계:

1. 현재 프로젝트에서 가장 반복적이고 시간이 오래 걸리는 작업 하나를 선택하세요 (예: 가장 자주 깨지는 기능의 테스트).
2. 해당 작업을 3단계로 나눌 수 있는지 확인하세요 (기획 → 실행 → 검증).
3. 각 단계를 담당할 에이전트를 설정하세요 (기존 Playwright 에이전트를 참고하거나 수정).
4. 작은 범위에서 먼저 시도하고, 성공하면 점진적으로 확장하세요.
5. 팀원과 에이전트 설정을 공유하고, 함께 개선하세요.

서브 에이전트를 활용하면 테스트 작성은 더 이상 부담스러운 작업이 아닙니다. 자동화된 파이프라인에서 자연스럽게 나오는 산출물이 되죠. 이게 바로 AI 시대의 개발 생산성을 10배 이상 높이는 핵심 전략이라고 봅니다.

지금 바로 Claude Code를 열고, 여러분의 개발 파이프라인을 서브 에이전트로 한번 설계해 보면 좋겠습니다.

---

관련 영상

이 글과 연결된 영상은 개발동생 유튜브 채널에서 보기에서 확인할 수 있습니다.

시나리오 분석가와 E2E 테스터 2인 구성은 이전 영상에서 다뤘습니다.