클로드 코드 서브 에이전트 만들기: 업무 자동화 에이전트 설계 실전

클로드 코드 서브 에이전트란?
클로드 코드(Claude Code)에서 특정 업무에 특화된 역할과 도구 세트를 부여한 독립 실행 AI 단위. 메인 에이전트가 복잡한 작업을 위임하면 자율적으로 수행하고 결과를 반환한다. .claude/agents/ 디렉터리에 마크다운 파일을 만드는 것으로 설계가 시작된다.

단일 에이전트 하나로 충분한가

코드베이스를 분석하면서 동시에 문서를 작성하고, 테스트를 실행하고, 슬랙에 알림까지 보내야 하는 업무를 단일 에이전트가 순서대로 처리한다면 어떻게 될까. 불가능하진 않다. 하지만 맥락이 길어질수록 응답 품질이 흐려지고, 병렬 처리가 없으니 시간도 선형으로 늘어난다.

클로드 코드의 서브 에이전트 시스템은 이 구조적 문제를 역할 분화로 푼다. 각 에이전트에 필요한 도구만 부여하고, 작업을 병렬로 위임한다. 사람이 일을 분업하는 것과 같은 원리다.

다만 에이전트를 쪼개는 게 항상 정답은 아니다. 단순 작업에 서브 에이전트를 붙이면 조율 비용이 더 늘고 토큰 소비도 배가된다. 무엇을 분리할 가치가 있는지 먼저 따져보는 게 순서다.

클로드 코드 서브 에이전트 작동 방식

클로드 코드는 두 가지 방식으로 서브 에이전트를 지원한다.

첫 번째는 빌트인 에이전트 타입이다. Explore(파일 탐색 전용), Plan(아키텍처 설계), general-purpose(범용), code-reviewer 같은 에이전트가 기본 제공된다. 각각 접근 가능한 도구와 시스템 프롬프트가 미리 정의돼 있어, 별도 설정 없이 바로 호출할 수 있다.

두 번째는 커스텀 에이전트다. 프로젝트의 .claude/agents/ 디렉터리 또는 글로벌 ~/.claude/agents/ 경로에 마크다운 파일을 만들면 된다. 파일 하나가 에이전트 하나다.

에이전트 파일 구조

커스텀 에이전트 파일은 YAML 프론트매터와 시스템 프롬프트 두 부분으로 구성된다. 아래는 SQL 쿼리 최적화 에이전트의 예시다.

---
description: >
  PostgreSQL 쿼리 최적화 전문가. 슬로우 쿼리 분석, 인덱스 전략
  제안, EXPLAIN ANALYZE 해석이 필요할 때 호출한다. 쿼리 수정은
  직접 하지 않고 개선 방향만 반환한다.
tools:
  - Read
  - Bash
model: claude-haiku-4-5
---

당신은 PostgreSQL 쿼리 최적화 전문가입니다.
주어진 쿼리의 실행 계획을 분석하고, 인덱스 전략과 리팩토링 방안을
구체적으로 제시하세요. EXPLAIN ANALYZE 결과를 반드시 확인하고,
개선 전후 예상 성능 차이를 수치로 표현하세요.
분석만 수행하고 파일을 직접 수정하지 마세요.

이 파일을 .claude/agents/sql-optimizer.md로 저장하면 메인 에이전트에서 subagent_type: "sql-optimizer"로 바로 호출된다.

프론트매터 핵심 항목

업무 자동화 에이전트 설계 패턴 4가지

실제 업무에 적용하다 보면 반복적으로 등장하는 구조가 있다.

1. 리서치-작성 분리 패턴

리서치 에이전트가 정보를 수집하면, 별도의 작성 에이전트가 콘텐츠를 만든다. 두 역할이 분리되면 각각의 시스템 프롬프트를 더 날카롭게 설계할 수 있다. 리서치 에이전트는 수집과 검증에만, 작성 에이전트는 구조화와 표현에만 집중한다. 같은 에이전트가 리서치와 작성을 모두 하면 수집 단계의 편향이 작성 결과에 그대로 녹아든다.

2. 검토-수정 루프 패턴

코드 리뷰 에이전트가 문제를 발견하고, 수정 에이전트가 처리한다. 같은 에이전트가 자기 작성물을 검토하면 anchoring 효과로 문제를 놓치기 쉽다. 역할을 분리해 검토자가 결과물만 받으면 이 편향이 줄어든다. 특히 비판적 판단이 필요한 단계에서 이 패턴이 유효하다.

3. 병렬 탐색 패턴

대형 코드베이스에서 여러 파일을 동시에 분석해야 할 때 쓴다. 탐색 에이전트 N개를 동시에 실행하고 결과를 취합하면 순서대로 처리할 때보다 전체 시간이 크게 줄어든다. 단, 각 에이전트가 독립적으로 작업 가능한 경우에만 효과적이다. 서로 의존하는 파일들을 병렬로 분석하면 결과가 어긋난다.

4. 격리 실행 패턴

파일을 수정하는 에이전트 여러 개가 동시에 작업하면 충돌이 생긴다. isolation: "worktree" 옵션을 지정하면 에이전트마다 별도의 git worktree에서 작업하고 완료 후 결과를 합친다. 설정 비용이 있으니 에이전트당 변경량이 충분히 클 때만 쓰는 게 맞다.

