바이브 코딩 에이전트 가이드: 서브에이전트, 팀, 커스텀 에이전트까지

바이브 코딩 도구를 쓰다 보면 하나의 AI가 모든 걸 처리하기 어려운 순간이 온다. 코드를 수정하면서 동시에 다른 파일을 탐색해야 하거나, 서버와 클라이언트를 동시에 고쳐야 하거나, 대규모 리팩토링을 하면서 기존 코드를 안전하게 보존해야 할 때가 그렇다.

이럴 때 등장하는 것이 에이전트다. 에이전트는 메인 AI와 별도로 동작하는 특화된 AI 인스턴스로, 독립적인 컨텍스트를 가지고 특정 작업을 수행한다. Claude Code와 Codex 모두 에이전트를 지원하며, 이를 잘 활용하면 복잡한 작업을 훨씬 효율적으로 처리할 수 있다.

에이전트란 무엇인가

에이전트는 메인 AI와 별개로 동작하는 독립적인 AI 인스턴스다. 메인 AI가 총괄 지휘관이라면, 에이전트는 특정 임무를 맡은 병사에 가깝다.

에이전트가 필요한 이유:• 컨텍스트 보호: 메인 대화의 컨텍스트를 오염시키지 않고 별도 작업을 수행할 수 있다. 예를 들어 대규모 코드베이스를 탐색하면 컨텍스트가 빠르게 차는데, 에이전트에게 탐색을 맡기면 메인 컨텍스트는 깨끗하게 유지된다.
• 병렬 처리: 여러 에이전트가 동시에 서로 다른 작업을 수행할 수 있다. 한 에이전트가 서버 코드를 수정하는 동안, 다른 에이전트가 클라이언트 코드를 수정하는 식이다.
• 역할 분리: 탐색 전용, 코드 수정 전용, 리뷰 전용 등 역할을 나누면 각 에이전트가 자기 역할에 집중할 수 있다.

현재 바이브 코딩 도구에서 에이전트는 크게 두 가지 형태로 제공된다. 서브에이전트(단방향, 태스크 기반)와 에이전트 팀(양방향, 협업 기반)이다.

서브에이전트

서브에이전트는 메인 AI가 특정 작업을 위해 생성하는 일회성 에이전트다. Claude Code에서는 Task 도구를 통해, Codex에서도 유사한 방식으로 동작한다.

동작 방식:1. 메인 AI가 서브에이전트에게 프롬프트(지시)를 전달
2. 서브에이전트가 독립적인 컨텍스트에서 작업 수행
3. 작업이 끝나면 결과를 메인 AI에게 보고
4. 서브에이전트 종료

핵심은 단방향 구조라는 점이다. 메인 → 서브로 지시를 내리고, 서브 → 메인으로 결과를 보고한다. 서브에이전트끼리 직접 대화하거나, 작업 중에 메인에게 질문을 던지는 건 불가능하다.

빌트인 서브에이전트 타입:• Explore: 코드베이스 탐색 전용. 파일 구조 파악, 특정 함수 찾기, 코드 흐름 분석 등에 사용한다. 읽기만 가능하고 수정은 불가능하다.
• Plan: 작업 계획 수립 전용. 구현 방안을 설계하고 단계별 계획을 세운다. 코드를 읽을 수 있지만 수정은 하지 않는다.

# 메인 AI가 서브에이전트를 사용하는 흐름 예시

메인 AI: "이 프로젝트의 인증 로직이 어디에 있는지 찾아줘"
  └─ Explore 서브에이전트 생성
     ├─ src/ 디렉토리 탐색
     ├─ auth 관련 파일 검색
     └─ 결과 보고: "src/auth/login.ts에 인증 로직이 있습니다"

메인 AI: 보고 받은 정보를 바탕으로 코드 수정 진행

서브에이전트는 가볍고 빠르다. 컨텍스트를 별도로 관리하므로 메인 대화가 오염되지 않고, 작업이 끝나면 자동으로 정리된다. 단순한 탐색이나 독립적인 작업에 적합하다.

