서브에이전트를 200% 활용하는 노하우 — description부터 병렬 실행까지

서브에이전트를 만드는 방법은 알아도 잘 쓰는 방법은 다르다. 설치했는데 자동으로 호출되지 않거나, 에이전트가 엉뚱한 작업을 하거나, 서로 간섭해서 결과가 망가지는 경우가 생긴다. 이 글은 서브에이전트를 제대로 활용하기 위한 실전 노하우를 정리한다.

노하우 1: description은 에이전트의 자동 위임 트리거다

이 다이어그램은 사용자가 .py 파일을 편집한 직후 메인 Claude가 어떤 절차로 서브에이전트 자동 호출 여부를 결정하는지 보여준다. 메인은 매 턴마다 "지금 이 상황에 맞는 에이전트가 있는가?"를 묻는데, 그 판단 근거가 바로 등록된 모든 에이전트의 description 필드다. 즉 description은 "이 에이전트가 무슨 일을 하는가"라기보다 "언제 나를 호출해야 하는가"의 트리거 규칙으로 작동한다.

description이 모호하면 에이전트가 자동으로 호출되지 않는다. 아무리 잘 만든 에이전트라도 description이 나쁘면 사용자가 직접 "@에이전트명"으로 불러야만 한다. 자동 위임 흐름이 멈추는 곳은 항상 매칭 판단 노드이고, 그 노드의 입력은 오직 description뿐이다.

▲ ❌ 트리거 안 되는 description

위의 세 가지가 왜 자동 호출에 실패하는지 살펴보자. "코드를 리뷰한다"는 "언제"가 빠져 있다. 메인이 매 상황마다 "지금이 리뷰 시점인가?"를 판단할 단서가 없다. "보안 검사기"는 한국어인 데다 명사형이라 행위·조건이 드러나지 않는다 — 메인의 내부 분류기는 영어 동사 구문("Use when ...", "Reviews ...")에 훨씬 강하게 반응한다. "좋은 에이전트"는 그저 자기 자랑일 뿐 의미가 비어 있다. 이런 description은 결국 사용자가 매번 손으로 호출해야 한다.

▲ ✅ 트리거 잘 되는 description

세 예시 모두 "Use proactively + 시점/조건 + 행위"의 동일한 골격을 따른다. 첫 예시는 ".py·.sh·.html 편집 직후"라는 파일 타입 트리거를 명시했고, 두 번째는 "사용자가 Python 에러를 신고했을 때"라는 사용자 발화 트리거, 세 번째는 "auth·network·subprocess를 다루는 코드"라는 키워드 트리거다. 메인 Claude는 현재 상황(어떤 파일을 편집했는지, 사용자가 무슨 말을 했는지, 직전 도구가 무엇이었는지)을 이 세 종류의 트리거와 대조해서 매칭 여부를 정한다.

좋은 description의 3요소: ① 영어로 작성 (한국어보다 판단 정확도 높음), ② "Use proactively when/after ..." 패턴으로 트리거 조건 명시, ③ 에이전트가 하는 일을 동사로 설명. 셋 중 하나라도 빠지면 매칭 신뢰도가 급격히 떨어진다.

노하우 2: tools 제한으로 에이전트의 안전 경계를 만든다

tools 필드의 본질은 권한 부여가 아니라 안전 경계 설정이다. 코드 리뷰어처럼 "결과를 보고만 하는" 에이전트는 Edit을 빼두면, LLM이 도중에 "겸사겸사 수정해드릴까요?"라며 파일을 건드릴 가능성 자체가 차단된다. 반대로 파이썬 디버거처럼 "원인 분석 + 수정"이 한 묶음인 에이전트는 Edit이 필수다. 핵심 원칙은 capability-based security — 할 수 없게 만들면 사고가 나지 않는다. 의사결정 분기점은 단 하나: "이 에이전트가 파일을 수정해야 하는 일을 위임받는가?"이다.

▲ 도구 최소화 원칙

도구를 줄이는 것은 안전성뿐 아니라 성능과 결과 품질에도 직결된다. 도구가 많을수록 LLM은 매번 "어떤 도구를 쓸지" 고민하는 의사결정 비용을 부담하고, 잘못된 도구를 고를 가능성도 높아진다. 예컨대 코드 리뷰어에게 WebSearch를 주면 "확인차" 검색을 돌려 토큰과 시간을 낭비할 수 있다. MCP 도구도 마찬가지다 — GitHub MCP·Slack MCP처럼 강한 권한을 가진 도구를 무차별로 노출하면, 에이전트가 의도치 않게 외부 시스템에 변경을 가할 수 있다. "필요한 것만, 명시적으로"가 모든 도구 부여의 기본자세다.

