서브에이전트 사용법과 안티패턴

한 줄 요약

서브에이전트의 핵심은 여러 AI를 많이 붙이는 것이 아니라, 컨텍스트, 도구, 권한, 책임을 잘라내는 것이다.

왜 저장했나

AI coding agent, research agent, MCP tool, Claude Code subagent, OpenAI Agents SDK, LangGraph, CrewAI 같은 흐름이 빠르게 겹치고 있다. 이 노트는 "언제 멀티에이전트를 쓰는가"보다 "언제 쓰면 안 되는가", "어떤 책임을 분리해야 안정적인가", "어떤 보안 경계를 세워야 하는가"를 다시 보기 위해 저장했다.

원 질문

서브에이전트를 가장 잘 사용하는 방법, 주의점, 안티패턴 등 모든 것을 알고 싶다. 관련 커뮤니티, 토론, 저명인사의 블로그, 논문, repository 등 정보를 찾아보고, 현재 시점에 유효한 내용과 트렌드를 분석해 정리한다.

핵심 답변

가장 안정적인 기본형은 메인 에이전트 1개가 최종 판단과 쓰기 작업을 소유하고, 서브에이전트는 조사, 검증, 리뷰, 요약, 전문 도구 사용을 맡는 구조다.

2026년 기준 원문의 실무 합의는 다음처럼 정리된다.

단순 작업은 단일 에이전트나 결정적 workflow로 끝낸다.
컨텍스트가 커지거나 도구가 많아지거나 전문 규칙이 갈라질 때만 서브에이전트를 만든다.
읽기, 검색, 분석, 리뷰, 검증은 병렬 서브에이전트가 강하다.
코드 수정, DB 변경, 배포, 결제, 메일 발송 같은 "세상에 영향을 주는 쓰기"는 단일 소유자나 명확한 승인 게이트를 둔다.
멀티에이전트는 성능을 공짜로 올리는 마법이 아니라, 토큰, 지연, 디버깅, 보안 비용을 지불하고 병렬 탐색 능력을 사는 구조다.

무엇을 서브에이전트라고 볼 것인가

Claude Code 기준 subagent는 특정 종류의 작업을 처리하는 전문 AI assistant이며, 자기 context window, custom system prompt, tool access, permission을 가지고 독립적으로 작업한 뒤 결과 요약만 메인 대화로 돌려준다. 핵심 가치는 더 똑똑한 에이전트가 아니라 다음 네 가지다.

메인 컨텍스트 오염 방지
도구와 권한 제한
재사용 가능한 전문 작업자
비용과 모델 라우팅

OpenAI Agents SDK 관점에서는 handoff와 agents-as-tools를 구분해야 한다. handoff는 specialist가 대화 branch의 ownership을 이어받는 방식이고, agents-as-tools는 manager가 최종 답변 책임을 유지한 채 specialist를 제한된 capability로 호출하는 방식이다. 실무에서 안정적인 "서브에이전트" 패턴은 대체로 후자에 가깝다.

LangChain은 multi-agent가 필요한 이유를 context management, distributed development, parallelization으로 정리하지만, 복잡한 작업이라고 항상 multi-agent가 필요한 것은 아니며 적절한 dynamic tools와 prompt를 가진 단일 agent가 더 나을 수 있다고 본다.

언제 써야 하나

상황	서브에이전트가 유리한 이유	추천 패턴
대규모 코드베이스 탐색	파일, 로그, 문서가 메인 컨텍스트를 오염시킨다	read-only explorer
긴 리서치	여러 독립 방향을 병렬 탐색할 수 있다	lead researcher + parallel research subagents
도구가 너무 많음	단일 agent가 tool selection을 헷갈린다	domain specialist / router
권한 분리가 필요함	DB 조회, 배포, 결제 같은 권한을 분리해야 한다	least-privilege subagent
리뷰와 검증이 필요함	작성자와 검토자의 failure mode를 분리한다	evaluator / reviewer
반복되는 전문 작업	같은 prompt, 도구, 출력 형식을 재사용한다	reusable subagent or skill
비용 최적화	쉬운 탐색은 작은 모델, 최종 판단은 큰 모델에 맡긴다	model routing