AGENTS.md로 커스텀 에이전트 만들기

빌트인 타입(Explore, Plan) 외에 나만의 에이전트를 정의할 수 있다. AGENTS.md 파일에 에이전트의 이름, 사용할 모델, 허용할 도구, 역할 등을 지정하면 된다.

파일 위치:• 프로젝트별: .claude/agents/에이전트이름.md
• 글로벌(모든 프로젝트 공통): ~/.claude/agents/에이전트이름.md

파일 구조:

name: Worker
model: opus
allowed_tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
permission_mode: default

# Worker

## 역할
- 코드 및 데이터 수정 전용
- 커밋, 빌드, 배포는 하지 않음

## 규칙
- 지시받은 파일만 수정할 것
- 수정 후 결과를 보고할 것

YAML 프론트매터 부분이 에이전트의 설정이고, 그 아래 마크다운 본문이 에이전트에게 전달되는 시스템 프롬프트다.

주요 설정 항목:• name: 에이전트 이름. Task 도구에서 이 이름으로 호출한다.
• model: 사용할 모델. opus, sonnet, haiku 등. 역할에 따라 적절한 모델을 선택하면 비용을 절약할 수 있다.
• allowed_tools: 이 에이전트가 사용할 수 있는 도구 목록. 예를 들어 탐색 전용 에이전트는 Read, Glob, Grep만 허용하고 Write, Edit는 제외할 수 있다.
• permission_mode: 권한 모드. default는 위험한 작업에 확인을 요청하고, bypassPermissions는 모든 작업을 자동 승인한다.

Codex의 경우:Codex에서는 codex.md 파일의 [agents] 섹션에서 유사하게 에이전트를 정의할 수 있다. 문법은 다르지만 개념은 동일하다.

커스텀 에이전트를 잘 정의하면 반복적인 작업을 표준화할 수 있다. 예를 들어 "Worker는 코드만 수정하고 절대 커밋하지 않는다", "Reviewer는 코드를 읽기만 하고 수정하지 않는다" 같은 규칙을 에이전트 정의에 넣어두면, 실수로 역할을 벗어나는 상황을 방지할 수 있다.

에이전트 팀

에이전트 팀은 Claude Code의 실험적 기능으로, 여러 에이전트가 동시에 활동하며 양방향으로 소통하는 멀티에이전트 시스템이다. 서브에이전트의 "지시 → 보고" 단방향 구조와 달리, 팀원 에이전트들이 서로 메시지를 주고받으며 협업할 수 있다.

팀 구조:

팀 리드 ─┬─ Explorer     (코드베이스 탐색)
         ├─ Worker A     (클라이언트 코드 수정)
         ├─ Worker B     (서버 코드 수정)
         ├─ Reviewer     (코드 리뷰)
         └─ Utility      (빌드/커밋/배포)

핵심 특징:• 양방향 소통: 팀원끼리 직접 메시지를 주고받을 수 있다. Worker A가 Worker B에게 "API 응답 형식이 어떻게 되나요?"라고 직접 물어볼 수 있다.
• 공유 태스크 리스트: 전체 팀이 공유하는 작업 목록이 있어, 누가 어떤 작업을 하고 있는지 파악할 수 있다.
• 메일박스 메시징: 각 에이전트에게 메시지를 보내면 해당 에이전트의 메일박스에 도착한다.
• 델리게이트 모드: 팀 리드가 Shift+Tab으로 전환하는 모드. 리드가 직접 작업하지 않고 팀원에게 위임하는 데 최적화되어 있다.

팀 리드의 역할:팀 리드는 직접 코드를 수정하거나 파일을 탐색하지 않는다. 대신 작업을 분배하고, 진행 상황을 조율하고, 유저와 소통하는 허브 역할을 한다. 마치 프로젝트 매니저처럼 동작한다.

팀 워크플로우 예시:

