Claude Code 서브에이전트: 맥락 격리, 오케스트레이터와 리뷰어, 필요 없는 경우

Claude Code 서브에이전트란 무엇인가

서브에이전트는 메인 에이전트가 별도의 작업을 맡기려고 띄우는 또 하나의 에이전트 인스턴스입니다. 자신만의 컨텍스트 창, 시스템 프롬프트, 허용된 도구 목록을 가집니다. 메인 에이전트는 작업 설명을 넘기고, 서브에이전트는 파일을 읽고 명령을 실행하며 독립적으로 일합니다. 돌아오는 것은 최종 메시지 하나뿐입니다.

핵심 단어는 격리입니다. 서브에이전트가 도중에 읽은 것, 즉 수십 개의 파일, 긴 테스트 출력, 막다른 가설은 모두 그 컨텍스트 안에 남고 메인 세션의 컨텍스트에는 들어가지 않습니다. 메인 에이전트는 짧은 결과만 봅니다. '함수 X에 오류가 있고, 원인은 이것이며, 영향받는 곳은 세 군데다'라는 식입니다.

Claude Code의 서브에이전트는 멀티에이전트 시스템이라는 더 넓은 아이디어의 한 사례입니다. '생각하고, 실행하고, 검증한다'는 하나의 루프 대신, 각자 역할과 책임을 가진 여러 노드의 그래프가 생깁니다.

맥락 격리가 필요한 이유

컨텍스트 창은 에이전트의 가장 중요한 자원입니다. 여기에는 CLAUDE.md의 지침, 대화 기록, 읽은 코드, 명령 출력이 동시에 들어갑니다. 에이전트가 30분 동안 버그 원인을 찾는다면 컨텍스트는 쓸모없는 파일과, 그중 한 줄만 중요한 로그로 가득 찹니다.

이 상황의 결과는 오래 에이전트를 써 본 사람에게는 익숙합니다. 모델이 프로젝트 규칙을 잘 지키지 못하고, 세부 사항을 혼동하며, 자동 압축 때 중요한 내용을 잃습니다. 서브에이전트는 이 문제를 구조적으로 해결합니다. 지저분한 작업은 별도의 컨텍스트에서 하고, 답을 받은 뒤 그 컨텍스트는 버립니다.

• 검색과 조사. '결제 함수가 호출되는 모든 곳을 찾고, 어떻게 구성되어 있는지 설명해 줘'는 서브에이전트에 맡기기 좋은 전형적인 작업입니다.
• 시끄러운 검사. 테스트를 돌리고 실패한 것을 분석하는 일은 서브에이전트에 맡기고, 원인 목록만 받으세요.
• 큰 문서 읽기. 수백 쪽짜리 명세가 몇 가지 사실만 필요할 때, 서브에이전트가 그 사실을 뽑아내게 하세요.

서브에이전트 설정: .claude/agents 폴더

직접 만드는 서브에이전트는 YAML 머리말이 있는 마크다운 파일로 정의합니다. 프로젝트 파일은 저장소의 .claude/agents/에 두고 git으로 팀 전체가 씁니다. 개인 파일은 ~/.claude/agents/에 두면 모든 프로젝트에서 작동합니다. Claude Code에서 /agents 명령으로 대화형으로 만들고 수정할 수도 있습니다.

---
name: code-reviewer
description: 코드 변경에서 오류와 프로젝트 규칙 위반을 찾습니다. 작업을 마친 뒤 커밋 전에 사용하세요.
tools: Read, Grep, Glob, Bash
---
당신은 코드 리뷰어입니다. 아무것도 고칠 필요는 없습니다.

1. 변경 사항을 확인하세요: git diff.
2. 각 변경을 논리 오류, 오류 처리, 보안(SQL, 출력 이스케이프, 비밀 값)
   측면에서 검토하세요.
3. AGENTS.md의 규칙과 대조하세요.
4. 지적 사항 목록을 반환하세요: 파일, 줄, 문제, 중요한 이유.
   지적 사항이 없으면 그렇게 적으세요.

필드의 의미는 다음과 같습니다.

파일 본문은 서브에이전트의 시스템 프롬프트입니다. 서브에이전트는 여러분과의 대화 기록을 보지 못하므로, 역할과 응답 형식에 대해 알아야 할 모든 것은 프롬프트나 메인 에이전트가 넘기는 작업 안에 있어야 합니다.

