[Claude 서브에이전트] 역할별 AI 팀 만드는 실전 가이드

안녕하세요. 재아군의 관찰인생입니다.

오늘은 Claude 서브에이전트을 현업 개발자 관점에서 정리해보겠습니다. 최근 AI 코딩 도구는 단순히 코드를 제안하는 수준을 넘어, 코드베이스를 읽고 작업을 나누고 테스트까지 돌리는 방향으로 빠르게 이동하고 있습니다.

특히 Claude Code를 쓰다 보면 “한 대화 안에서 기획, 구현, 리뷰, 테스트까지 전부 처리해도 될까?”라는 질문이 생깁니다. 이때 서브에이전트는 작업을 역할별로 나누고 컨텍스트를 분리하는 현실적인 해법이 됩니다.

Claude 서브에이전트는 특정 목적과 도구 권한, 시스템 프롬프트를 가진 보조 AI 역할입니다. 메인 대화가 모든 일을 떠안지 않도록 작업을 분리하는 구조라고 보면 됩니다.

---

1. Claude 서브에이전트을 먼저 이해해야 하는 이유

AI 코딩에서 가장 흔한 문제는 모델이 코드를 못 짜는 것이 아니라, 너무 많은 맥락을 한 번에 떠안는 것입니다. 요구사항, 코드 탐색, 구현, 테스트, 리뷰가 한 대화에 섞이면 판단 기준이 흐려지고 결과물도 들쑥날쑥해집니다.

서브에이전트는 이 문제를 역할 분리로 풀어냅니다. 예를 들어 explorer는 코드 구조를 읽고, worker는 제한된 파일만 수정하고, reviewer는 diff 중심으로 위험을 찾게 만들 수 있습니다.

• 컨텍스트 오염을 줄여 메인 대화의 판단을 선명하게 유지합니다.
• 역할별 도구 권한을 다르게 주어 위험한 작업을 제한할 수 있습니다.
• 반복되는 리뷰, 테스트, 문서화 작업을 재사용 가능한 패턴으로 만들 수 있습니다.
• 팀원마다 다른 프롬프트 습관을 프로젝트 표준으로 수렴시킬 수 있습니다.

구분	기존 방식	Claude 서브에이전트 적용 후
코드 탐색	메인 대화가 파일을 계속 읽으며 맥락이 커짐	explorer가 구조와 핵심 파일만 요약
구현	하나의 대화가 여러 파일을 동시에 수정	worker가 정해진 책임 범위만 수정
리뷰	작업자가 스스로 검수해 놓치는 부분 발생	reviewer가 diff와 테스트 관점으로 별도 점검

---

2. 핵심 구조와 동작 원리

서브에이전트 구조는 복잡해 보이지만 실제로는 세 가지 요소만 보면 됩니다. 이름, 호출 조건, 그리고 허용 도구입니다. 여기에 역할별 시스템 프롬프트를 붙이면 재사용 가능한 팀 규칙이 됩니다.

레이어	역할	실무에서 확인할 것
Agent Definition	에이전트 이름, 설명, 도구 목록을 정의	역할이 너무 넓지 않은지 확인
Prompt Policy	작업 방식, 금지 행동, 산출물 형식 지정	파일 수정 범위와 보고 형식 명시
Invocation	자동 호출 또는 명시적 호출로 실행	메인 대화가 결과를 어떻게 통합할지 결정

이 구조를 이해하면 AI 도구를 “똑똑한 채팅창”으로만 쓰지 않고, 팀의 개발 프로세스 안에 넣을 수 있습니다. 중요한 것은 모델 성능보다 작업 단위, 권한, 검증 루프를 먼저 설계하는 것입니다.

User Request
  -> Main Claude Code Session
    -> explorer: read and summarize codebase
    -> worker: implement scoped change
    -> reviewer: inspect diff and risks
  -> Main Session integrates result

---

3. 실무 설정 예시

프로젝트 단위로 쓰려면 `.claude/agents/` 아래에 역할별 Markdown 파일을 두는 방식이 가장 관리하기 쉽습니다. 아래는 코드 리뷰 전용 에이전트의 예시입니다.

---
name: code-reviewer
description: Review recent code changes and find bugs, regressions, and missing tests
tools: Read, Grep, Bash
---

You are a senior code reviewer. Focus on behavioral bugs, security risks, and missing tests.
Report findings first with file and line references. Do not rewrite code unless asked.

구현 담당 에이전트는 리뷰어와 반대로 파일 수정 도구가 필요합니다. 대신 책임 범위를 좁혀서 “인증 모듈만 수정”, “테스트 파일만 추가”처럼 충돌 가능성을 줄여야 합니다.

> Use the code-reviewer subagent to review my latest changes
> Use the frontend-worker subagent to update only the dashboard UI files

작게 시작하는 적용 순서

1. 가장 자주 반복되는 작업 하나를 고릅니다.
2. 그 작업의 성공 기준과 금지 행동을 문장으로 적습니다.
3. 읽기 전용 에이전트부터 만들어 위험을 낮춥니다.
4. 수정 권한이 필요한 worker는 파일 범위를 좁혀서 운영합니다.
5. 팀에서 좋은 결과가 나온 프롬프트만 프로젝트 에이전트로 승격합니다.