Anthropic의 multi-agent research system은 lead agent가 계획을 세우고 subagent들이 병렬 검색한 뒤 lead가 종합하는 구조였다. 원문은 내부 research eval에서 단일 Opus 4보다 90.2% 높은 성능을 보였다고 정리하면서도, multi-agent가 chat 대비 약 15배의 토큰을 쓰므로 가치가 충분히 높은 작업에서만 경제성이 맞는다고 경고한다.

쓰지 말아야 하는 경우

상황	더 나은 대안
고정된 순서의 단순 작업	prompt chaining, deterministic workflow
단순 분류	router 또는 작은 model call
포맷팅, lint, 테스트 실행 강제	hook, CI, schema validation
모든 subagent가 같은 전체 컨텍스트를 봐야 함	단일 agent + note/memory
서로 의존성이 높은 코드 수정	single writer, worktree 분리, 명시적 merge owner
보안과 권한 설계가 안 된 상태	권한, trace, eval부터 설계

Cognition은 "parallel writer swarm"을 여전히 취약한 패턴으로 보고, 실제로 잘 되는 구조를 "여러 agent가 intelligence를 보태되 writes는 single-threaded로 유지하는 방식"으로 정리한다.

안정적인 패턴

Subagent-as-tool / Supervisor-worker

메인 agent가 최종 답변과 전체 상태를 소유하고, 서브에이전트를 도구처럼 호출한다. 가장 안전한 기본형이다.

좋은 요청 형태:

auth 변경사항을 읽고, 보안상 위험한 패턴만 찾아서
파일, 라인, 근거, 수정 제안으로 반환해.
코드는 수정하지 마.

이 구조에서는 specialist가 bounded task를 수행하고 manager가 최종 합성을 맡는다. 최종 답변을 메인 agent가 써야 한다면 handoff보다 이 패턴이 안정적이다.

Handoff

전문 agent가 사용자와 직접 대화하거나 branch ownership을 가져야 할 때 쓴다. billing agent, refund agent, support agent가 예다.

단, handoff는 routing, state, guardrail 설계가 복잡하다. specialist가 정말 대화 주체가 되어야 할 때만 쓰고, 최종 답변을 manager가 써야 하면 tool-calling으로 호출하는 편이 낫다.

Orchestrator-workers

중앙 orchestrator가 작업을 동적으로 쪼개고 worker들이 병렬 수행한 뒤 결과를 종합한다. 리서치, 대규모 탐색, unknown unknown이 많은 문제에 강하다.

Evaluator-optimizer / Reviewer loop

작성 agent와 평가 agent를 분리한다. 번역, 글쓰기, 코드 리뷰, 보안 리뷰, 요구사항 검증처럼 평가 기준이 비교적 명확한 작업에 적합하다.

Router

입력 유형을 분류해 적절한 specialist로 보낸다. 고객지원, 사내 업무 assistant, 도메인별 toolset이 다른 경우에 좋다. 단, router가 틀리면 전체 시스템이 틀리므로 fallback과 trace가 필요하다.

Agent team / Swarm

agent들이 peer-to-peer로 소통하거나 각자 독립 세션을 가져야 할 때 쓴다. Claude Code 문서 기준 subagent는 메인 세션 안에서 결과만 돌려주는 구조이고, agent team은 독립 Claude Code session들이 서로 메시지하며 조정하는 구조다. 비용과 복잡도가 더 높다.

좋은 서브에이전트 계약 템플릿

서브에이전트 prompt나 config는 역할극보다 계약서처럼 써야 한다.

name: security-reviewer
description: Use proactively after auth, payment, permission, or data-access changes.
model: strong-enough-for-review
tools: Read, Grep, Glob, Bash(test-only)
permissions: read-only; no Edit/Write; no network unless explicitly allowed

Mission:
- Review the given diff or files for security issues.
- Do not modify code.

Inputs:
- Changed files or diff summary
- Relevant threat model
- Project security conventions

Must check:
- auth bypass
- injection
- privilege escalation
- sensitive data exposure
- unsafe external calls
- missing tests

Output format:
1. Verdict: pass / needs changes / blocked
2. Findings ordered by severity
3. File and line references
4. Why it matters
5. Minimal fix recommendation
6. Tests or checks to add
7. Uncertainties and assumptions

Stop condition:
- Stop after reviewing the provided scope.
- Do not expand into unrelated refactors.