▲ 실제 예시

code-reviewer와 security-auditor는 둘 다 read-only지만 역할이 분리되어 있다는 점에 주목하자. 같은 도구 세트라도 description에서 책임 영역을 분명히 나눠두면, 메인이 상황별로 "지금은 코드 품질 이슈, 지금은 보안 이슈"를 골라 호출한다. 두 에이전트를 합쳐 "리뷰+감사" 만능 에이전트로 만들면 매칭 정확도가 떨어진다(노하우 8 참조). 반면 python-debugger는 "에러 발견 → 원인 분석 → 수정"이 한 작업 단위라 Edit이 빠지면 임무를 완수할 수 없다. 도구 구성은 항상 "에이전트의 임무 단위"에 맞춰 정한다.

노하우 3: 병렬 실행으로 시간을 반으로 줄인다

▲ ❌ 순차 실행 — 합산 시간

순차 실행은 작업들이 서로의 결과를 필요로 하지 않더라도 한 줄로 늘어서서 기다리는 구조다. 코드 리뷰가 끝나야 보안 감사를 시작하고, 그게 끝나야 테스트 확인을 시작한다. 총 소요 시간은 3 + 5 + 2 = 10분으로 모든 작업 시간의 합산이다. 독립적인 작업끼리도 어쩌다 순차로 굴러가는 경우가 흔한 이유는, 사용자가 "먼저 리뷰해줘", "이제 보안 봐줘"처럼 한 번에 하나씩 요청하기 때문이다.

▲ ✅ 병렬 실행 — 최장 시간

같은 세 작업을 동시에 던지면 총 소요 시간은 가장 오래 걸리는 5분으로 줄어든다 — 정확히 절반이다. 메인 Claude가 한 번의 응답에서 Agent 도구 호출 3개를 동시에 발사하면, 세 에이전트가 각자 독립 컨텍스트에서 병렬로 달리고, 결과는 비동기로 메인에 돌아온다.

독립적인 작업은 병렬로 실행해야 한다. 메인 Claude에게 "code-reviewer, security-auditor, test-checker 세 에이전트를 동시에 실행해서 결과를 합쳐줘"라고 한 문장으로 요청하면 세 에이전트가 병렬로 달린다. 에이전트 수가 많아질수록 절약 효과가 커지는 이유는 합산은 선형으로 늘지만 max는 그렇지 않기 때문이다. 5개를 순차로 돌리면 모든 시간을 더하지만, 병렬이면 여전히 가장 느린 하나의 시간이다.

노하우 4: 에이전트 계층 구조로 복잡한 작업 분해

PR 리뷰처럼 여러 관점이 필요한 복합 작업은 한 에이전트가 다 처리하기 어렵다. 이 다이어그램은 "메인이 감독자, 에이전트들이 실무자"인 위계를 보여준다. 메인은 사용자의 한 줄 요청("PR 검토해줘")을 받아 영역별로 쪼개고, 각 영역의 전문 에이전트에게 위임한다. 세 에이전트가 동시에 달려(노하우 3과 결합) 결과를 돌려보내면, 메인이 그것들을 합쳐 사용자가 이해할 수 있는 종합 리포트 한 장으로 정리한다.

메인 Claude가 감독자가 되고 에이전트들이 실무자가 된다. 이 구조의 장점은 셋이다 — ① 각 에이전트가 자기 영역에만 집중하므로 깊이가 살아난다, ② 병렬 실행이 가능하다, ③ 한 에이전트가 실패해도 다른 결과는 살아남는다. 이 구조가 잘 작동하려면 각 에이전트의 description에 "어떤 작업을 위임받는지"가 명확해야 한다 — 그렇지 않으면 메인이 영역을 어떻게 쪼개야 할지 모른다.

노하우 5: 컨텍스트 격리로 메인 대화를 깨끗하게 유지

▲ ❌ 서브에이전트 없이

큰 결과물(10만 줄 diff, 5천 줄 로그)을 메인 대화에서 직접 처리하면 컨텍스트 윈도우가 빠르게 채워진다. 다이어그램의 흐름을 보자 — diff가 들어오고, 로그가 들어오고, 마지막에 정작 하려던 본 작업이 들어왔을 때는 이미 윈도우의 대부분이 분석 텍스트로 점령된 상태다. 결과적으로 메인은 직전 내용을 잊거나, 자동 컨텍스트 압축이 빈번해져 정확도가 떨어진다. 컨텍스트 윈도우는 "주의력 예산"이라고 보면 이해가 쉽다 — 한정된 예산을 어디에 쓰느냐가 작업 품질을 결정한다.