1. 유저: "로그인 기능에 2FA를 추가해줘"
2. 리드 → Explorer: "현재 인증 코드 구조 파악해줘"
3. Explorer → 리드: "src/auth/에 로그인 로직이 있습니다"
4. 리드 → Worker A: "클라이언트에 2FA UI 추가해줘"
5. 리드 → Worker B: "서버에 2FA 검증 로직 추가해줘"
6. Worker A ↔ Worker B: "OTP 검증 API 엔드포인트 이름 뭘로 할까요?"
7. Workers → 리드: "구현 완료했습니다"
8. 리드 → 유저: "2FA 기능 추가 완료. 변경 파일은 ..."

서브에이전트 vs 에이전트 팀

두 방식은 용도가 다르다. 어떤 상황에 어떤 방식이 적합한지 비교해보자.

서브에이전트를 쓸 때:• 코드베이스를 탐색해서 정보만 가져올 때
• 독립적인 작업을 병렬로 처리할 때 (서로 의존성이 없는 작업)
• 메인 컨텍스트를 보호하면서 부가 작업을 할 때

에이전트 팀을 쓸 때:• 클라이언트 + 서버를 동시에 수정해야 할 때
• 여러 역할(개발, 리뷰, 배포)이 협업해야 할 때
• 장기간 여러 작업을 순차적으로 처리해야 할 때

실전 활용 팁

에이전트를 효과적으로 활용하기 위한 실전 팁을 정리했다.

서브에이전트 활용 팁:• 프롬프트를 구체적으로 작성하자. "코드 좀 봐줘" 대신 "src/auth/ 디렉토리에서 JWT 토큰 검증 로직을 찾아서 함수명과 파일 경로를 알려줘"가 훨씬 좋은 결과를 낸다.
• 탐색 결과가 방대할 때 Explore 서브에이전트를 쓰면 메인 컨텍스트가 오염되지 않는다. 결과 요약만 메인으로 돌아오기 때문이다.
• 서로 독립적인 탐색 작업은 여러 서브에이전트를 동시에 띄워 병렬로 처리할 수 있다.

에이전트 팀 활용 팁:• 팀 리드는 직접 일하지 말고 조율에 집중하자. 리드가 직접 파일을 수정하기 시작하면 조율 역할이 약해진다.
• 같은 파일을 여러 Worker가 동시에 수정하면 충돌이 생긴다. 파일 단위로 작업을 나누거나, 순차적으로 수정하도록 조율해야 한다.
• Utility 에이전트(빌드/커밋 담당)는 모든 Worker의 작업이 끝난 후에 동작하도록 하자.

흔한 실수:• 과도한 팀 사용: 단순한 작업에 팀을 구성하면 오버헤드만 늘어난다. 파일 하나 수정하는 데 팀을 꾸릴 필요는 없다.
• 너무 큰 태스크: 서브에이전트에게 "프로젝트 전체를 리팩토링해줘" 같은 거대한 태스크를 주면 컨텍스트가 넘치거나 결과가 부실해진다. 작은 단위로 쪼개서 지시하자.
• 역할 경계 무시: Worker가 커밋까지 하거나, Reviewer가 코드를 수정하면 혼란이 생긴다. 에이전트별 역할 경계를 명확히 정의하고 지키자.
• 커스텀 에이전트 모델 낭비: 탐색이나 단순 작업에 최상위 모델을 쓰면 비용만 늘어난다. Explorer는 Sonnet, Worker는 Opus 같이 역할에 맞는 모델을 배정하자.

마치며

에이전트는 바이브 코딩의 생산성을 한 단계 끌어올리는 핵심 기능이다. 서브에이전트로 컨텍스트를 보호하며 독립 작업을 처리하고, AGENTS.md로 프로젝트에 맞는 커스텀 에이전트를 정의하고, 에이전트 팀으로 복잡한 작업을 분할 협업할 수 있다.

처음에는 서브에이전트부터 시작하는 것을 추천한다. Explore 타입으로 코드 탐색을 위임하는 것만으로도 메인 컨텍스트를 깨끗하게 유지하는 효과를 바로 체감할 수 있다. 익숙해지면 AGENTS.md로 프로젝트에 맞는 에이전트를 정의하고, 필요할 때 에이전트 팀까지 활용하면 된다.