Anthropic의 multi-agent research 회고도 subagent에게 objective, output format, tools/sources guidance, task boundaries를 주지 않으면 중복 검색, 누락, 잘못된 분업이 생긴다고 설명한다.

컨텍스트 엔지니어링 원칙

서브에이전트 성공의 핵심은 prompt wording보다 무엇을 보게 하고 무엇을 못 보게 할지다. 원문은 Anthropic의 context engineering 흐름을 바탕으로 다음 원칙을 강조한다.

메인 agent에는 계획, 결정, 최종 요약, 현재 상태만 남긴다.
서브에이전트에는 작업에 필요한 최소 파일, 로그, 링크, 도구만 준다.
대용량 파일, 로그, DB 결과는 통째로 넣지 말고 query, search, head, tail로 필요한 부분만 읽게 한다.
긴 작업은 TODO, NOTES, scratch file, issue comment 같은 외부 상태 저장소를 둔다.
subagent 결과는 원문 dump가 아니라 1,000~2,000 token 정도의 압축된 findings로 받는다.

이 관점에서는 subagent가 많은 token을 쓰는 것 자체는 괜찮다. 중요한 것은 lead agent에게 되돌아오는 내용이 합성 가능한 고신호 요약이어야 한다는 점이다.

도구 설계 원칙

서브에이전트는 tool surface가 나쁘면 쉽게 무너진다.

좋은 방향:

list_all_logs보다 search_logs
list_users + list_events + create_event보다 schedule_event
get_customer_by_id + list_transactions + list_notes보다 get_customer_context
저수준 UUID만 반환하지 말고 의미 있는 이름, 상태, 관련 메타데이터를 반환
도구 이름은 겹치지 않게 namespace를 사용한다. 예: github_search_issues, jira_search_tickets

도구를 많이 붙이는 것은 능력 확장이 아니라 선택 문제를 키우는 일일 수 있다. Anthropic은 몇 개의 신중한 high-impact workflow 도구부터 만들고, 겹치는 도구나 저신호 출력은 피하라고 권한다.

안티패턴

1. Agent가 많으면 더 똑똑해진다고 믿기

agent가 많아지면 병렬 탐색 능력은 늘지만 비용, 지연, coordination failure, debugging surface도 커진다. Anthropic 사례의 약 15배 토큰 비용은 이 trade-off를 잘 보여준다.

2. Parallel writer swarm

여러 agent가 같은 코드베이스를 동시에 수정하면 style, edge case, architecture 선택이 충돌한다. 원문은 읽기와 검증은 병렬화하되, 쓰기는 단일 소유자가 맡는 구조를 더 안정적인 기본값으로 둔다.

3. 모호한 역할 프롬프트

"senior backend engineer" 같은 역할보다 입력, 금지사항, 도구, 출력 형식, 종료 조건이 중요하다. "이 diff에서 auth bypass만 찾아라. 수정하지 말고 severity 순으로 반환하라"가 더 안정적이다.

4. Multi-agent debate를 기본값으로 쓰기

원문은 "Stop Overvaluing Multi-Agent Debate"를 근거로, multi-agent debate가 더 많은 inference compute를 쓰고도 CoT나 Self-Consistency 같은 단순 baseline을 자주 넘지 못할 수 있다고 정리한다.

5. Handoff와 tool-calling 혼동

최종 답변을 manager가 써야 하면 specialist는 tool로 호출하는 편이 안정적이다. handoff는 ownership transfer라서 routing, state, guardrail 설계가 더 복잡하다.

6. Deterministic rule을 agent 기억에 맡기기

format, lint, protected file block, test command, schema validation은 agent가 기억하길 바라지 말고 hook, CI, schema, permission으로 강제한다.

7. Trace와 eval 없이 운영하기

멀티에이전트는 실패 경로가 비결정적이다. 같은 입력도 다른 subagent 수, 다른 tool sequence, 다른 handoff로 갈 수 있다. traces, graders, datasets, eval runs가 운영 필수 인프라가 된다.

8. 모든 agent에게 모든 권한 주기

가장 위험한 안티패턴이다. private data, untrusted content, external communication이 한 agent 안에 결합되면 Simon Willison이 말한 "lethal trifecta"가 된다.

9. Guardrail이 모든 것을 막는다고 믿기