서브에이전트 호출하기

작업이 설명(description)에 맞으면 메인 에이전트가 스스로 서브에이전트를 고를 수 있습니다. 그러나 명시적으로 요청하는 편이 확실합니다. '코드 리뷰어 서브에이전트를 써서 변경 사항을 검토해 줘'처럼요. 설명에 '적극적으로 사용'이라는 문구를 넣으면 알림 없이도 호출될 가능성이 높아지지만, 보장되지는 않습니다.

탐색 서브에이전트

거의 모든 프로젝트에 만들어 둘 가치가 있는 두 번째 파일은 읽기 전용 탐색자입니다. 코드에 대한 질문에 답하고, 아무것도 바꾸지 않습니다.

---
name: explorer
description: 코드베이스에서 무엇이 어디에 있고 어떻게 동작하는지 답합니다. 많은 파일을 읽고 짧은 답만 얻고 싶을 때 사용하세요.
tools: Read, Grep, Glob
---
당신은 코드를 탐색하며 아무것도 바꾸지 않습니다.
반환하세요: 질문에 대한 짧은 답, 근거가 된 파일과 줄 목록,
그리고 확인하지 못한 것.

이런 서브에이전트는 작업 초반에 특히 유용합니다. 메인 에이전트는 모든 것을 읽느라 컨텍스트를 쓰지 않고도 필요한 위치의 지도를 얻으며, 이후 구체적인 파일을 가지고 작업합니다.

'오케스트레이터와 실행자' 구조

가장 흔한 멀티에이전트 구조는 한 오케스트레이터 에이전트가 계획과 전체 그림을 쥐고, 구체적인 단계는 실행자에게 나눠 주는 것입니다. 오케스트레이터는 코드 전체를 직접 읽지 않습니다. 작업을 정의하고, 결과를 받고, 다음에 무엇을 할지 결정합니다.

1. 오케스트레이터는 작업을 독립적인 부분으로 나누고, 각 부분에 자기완결적인 지시를 씁니다. 목표, 어디서 찾을지, 무엇을 완료로 볼지, 어떤 형식으로 답할지.
2. 실행자는 자기 컨텍스트에서 지시를 수행합니다.
3. 오케스트레이터는 답을 모으고, 부분들이 맞물리는지 확인한 뒤, 다음 단계를 실행하거나 이전 단계로 되돌립니다.

이 구조의 약점은 작업의 전달입니다. 서브에이전트는 자신에게 적힌 것만 압니다. '지난번에 얘기한 그 버그를 고쳐 줘'라는 지시는 그에게 빈 말입니다. 대화를 보지 못했기 때문입니다. 좋은 지시는 저장소를 처음 연 새 동료에게 주는 과제처럼 읽혀야 합니다.

실행자가 돌려줘야 할 것

응답 형식을 미리 정해 두세요. 파일 목록, 출력, 찾은 원인, 확인하지 못한 것. 짧고 구조화된 응답은 오케스트레이터의 컨텍스트를 아끼고, '확인하지 못한 것' 항목은 잘못된 확신을 막습니다. 실행자도 다른 에이전트와 마찬가지로 성공을 보고하려는 경향이 있기 때문입니다.

별도의 리뷰어: 판사와 실행자를 분리하는 이유

같은 에이전트가 코드를 쓰고 스스로 검토하면, 판사와 피고인이 같은 머리를 씁니다. 에이전트는 자신이 무엇을 하려 했는지 기억하고, 코드에서 쓰인 내용이 아니라 자기 의도를 봅니다. 게다가 끝내고 싶어 합니다. 그래서 검토는 형식적인 절차가 되기 쉽습니다.

별도 컨텍스트의 리뷰어는 이런 문제가 없습니다. 결정의 역사를 모르고, diff와 프로젝트 규칙만 보며, 결과를 새로운 눈으로 평가합니다. 실제 팀에서 작성자가 자기 풀 리퀘스트를 승인하지 않는 것과 같은 원리입니다.

