서브에이전트를 효과적으로 사용하기

서브에이전트가 빛을 발하는 경우

서브에이전트는 탐색 작업이 실행 작업과 분리되어 있을 때 가장 잘 작동합니다. 작업의 각 단계가 이전 단계에서 발견한 내용에 의존한다면, 그 작업은 메인 스레드에서 진행하는 것이 좋습니다. 하지만 결과만 필요하고 그 과정에는 관심이 없다면, 위임하세요.

서브에이전트는 다음과 같은 작업에서 탁월합니다:

• 결과를 찾아낸 과정이 아니라 결과 자체가 필요한 경우
• 탐색 작업이 메인 스레드의 컨텍스트를 어지럽힐 수 있는 경우
• 새로운 관점이나 맞춤형 시스템 프롬프트가 작업에 도움이 되는 경우

리서치 작업

리서치는 전형적인 서브에이전트 사용 사례입니다. 익숙하지 않은 코드베이스에서 인증이 어떻게 작동하는지 조사하는 경우를 생각해 보세요. 메인 스레드는 JWT가 어디서 검증되는지 알아야 하지만, 그 과정에서 검색된 모든 파일을 볼 필요는 없습니다.

리서치 서브에이전트는 수십 개의 파일을 읽고, 함수 호출을 추적하고, 다양한 코드 경로를 탐색할 수 있습니다. 그 모든 탐색 작업은 서브에이전트의 컨텍스트 안에 머무릅니다. 메인 스레드는 다음과 같이 깔끔한 요약을 받게 됩니다:

JWT validation happens in middleware/auth.js line 42,
called from the Express router in route/api.js

서브에이전트가 힘든 작업을 대신 처리했습니다. 메인 스레드는 앞으로 나아가는 데 필요한 것만 정확히 얻게 됩니다.

코드 리뷰

Claude는 코드가 다른 누군가가 작성한 것처럼 제시될 때 더 효과적으로 리뷰합니다. 메인 스레드와 함께 여러 턴에 걸쳐 기능을 구축했다면, 같은 스레드에 리뷰를 요청하면 종종 약한 피드백이 나옵니다. Claude가 그 코드를 만드는 데 관여했기 때문에, 새로운 시각으로 바라보는 데 어려움을 겪습니다.

리뷰어 서브에이전트는 별도의 컨텍스트에서 변경 사항을 봅니다. git diff를 실행하고, 수정된 파일을 읽고, 코드가 어떻게 작성되었는지에 대한 이력 없이 전문화된 리뷰 기준을 적용합니다. 이러한 분리는 또한 프로젝트별 리뷰 기준을 서브에이전트의 시스템 프롬프트에 담을 수 있게 해주어, 팀 전체에서 일관된 리뷰 기준을 보장합니다.

맞춤형 시스템 프롬프트

Claude Code의 기본 시스템 프롬프트는 간결하고 코드 중심적인 응답을 강조합니다. 이는 코딩에는 훌륭하게 작동하지만, 모든 경우에 적합한 것은 아닙니다.

다음은 맞춤형 시스템 프롬프트가 서브에이전트를 메인 스레드보다 진정으로 더 낫게 만드는 두 가지 사례입니다:

• 카피라이팅 서브에이전트 -- 톤, 대상 독자, 스타일에 대한 지침을 제공하세요. Claude Code의 기본 프롬프트는 간결한 기술 문서 작성 쪽으로 기울어져 있는데, 이는 랜딩 페이지나 이메일 캠페인에는 적합하지 않습니다. 카피라이팅 서브에이전트는 어조와 구조에 대해 완전히 다른 지침을 가질 수 있습니다.
• 스타일링 서브에이전트 -- 시스템 프롬프트에서 먼저 디자인 시스템 파일을 읽도록 지시하여, CSS를 작성하기 전에 색상 변수, 간격 규칙, 컴포넌트 패턴을 파악하도록 하세요.

서브에이전트가 방해가 되는 경우

서브에이전트를 실행하는 데 드는 오버헤드 -- 작업 내용을 메인 스레드로부터 숨기고 그 결과를 요약으로 압축하는 것 -- 는 서브에이전트가 메인 스레드가 할 수 없는 무언가를 해낼 때만 의미가 있습니다. 주의해야 할 세 가지 흔한 안티패턴이 있습니다.

전문가 주장

전문성을 주장하는 서브에이전트는 거의 도움이 되지 않습니다. "당신은 Python 전문가입니다"나 "당신은 Kubernetes 전문가입니다" 같은 프롬프트는 아무런 가치를 더하지 않습니다. Claude는 이미 그 지식을 가지고 있기 때문입니다. 이른바 전문가 서브에이전트가 할 수 있는 일 중 메인 스레드가 직접 할 수 없는 것은 없습니다.

순차적 파이프라인

순차적 서브에이전트 파이프라인은 문제를 일으킵니다. 버그를 재현하는 에이전트 하나, 디버깅하는 에이전트 하나, 수정하는 에이전트 하나로 구성된 3단계 흐름을 생각해 보세요. 파이프라인은 작업이 진정으로 독립적일 때 작동합니다. 각 단계가 이전 단계의 발견에 의존할 때는 실패하며 -- 버그 수정은 거의 항상 그렇습니다. 에이전트 간 인계 과정에서 정보가 손실됩니다.

테스트 실행기

테스트 실행기 서브에이전트는 필요한 정보를 숨기는 경향이 있습니다. 테스트가 실패하면 문제를 진단하기 위해 전체 출력이 필요합니다. "테스트 실패"라고만 반환하는 서브에이전트는 직접 출력에서 볼 수 있었을 세부 정보를 얻기 위해 추가 디버그 스크립트를 만들도록 강요합니다. 테스트 결과, 테스트 실행기 패턴이 모든 구성 중 가장 낮은 성능을 보였습니다.

결정 규칙

서브에이전트를 사용할지 결정할 때는 스스로에게 한 가지 질문을 던져보세요: 중간 작업 과정이 중요한가?

답이 아니오라면 -- 최종 결과만 필요하다면 -- 서브에이전트에 위임하세요. 답이 예라면 -- 진행 과정을 보고 그에 반응해야 한다면 -- 메인 스레드에서 진행하세요.

다음의 경우 서브에이전트를 사용하세요:

• 리서치 및 탐색
• 코드 리뷰
• 맞춤형 시스템 프롬프트가 필요한 작업

다음의 경우 서브에이전트를 피하세요:

• 실질적인 역량을 더하지 않는 "전문가" 페르소나
• 각 단계가 이전 단계에 의존하는 다단계 파이프라인
• 디버깅을 위해 전체 출력이 필요한 테스트 실행