OpenAI Agents SDK의 guardrail도 적용 범위가 도구 종류와 실행 경로에 따라 다르다. handoff, MCP, shell, browser, patch tool을 쓰는 시스템은 별도 권한, sandbox, 승인 설계가 필요하다.

현재 트렌드

Prompt engineering에서 context engineering으로

2025~2026년 자료에서 가장 강하게 반복되는 흐름이다. Anthropic, Cognition, LangChain 모두 agent 설계의 핵심을 멋진 역할 프롬프트가 아니라 각 agent가 어떤 context를 언제 얼마나 보느냐로 본다.

Skills가 subagent 남용을 대체

Claude Code의 CLAUDE.md, Skills, Subagents, Hooks, MCP, Agent teams는 서로 다른 extension layer다. Skills는 반복 workflow나 reference material을 on-demand로 로드하는 방식이다. 흐름은 "agent를 많이 만들기"보다 "단일 agent + 필요한 skill을 progressive disclosure로 로드"하는 쪽으로 기운다.

MCP와 agent/tool interoperability

MCP는 AI application과 외부 data source/tool을 연결하는 open standard로 등장했고, GitHub MCP Registry 같은 discovery layer도 생겼다. agent framework 내부 도구에서 표준 protocol 기반 조합으로 이동하는 흐름이다.

관측 가능성, eval, trace의 인프라화

OpenAI Agents SDK는 LLM generation, tool call, handoff, guardrail을 trace로 수집하고, trace grading과 dataset eval로 routing/tool/handoff 품질을 평가하라고 안내한다. LangSmith, Braintrust류 observability 도구도 이 흐름을 강화한다.

읽기 병렬화와 쓰기 단일화

GitHub Agent HQ처럼 여러 coding agent를 한 workflow에서 관리하려는 제품 흐름은 강하지만, 실무적으로는 plan, review, branch/worktree, human review, merge owner가 여전히 중요하다. Cognition의 표현대로 여러 agent가 intelligence를 보태더라도 writes는 single-threaded로 유지하는 쪽이 안정적이다.

Debate와 ensemble은 선택적으로만

Mixture-of-Agents 계열은 여러 출력을 결합해 성능을 높일 수 있음을 보였지만, Self-MoA 흐름은 강한 단일 모델의 여러 출력이 다양한 모델을 섞는 것보다 나을 수 있음을 보여준다. diversity 자체보다 독립 시도 품질과 aggregation 기준이 중요하다.

Coordination engineering의 부상

Swarm Skills, CA-MCP, Agent-as-a-Graph 같은 흐름은 agent를 수동으로 나열하는 단계를 넘어 coordination, routing, retrieval, shared memory를 설계 대상으로 본다.

Agent 보안 리스크의 확대

OWASP Agentic Applications Top 10, OWASP Agentic Skills Top 10, NCSC/Five Eyes 경고, multi-agent zero-day exploit 연구는 같은 방향을 가리킨다. agent가 tool, private data, external action을 갖는 순간 전통적인 LLM 앱보다 훨씬 넓은 공격면이 생긴다.

분야별 운영 방식

코드 작업

안전한 기본 workflow:

메인 agent가 요구사항을 정리하고 plan을 쓴다.
explorer subagent가 관련 파일, dependency, test 위치를 read-only로 조사한다.
메인 agent가 구현한다.
test-runner subagent가 테스트 실패 로그를 요약한다.
code-reviewer/security-reviewer subagent가 diff를 read-only로 리뷰한다.
메인 agent가 수정 반영한다.
destructive action, merge, deploy는 human approval을 둔다.

리서치 작업

안정적인 구조:

lead researcher가 질문을 독립 하위 질문으로 나눈다.
subagent마다 source class를 다르게 준다. 예: 공식 문서, 논문, GitHub, 커뮤니티, 뉴스.
각 subagent는 citation, uncertainty, contradictory evidence를 포함해 반환한다.
lead가 중복 제거, 신뢰도 평가, synthesis를 한다.
citation checker 또는 verifier가 최종 주장과 출처를 대조한다.

사내 업무 자동화

보안 체크리스트