• 리뷰어에게는 읽기와 검사 실행 도구만 주세요. 파일을 편집할 권한은 주지 마세요. 그러면 문제를 보고하는 대신 조용히 고치는 일이 생기지 않습니다.
• 검사 기준을 명시하세요. 무엇이 오류인지, 어떤 프로젝트 규칙이 필수인지.
• 지적 사항을 어떻게 처리할지는 오케스트레이터나 사람이 결정하세요. 리뷰어는 찾고, 실행자는 고칩니다.

리뷰어가 기계적 검사를 대체하지는 않습니다. 테스트, 린터, 타입 검사는 결정적인 노드이며, 어떤 모델보다 믿을 만합니다. 리뷰어는 기계적 검사가 보지 못하는 것, 즉 잘못된 논리, 합의 위반, 불필요한 복잡성을 잡아냅니다.

서브에이전트의 병렬 실행

Claude Code는 여러 서브에이전트를 동시에 실행할 수 있습니다. 작업의 일부가 실제로 독립적일 때 속도가 빨라집니다. 예를 들어 모듈 세 개를 살펴보기, 변경을 세 관점(보안, 성능, 테스트)에서 검토하기, 여러 출처에서 정보를 모으기 등입니다.

병렬 실행은 읽기에서는 잘 작동하고 쓰기에서는 잘 작동하지 않습니다. 두 실행자가 같은 파일을 동시에 고치면 서로의 변경을 덮어쓰고, 어느 쪽도 그 사실을 모릅니다. 에이전트 그래프 용어로 말하면 병합 규칙이 없는 공유 상태입니다. 실용적인 규칙은 다음과 같습니다.

• 병렬로는 조사, 분석, 리뷰를 합니다. 겹치는 파일의 수정은 순차적으로 합니다.
• 실행자가 그래도 병렬로 쓴다면 영역을 나누세요. 각자 자기 파일에서만 일하거나, 자기 저장소 사본(예: 별도의 git worktree)에서 일합니다.
• 결과를 모으는 노드는 하나, 즉 오케스트레이터여야 합니다. 실행자끼리 직접 모으지 않습니다.

서브에이전트가 필요 없는 경우

멀티에이전트 구조에는 비용이 듭니다. 토큰, 시간, 그리고 전달 과정에서 정보가 사라지는 지점이 늘어납니다. Claude Code의 서브에이전트가 늘 이득이 되지는 않습니다.

에이전트 그래프를 만들기 전에 간단한 질문에 답하세요. 공통 목표를 누가 책임지는가, 누가 거부권을 가져 변경을 되돌릴 수 있는가, 무엇을 성공으로 볼 것인가. 답이 없다면 여러 에이전트는 혼란을 그저 늘릴 뿐입니다.

서브에이전트에서 흔한 실수

모호한 설명

'코드 도우미'라는 설명으로는 메인 에이전트가 언제 불러야 할지 알 수 없습니다. 트리거를 쓰세요. 예: 'api/ 폴더를 바꾼 뒤, 커밋 전에'.

맥락 없는 지시

경로, 완료 기준, 제약 없이 작업을 받은 서브에이전트는 원하는 것이 무엇인지 추측하느라 일의 절반을 씁니다. 지시 템플릿으로 해결하세요. 목표, 입력 데이터, 제약, 응답 형식.

지나치게 넓은 권한

탐색자와 리뷰어에게 파일 편집 권한은 필요 없습니다. tools 제한은 역할을 프롬프트의 부탁이 아니라 메커니즘으로 만드는 값싼 방법입니다.

검증 없이 보고 믿기

서브에이전트 답변의 '모든 테스트 통과'는 주장이지 사실이 아닙니다. 오케스트레이터는 확인 가능한 것, 즉 명령 출력, 종료 코드, 구체적인 줄에 근거해야 합니다.

정리

Claude Code의 서브에이전트는 세 가지 일에 쓰는 도구입니다. 메인 컨텍스트를 깨끗하게 유지하기, 검증과 실행을 분리하기, 독립적인 작업을 병렬화하기. 짧은 마크다운 파일로 .claude/agents/에 정의하며, 작동 품질은 역할 설명, 도구 세트, 그리고 지시가 얼마나 자기완결적인지에 달려 있습니다. 작업이 작거나 대화와 밀접하게 얽혀 있다면, 여전히 에이전트 하나가 낫습니다. 하나의 루프에서 노드, 간선, 공유 상태로 이루어진 시스템으로의 전환은 강의에서 실제 사례로 자세히 다룹니다.