시스템 프롬프트가 에이전트 품질을 결정한다

서브 에이전트가 기대대로 동작하려면 시스템 프롬프트가 세 가지를 명확히 해야 한다.

• 역할의 경계: 이 에이전트가 하는 일과 하지 않는 일. "리뷰만 하고 수정은 하지 않는다" 같은 명시적 경계가 없으면 에이전트가 스코프 밖까지 건드린다.
• 출력 형식: 결과물을 어떤 형태로 반환해야 하는지. 메인 에이전트가 파싱하거나 후속 에이전트가 이어받을 형식이면 구조화 명세가 필요하다.
• 실패 처리 방식: 작업이 불가능하거나 정보가 부족할 때 어떻게 할지. 에이전트가 판단 없이 멈추거나 잘못된 결과를 반환하면 전체 파이프라인이 무너진다.

좋은 시스템 프롬프트는 에이전트가 "이걸 어떻게 처리해야 하지?"로 멈추는 상황을 줄인다. 판단 기준을 프롬프트 안에 심어두는 게 핵심이다.

디렉터리 스코프: 글로벌 에이전트와 프로젝트 에이전트

커스텀 에이전트는 저장 위치에 따라 적용 범위가 달라진다.

같은 이름의 에이전트가 양쪽에 있으면 프로젝트 에이전트가 우선한다. 팀 공유 에이전트는 레포에 커밋하고, 개인 작업 에이전트는 글로벌 경로에 두는 방식이 관리하기 깔끔하다.

비용과 복잡도: 도입 전에 따져볼 것

서브 에이전트를 도입하면 토큰 비용이 배수로 늘어난다. 에이전트 호출마다 독립적인 컨텍스트가 생기기 때문이다. 백그라운드 에이전트를 여러 개 띄울수록 비용 예측이 어려워진다.

디버깅도 복잡해진다. 단일 에이전트 실패는 로그를 보면 어디서 틀렸는지 바로 보이지만, 멀티 에이전트 시스템은 어느 에이전트가 잘못된 결과를 넘겼는지 역추적해야 한다.

다음 중 하나라도 해당하면 서브 에이전트 도입을 재고하는 편이 낫다.

• 작업이 단순하고 컨텍스트가 길지 않을 때
• 에이전트 간 넘겨줄 중간 결과물이 불명확할 때
• 팀이 멀티 에이전트 로그를 해석할 역량이 부족할 때
• 단발성 작업이라 설계 투자 대비 실익이 없을 때

서브 에이전트는 복잡도를 추가하는 도구다. 그 복잡도가 불가피한 문제를 풀 때 비로소 들인 비용 이상의 가치를 낸다. 처음엔 단일 에이전트로 얼마나 풀 수 있는지 먼저 테스트하고, 명확한 병목이 생기면 그때 분화를 검토하는 게 현실적인 순서다.

에이전트 시스템 도입이 실제 비즈니스 ROI로 이어지는 조건은 AI 전환 ROI: 기업이 알아야 할 경제학에서 더 깊이 다룬다.

더 읽어보기

• AI 전환 ROI: 기업이 알아야 할 경제학

자주 묻는 질문

서브 에이전트와 워크플로우(Workflow)는 어떻게 다른가?

서브 에이전트는 단일 작업 단위다. 메인 에이전트가 특정 역할을 위임할 때 쓴다. 워크플로우는 여러 에이전트를 조율하는 상위 레이어로, 병렬 실행과 파이프라인, 루프 같은 제어 흐름을 코드로 정의한다. 단순 위임이면 서브 에이전트로 충분하다. N개 에이전트를 조율하는 복잡한 자동화라면 워크플로우가 맞다. 두 개념을 구분하는 기준은 "제어 흐름을 내가 코드로 정의해야 하는가"다.

에이전트 파일의 description을 어떻게 써야 선택 정확도가 높아지는가?

클로드 코드는 description을 보고 어떤 에이전트를 호출할지 판단한다. 설명이 짧거나 모호하면 엉뚱한 에이전트가 선택되거나, 에이전트가 존재하는데도 호출되지 않는다. 세 가지를 명시하면 정확도가 올라간다. 우선 트리거 조건("슬로우 쿼리 분석이 필요할 때"), 다음으로 에이전트가 다루는 도메인("PostgreSQL 인덱스 전략"), 마지막으로 쓰면 안 되는 케이스("쿼리를 직접 수정할 필요는 없고 분석만 필요할 때")다.

서브 에이전트에 어떤 도구를 부여해야 하는가?

최소 권한 원칙을 따른다. 리서치 에이전트에 파일 쓰기 권한이 있어선 안 되고, 코드 리뷰 에이전트에 실행 권한도 없어야 한다. 도구 범위가 좁을수록 에이전트가 스코프 밖 행동을 하는 사고를 막는다. 처음엔 읽기 전용(Read, WebFetch, WebSearch)만 주고, 실제 필요가 생겼을 때 쓰기 도구를 추가하는 방식이 안전하다. 도구를 넓게 주고 시작하면 나중에 줄이기 어렵다.

클로드 코드 에이전트 설계, 팀 전체 AI 전환으로 이어지려면

서브 에이전트 설계에서 조직 단위 자동화 로드맵까지, Nitrox에서 컨설팅한다. nitrox.ai.kr에서 무료 상담을 신청하면 된다.