▲ ✅ 서브에이전트 사용

같은 분석을 서브에이전트에 위임하면 결과가 달라진다. 10만 줄 diff와 5천 줄 로그는 에이전트의 독립 컨텍스트에서 처리되고, 메인 대화로 돌아오는 것은 3줄짜리 요약뿐이다. 메인의 윈도우는 본 작업을 위한 예산을 그대로 보존한다. 서브에이전트는 일종의 외주(outsourcing) 장치다 — 큰 짐을 외부에 맡기고, 결정에 필요한 결론만 가져온다. 깊이 있는 분석 자체를 포기하는 것이 아니라, 깊이 있는 분석을 메인 컨텍스트 바깥에서 수행하게 만드는 것이다.

노하우 6: memory 필드로 에이전트가 학습하게 만들기

기본적으로 에이전트는 호출이 끝나면 모든 기억을 잃는다 — 매 호출이 일회용이다. 다이어그램은 그 한계를 깨는 방법을 보여준다. 세션 1에서 에이전트가 패턴 A, B를 발견하면 그 결과를 프로젝트 메모리(~/.claude/projects/.../memory/) 파일로 저장한다. 세션 2가 시작될 때 메모리가 자동으로 로드되어, 에이전트는 패턴 A·B를 이미 아는 상태에서 출발한다. 그 위에 패턴 C·D를 쌓고, 세션 3은 누적된 A·B·C·D를 기반으로 더 깊은 분석을 수행한다 — 매번 처음부터 탐색하지 않는다.

memory: project를 설정하면 에이전트가 세션을 넘어 기억을 유지한다. 아키텍처 분석, 대규모 코드베이스 탐색, 리팩토링 후보 식별처럼 "알면 알수록 더 잘하는" 작업에 특히 효과적이다. 에이전트가 프로젝트를 처음 보는 것이 아니라 이미 아는 패턴과 대조하면서 판단하게 된다. 반면 일회성 디버깅이나 한 파일 리뷰처럼 누적 학습이 필요 없는 작업에는 memory가 오히려 잡음이 될 수 있으므로, 에이전트의 성격에 맞게 켜고 끈다.

노하우 7: 시스템 프롬프트에 출력 형식을 강제하기

다이어그램의 좌측 흐름은 출력 형식이 없을 때의 문제를, 우측은 명시했을 때의 효과를 보여준다. 형식이 없으면 에이전트는 매번 자유롭게 답하고, 어떤 때는 markdown 헤더로, 어떤 때는 평문 단락으로, 어떤 때는 JSON 비슷한 무언가로 결과를 내놓는다. 메인 Claude가 이걸 파싱하려면 매번 다르게 해석해야 하고, 여러 에이전트의 결과를 합칠 때 형식이 달라 정렬조차 안 된다.

형식을 시스템 프롬프트에 못박아두면 — 예를 들어 **근본 원인**: 한 문장 / **수정 내용**: 파일:라인 / **검증**: 실행한 명령처럼 — 에이전트의 모든 응답이 같은 슬롯 구조를 갖는다. 메인은 슬롯별로 신뢰하고 파싱할 수 있고, 여러 에이전트의 결과를 슬롯별로 나란히 표로 합치는 것도 자연스러워진다. 출력 형식 강제는 단순한 미관 문제가 아니라 자동화 파이프라인의 기반이다 — 다음 단계가 결과를 프로그램적으로 처리할 수 있게 만든다.

노하우 8: 에이전트를 작게 유지하고 조합하기

▲ ❌ 만능 에이전트 — 피해야 할 패턴

한 에이전트에 6가지 역할을 모두 욱여넣으면 세 가지 문제가 한꺼번에 터진다. 첫째, description이 "코드 리뷰 + 보안 + 성능 + 테스트 커버리지 + DB 최적화 + 문서"가 되어 너무 광범위해진다 — 메인 Claude가 "지금이 호출 시점인가?"를 판단하기 어렵다(노하우 1의 매칭 실패). 둘째, 하나의 시스템 프롬프트·도구 세트로 6가지 영역을 모두 다루려다 보니 어느 한 영역도 깊이 있게 파지 못하고 평균적인 답만 내놓는다. 셋째, 한 에이전트 내부의 작업은 순차적으로만 진행되므로 코드 리뷰가 다 끝나야 보안 감사를 시작한다 — 병렬화의 이득을 통째로 잃는다.

