서브에이전트로 작업 분할·병렬화

서브에이전트 — 복잡한 작업을 나누어 정복하기

Claude Code에는 강력한 Agent 도구가 내장되어 있습니다. 하나의 대화 안에서 독립적인 서브에이전트를 생성하고, 그 결과를 취합하는 방식으로 복잡한 작업을 처리할 수 있습니다. 서브에이전트는 부모 컨텍스트를 공유하지 않는 새로운 세션으로 시작됩니다. 이 특성이 장점이자 설계 포인트입니다.

서브에이전트가 필요한 상황

• 컨텍스트 폭발 방지: 코드베이스 전체를 한 세션에 넣으면 토큰 한계에 도달합니다. 서브에이전트는 독립 컨텍스트 윈도우에서 실행되어 부모 세션의 컨텍스트를 오염시키지 않습니다.
• 병렬 실행: 독립적인 작업(마이그레이션 작성 + 컴포넌트 구현 + 테스트 생성)을 동시에 실행하면 총 소요 시간이 줄어듭니다.
• 역할 격리: "코드 분석 전문 에이전트"와 "코드 수정 전문 에이전트"를 분리하여 각자 적합한 지시를 줄 수 있습니다.

Agent 도구 기본 사용법

// Claude Code가 자체 프롬프트에서 호출하는 방식 (CLAUDE.md나 슬래시 명령에서 참조)
Agent({
  description: "TypeScript 타입 오류 수정",
  prompt: `
    app/actions/ 디렉토리의 모든 TypeScript 파일을 검사해줘.
    다음을 체크하고 수정해줘:
    1. 'any' 타입 사용 → 적절한 타입으로 교체
    2. Supabase 응답 타입 누락 → types/supabase.ts 기반으로 추가
    3. 함수 반환 타입 명시
    수정 완료 후 npx tsc --noEmit 실행해서 타입 오류 0개 확인.
  `
})

병렬 서브에이전트 패턴

독립적인 작업을 동시에 실행하는 것이 핵심입니다. 단, 서로 같은 파일을 수정하는 작업은 병렬 실행 시 충돌이 발생하므로 순차 실행해야 합니다.

// 병렬 실행 가능 — 서로 다른 파일 작업
Agent({ description: "ko.json 번역 완성", prompt: "messages/ko.json의 미번역 키를 채워줘..." })
Agent({ description: "en.json 번역 완성", prompt: "messages/en.json의 미번역 키를 채워줘..." })
Agent({ description: "ja.json 번역 완성", prompt: "messages/ja.json의 미번역 키를 채워줘..." })

// 순차 실행 필요 — 같은 파일 수정
// 1단계: DB 마이그레이션 생성
Agent({ description: "마이그레이션 파일 생성", prompt: "supabase/migrations/ 에 새 테이블 추가..." })
// 2단계: 타입 재생성 (마이그레이션 완료 후)
Agent({ description: "TypeScript 타입 갱신", prompt: "npx supabase gen types typescript..." })

서브에이전트 프롬프트 작성 원칙

서브에이전트는 부모 컨텍스트를 모릅니다. "지금까지 논의한 내용 반영해줘"는 작동하지 않습니다. 프롬프트는 자기완결적이어야 합니다.

// ❌ 나쁜 예 — 부모 컨텍스트 의존
Agent({
  prompt: "아까 얘기한 기업 대시보드 버그 수정해줘"
})

// ✅ 좋은 예 — 자기완결적
Agent({
  prompt: `
    **목표**: app/[locale]/company/dashboard/page.tsx의 통계 계산 버그 수정

    **버그 내용**: 최종합격자 집계 시 모든 stage를 포함해 계산하는 문제.
    learning_series의 selection_stages 마지막 단계를 통과한 지원자만 집계해야 함.

    **관련 파일**: 
    - app/[locale]/company/dashboard/page.tsx
    - app/actions/company.ts
    - types/supabase.ts (DB 타입 참조)

    **완료 조건**: 로직 수정 후 npm run build 에러 없음 확인
  `
})

결과 취합 패턴

// 서브에이전트가 각자 분석 후 결과 반환
const [authAnalysis, dbAnalysis, uiAnalysis] = await Promise.all([
  Agent({ description: "인증 보안 감사", prompt: "app/actions/ 인증 관련 보안 취약점 분석해서 목록 반환..." }),
  Agent({ description: "DB 쿼리 최적화", prompt: "느린 쿼리 찾아서 최적화 방안 제안..." }),
  Agent({ description: "UI 접근성 감사", prompt: "모든 페이지 컴포넌트의 접근성 문제 점검..." })
])
// 부모 에이전트가 결과 통합 후 실행 계획 수립

Worktree 격리 — 브랜치 충돌 없는 병렬 작업

같은 저장소에서 여러 서브에이전트가 파일을 동시에 수정하면 충돌이 납니다. isolation: "worktree" 옵션을 사용하면 각 에이전트가 독립된 git worktree에서 작업합니다.

// 각 에이전트가 별도 브랜치에서 작업 — 나중에 merge
Agent({
  description: "결제 모듈 구현",
  isolation: "worktree",
  prompt: "feature/payment 브랜치에서 결제 흐름 구현..."
})
Agent({
  description: "알림 시스템 구현",
  isolation: "worktree",
  prompt: "feature/notification 브랜치에서 알림 모듈 구현..."
})

서브에이전트의 진짜 가치는 "큰 작업을 작게 쪼개는 것"이 아니라 "독립적인 컨텍스트에서 전문적으로 작업하는 것"입니다. 데이터베이스 전문가, UI 전문가, 보안 전문가를 각각 고용하는 것과 같습니다 — 제너럴리스트 한 명보다 스페셜리스트 여럿이 복잡한 작업을 더 잘 처리합니다.

핵심 정리

• 서브에이전트는 독립 컨텍스트 세션 — 부모 대화 내용을 모르므로 프롬프트는 자기완결적으로 작성
• 독립적인 파일 작업은 병렬, 같은 파일 수정은 순차 실행 — isolation: "worktree"로 git 충돌 방지
• 컨텍스트 보호가 핵심 가치 — 대규모 코드베이스 작업 시 서브에이전트로 분리해 부모 세션 토큰 절약

관련 검색어  ·  클로드 코드  ·  Claude Code  ·  서브에이전트  ·  병렬 AI 작업  ·  컨텍스트 분리  ·  worktree 격리  ·  AI 작업 분할