---

4. 팀 워크플로우에 넣는 방법

실무에서는 서브에이전트를 “많이 만드는 것”보다 “일의 경계가 분명하게 만드는 것”이 중요합니다. 하나의 에이전트가 기획, 구현, 테스트, 배포 판단을 모두 맡으면 다시 만능 대화창으로 돌아갑니다.

제가 추천하는 기본 조합은 explorer, worker, reviewer 세 가지입니다. 여기에 문서화가 많은 팀은 docs-writer를 추가하고, 보안 민감도가 높은 팀은 security-reviewer를 별도로 둡니다.

상황	추천 역할	주의점
새 코드베이스 파악	explorer	수정 도구 없이 읽기와 검색 중심
작은 기능 구현	worker	소유 파일과 테스트 명령을 명확히 지정
배포 전 점검	reviewer	버그와 누락 테스트를 먼저 보고

• 에이전트 설명은 “언제 호출해야 하는지”가 드러나야 합니다.
• 도구 권한은 필요한 만큼만 열어둡니다.
• 결과 형식은 짧고 반복 가능해야 합니다.
• 작업 후 메인 세션이 통합 판단을 하도록 둡니다.

---

5. 경쟁 도구와 비교해서 보는 포인트

Claude 서브에이전트는 로컬 또는 Claude Code 중심 워크플로우에서 강합니다. 반면 Codex와 Copilot 에이전트는 클라우드 작업, PR 자동화, GitHub 이슈 기반 흐름에서 장점이 있습니다.

도구	강점	아쉬운 점	추천 사용처
Claude 서브에이전트	역할 분리와 컨텍스트 관리가 강함	설계를 잘못하면 에이전트가 난립함	복잡한 로컬 코드베이스 분석과 팀 규칙 표준화
Codex	백그라운드 병렬 작업과 코드 변경에 강함	작업 단위가 흐리면 결과 검수가 어려움	여러 후보 구현, 버그 수정, 테스트 추가
Copilot 에이전트	GitHub 이슈와 PR 흐름에 자연스럽게 붙음	GitHub 중심 조직이 아니면 장점이 줄어듦	이슈 기반 변경 요청과 PR 반복 수정

비교의 핵심은 “어떤 도구가 최고인가”가 아니라 “어떤 작업을 맡길 때 실패 비용이 낮은가”입니다. 같은 기능 구현이라도 로컬 탐색, 클라우드 병렬 작업, GitHub 중심 PR 자동화는 운영 방식이 꽤 다릅니다.

---

6. 도입 전 체크리스트와 흔한 실수

서브에이전트 도입에서 가장 위험한 패턴은 “역할 이름만 다르고 프롬프트는 비슷한” 에이전트를 많이 만드는 것입니다. 역할이 겹치면 호출 기준이 흐려지고 유지보수 비용만 늘어납니다.

체크 항목	좋은 기준	실패 신호
권한	읽기 전용과 수정 가능 역할을 분리	모든 에이전트가 Bash/Edit 권한 보유
범위	파일, 모듈, 산출물 기준이 명확	어떤 작업이든 맡길 수 있다고 설명
검증	테스트 명령과 리뷰 기준 포함	완료 보고만 있고 검증 흔적 없음

자주 생기는 실수

• 에이전트 이름을 직무명처럼 넓게 짓는 실수
• 수정 권한이 있는 에이전트에게 파일 범위를 주지 않는 실수
• 리뷰어가 코드 작성까지 하도록 허용하는 실수
• 좋은 프롬프트를 개인 환경에만 두고 프로젝트에 공유하지 않는 실수

---

7. 앞으로의 발전 방향

앞으로 AI 코딩 도구는 단일 모델 성능 경쟁보다 작업 분배와 검증 체계 경쟁으로 이동할 가능성이 큽니다. 서브에이전트는 이 변화의 가장 현실적인 시작점입니다.

특히 대규모 코드베이스에서는 전체 맥락을 한 번에 넣는 방식보다, 역할별로 필요한 맥락만 읽게 만드는 방식이 비용과 정확도 면에서 유리합니다.

• 프로젝트별 에이전트 템플릿 공유
• MCP 도구 권한과 에이전트 역할의 결합
• 리뷰 전용, 테스트 전용, 마이그레이션 전용 에이전트의 표준화
• 에이전트 실행 로그를 통한 팀 품질 관리

---

마무리

정리하면 Claude 서브에이전트은 AI 코딩 도구를 실무 프로세스에 넣기 위한 중요한 퍼즐입니다. 처음부터 거창한 자동화를 목표로 하기보다, 반복되는 작은 작업 하나를 안정적으로 맡기는 쪽이 성공 확률이 높습니다.

첫 번째 에이전트는 거창할 필요가 없습니다. 코드리뷰 전용, 테스트 추가 전용처럼 작은 역할 하나부터 만들면 AI 코딩 경험이 훨씬 안정적으로 바뀝니다.

이 글이 도움이 되셨다면 댓글로 현재 사용 중인 AI 코딩 도구와 가장 자동화하고 싶은 작업을 남겨주세요. 다음 글에서 Claude 서브에이전트를 더 실전적인 예제로 이어가겠습니다.