▲ ✅ 작은 전문 에이전트 조합 — 권장 패턴

같은 6가지 일을 4개의 작은 전문 에이전트로 쪼개면 만능 에이전트의 세 문제가 모두 풀린다. ① 각 description이 한 영역에만 집중하므로 매칭 정확도가 올라가고, ② 각자 자기 도구·시스템 프롬프트·memory를 영역에 맞춰 최적화할 수 있어 깊이가 살며, ③ 메인이 4개 에이전트를 한 번에 던져 병렬로 돌릴 수 있다. Unix 철학의 "do one thing well"이 서브에이전트 설계에도 그대로 적용된다 — 작은 도구들이 조합되어 큰 일을 해내는 구조가 한 거대한 도구보다 거의 항상 더 나은 결과를 낸다.

노하우 9: isolation으로 파일 변경을 격리하기

▲ 일반 에이전트 실행

기본 모드에서 에이전트는 메인 Claude와 같은 작업 트리(working tree)에서 동작한다. 에이전트가 파일을 Edit하면 그 변경은 즉시 메인 트리에 반영되어 사용자가 보고 있는 파일이 바뀐다. 변수 이름 변경 같은 작은 fix에는 이 모드가 빠르고 편하다 — 결과를 곧바로 확인하고 git diff로 검토하면 된다. 하지만 대규모 리팩토링이나 실험적 변경을 맡길 때는 위험하다 — 에이전트가 30개 파일을 건드려놓고 방향이 틀렸음이 밝혀지면 되돌리기가 번거롭다.

▲ isolation: worktree 설정

isolation: worktree를 켜면 에이전트 호출 시 별도의 Git worktree가 자동 생성된다. 같은 저장소의 동일 커밋에서 분기한 임시 작업 공간이다. 에이전트는 이 worktree 안에서만 파일을 수정하므로, 메인의 작업 트리는 손도 닿지 않는다. 사용자가 결과를 검토해 승인하면 변경 사항이 메인으로 머지되고, 거절하면 worktree 자체를 삭제해서 원본을 무손상으로 유지한다. 다이어그램의 두 분기(승인/거절) 모두 메인을 보호한다는 점이 핵심이다.

실험적인 대규모 리팩토링을 에이전트에게 맡길 때 isolation이 유용하다. "이 방향이 맞는지 모르겠지만 일단 한번 해봐"라고 맡길 수 있는 안전망 역할이다. 30개 파일을 만지든 100개를 만지든, 결과를 보고 마음에 안 들면 worktree를 지우는 것으로 깔끔히 끝난다. git의 branch + stash + reset을 한 번에 대체하는 안전장치로 이해하면 직관적이다.

노하우 10: 에이전트 디버깅 — 왜 호출이 안 될 때

"내 에이전트가 왜 자동으로 호출되지 않을까?"라는 질문이 들 때 이 다이어그램의 순서대로 체크하면 거의 모든 원인이 잡힌다. 위에서 아래로 갈수록 의심도가 낮아지는 순서다 — description은 가장 흔한 원인이고, 명시적 호출 테스트는 마지막 보루다. 각 체크 단계마다 대응 fix가 1:1로 매칭되어 있어, 원인이 좁혀지면 해결책이 자동으로 정해진다.

명시적 호출(@<name 값>)로 동작을 먼저 확인한다. 이것이 가장 강력한 분기 도구다 — 명시적 호출은 되는데 자동 위임이 안 된다면 description 문제로 좁혀지고, 명시적 호출조차 안 된다면 파일 위치·name 필드 형식·frontmatter 구문 오류 같은 등록 자체의 문제로 좁혀진다. 이 두 갈래만 갈라놓으면 디버깅 범위가 절반으로 줄어든다. description 문제일 때는 "Use proactively when X" 같은 트리거 패턴을 더 구체화하는 방향으로 다시 쓴다(노하우 1 참조).

한 가지 짚어둘 것 — 공식 문서(code.claude.com/docs/en/sub-agents)는 파일명이 name 필드와 일치할 필요가 없다고 명시한다. 호출 시 사용되는 식별자는 frontmatter의 name 값이고, 파일명은 디스크상 위치만 정한다. 다만 관리·검색의 편의 때문에 컨벤션상 일치시키는 것이 권장되며, 공식 예제들도 대부분 그렇게 둔다(예: code-reviewer.md ↔ name: code-reviewer).

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.