기본은 read-only로 시작한다.
subagent마다 고유 identity, key, permission을 둔다.
private data, untrusted content, external communication을 한 agent에 몰아넣지 않는다.
prompt injection을 완전히 차단할 수 있다고 가정하지 않는다.
MCP server와 skill은 verified source, pinned version, permission review를 거친다.
shell, browser, DB write, email send, payment, deploy는 human approval 또는 policy gate를 둔다.
trace에는 민감정보가 들어갈 수 있으므로 저장 정책을 명시한다.
eval에는 정상 케이스뿐 아니라 prompt injection, malicious tool output, stale context, wrong handoff, excessive tool use를 넣는다.

바로 적용할 체크리스트

서브에이전트를 새로 만들기 전에 아래 질문에 "예"가 3개 이상이면 만들 가치가 있다.

이 작업이 메인 컨텍스트를 오염시킬 만큼 많은 파일, 로그, 검색 결과를 읽는가?
이 작업은 read-only로 분리할 수 있는가?
다른 도구, 권한, 모델, 정책이 필요한가?
출력 형식과 성공 기준을 명확히 쓸 수 있는가?
실패해도 되돌리기 쉬운가?
trace와 eval로 품질을 확인할 수 있는가?
병렬화했을 때 실제 시간이나 품질 이득이 있는가?
agent가 아니라 hook, CI, schema, deterministic function으로 처리할 수 없는가?

초기 세팅은 다음 정도로 충분하다.

explorer: read-only, 코드, 문서, 로그 조사 전용
reviewer: read-only, diff 리뷰와 위험 탐지 전용
test-debugger: test/log 분석 전용, 수정은 제안만
security/db-validator: DB query, auth, permission 검토 전용
main: 최종 판단, 코드 수정, 사용자 응답, merge 책임

핵심 운영 원칙은 간단하다. 서브에이전트는 조직도가 아니라 회로 차단기다. 컨텍스트를 줄이고, 권한을 줄이고, 실패 반경을 줄이고, 검증 가능성을 높일 때만 좋은 서브에이전트다.

Source Fidelity Notes

Preserved key numbers: Anthropic research eval의 90.2% 성능 개선 주장, chat 대비 약 15배 token 비용, subagent findings를 1,000~2,000 token으로 압축하라는 운영 기준, 새 subagent 생성 전 "예" 3개 이상 체크 기준.
Preserved frameworks / models: subagent-as-tool, handoff, orchestrator-workers, evaluator-optimizer, router, agent team/swarm, context engineering, tool design, Skills, MCP, Agent HQ, Mixture-of-Agents, Self-MoA, Swarm Skills, CA-MCP, Agent-as-a-Graph, OWASP Agentic Applications Top 10, Simon Willison의 lethal trifecta.
Preserved templates / checklists: security-reviewer subagent 계약 템플릿, 언제 쓸지/쓰지 말지 표, context engineering 원칙, tool design 원칙, anti-pattern 목록, coding/research/internal automation workflow, security checklist, 바로 적용할 체크리스트, 초기 subagent 구성.
Omitted or compressed: 원문의 긴 출처별 해설, 반복 설명, 일부 커뮤니티 토론의 세부 맥락, reference title의 부가 텍스트, 공개 독자에게 덜 필요한 raw GPT 문장 흐름.
Omission risk: 원문 전체를 복원할 수 있는 수준은 아니지만, 핵심 주장과 실무 적용에 필요한 숫자, 패턴, 템플릿, caveat, reference는 보존했다. 원문은 Waitworthy sources/ layer에 별도 보존되어 있으며 공개 페이지에는 raw output을 직접 노출하지 않는다.

검증이 필요한 주장

"2026년 현재"라는 표현은 빠르게 변하는 agent 도구 생태계를 전제로 하므로, 특정 도구의 최신 기능과 가격, 정책은 별도로 확인해야 한다.
Anthropic의 90.2% 개선과 약 15배 token 비용은 특정 research eval과 시스템 설계 조건의 결과이므로 일반 작업에 그대로 일반화하면 안 된다.
OpenAI Agents SDK, Claude Code, LangChain, CrewAI의 handoff, guardrail, tracing, permission 동작은 버전별로 바뀔 수 있다.
arXiv와 커뮤니티 자료는 peer review 여부와 재현성이 서로 다르므로, 중요한 운영 결정을 할 때는 공식 문서와 실제 eval을 함께 봐야 한다.
보안 체크리스트는 위험을 줄이는 기준이지 prompt injection이나 tool misuse를 완전히 막는 보장은 아니다.