효과적인 서브에이전트 설계하기
서브에이전트를 만드는 방법을 알았으니, 이제 서브에이전트를 실제로 효과적으로 만드는 패턴을 살펴보겠습니다. 제대로 구성되지 않은 서브에이전트는 방향을 잃거나, 너무 오래 실행되거나, 메인 에이전트가 사용할 수 없는 결과물을 만들어냅니다. 이를 해결하는 방법은 네 가지로 정리됩니다: 좋은 설명 작성하기, 출력 형식 정의하기, 장애물 보고하기, 도구 접근 제한하기입니다.
한국어 대본
- 00:00이제 Subagents를 만드는 방법을 알았으니, 효과적인 Subagents로 이어지는 패턴을 살펴보겠습니다.
- 00:10먼저, Subagent 설정 파일의 일부 데이터가 어떻게 사용되는지 더 잘 이해해 보겠습니다.
- 00:16메인 컨텍스트 창 에이전트에게 메시지를 보낼 때마다 각 Subagent의 이름과 설명이
- 00:21시스템 프롬프트에 포함됩니다. 따라서 메인 에이전트가 언제
- 00:26Subagent를 자동으로 실행하는지 더 잘 제어하려면
- 00:32Subagent가 실행되면 메인 에이전트는 입력 프롬프트를 작성합니다. 이 입력 프롬프트를 작성할 때
- 00:38설명을 지침으로 사용합니다. 따라서 메인 에이전트가 언제 자동으로 Subagent를 실행하는지
- 00:43더 잘 제어하려면 이름과 설명을 수정해야 합니다. 리뷰 Subagent를
- 00:51다시 살펴보겠습니다. 현재 메인 에이전트가 Subagent를 실행하면 Subagent에는 입력 프롬프트가 주어집니다.
- 00:56현재 변경 사항을 찾기 위해 git diff를 사용하라는 내용입니다. 메인
- 01:02에이전트가 어떤 파일을 검토할지 Subagent에게 더 확실하게 알려주려면
- 01:06설명을 업데이트해야 합니다. 에이전트에게 검토할
- 01:12파일을 정확히 알려야 합니다.
- 01:14이제 Claude에게 코드 리뷰어 에이전트를 실행해 달라고 요청하면 다른 입력이 나타납니다.
- 01:22설명을 통해 메인 스레드가 Subagent에게 전달하는 내용에도 영향을 줄 수 있습니다.
- 01:28웹 검색 Subagent의 설명에 인용할 수 있는 출처를 반환하라는 내용을 추가하면 메인 스레드는
- 01:34작업을 위임할 때 메인 스레드가 그 지침을 포함합니다.
- 01:42가장 중요한 개선은 시스템
- 01:45프롬프트에 출력 형식을 정의하는 것입니다.
- 01:46이렇게 하면 Subagent에 자연스러운 중단 지점이 생깁니다.
- 01:50출력 형식이 없으면 Subagent는 조사를 충분히 했는지 판단하기 어려워하고,
- 01:55출력 형식이 지정된 Subagent보다 훨씬 더 오래 실행하는 경향이 있습니다.
- 02:03Subagent가 종속성 문제 같은 사안의 우회 방법을 발견하면,
- 02:10특정 명령에 특정 플래그가 필요하다는 사실을 알아냈다면, 이런 세부 사항이 요약에 나타나야 합니다.
- 02:16그렇지 않으면 메인 스레드가 동일한 해결책을 다시 찾아야 합니다.
- 02:21마주친 장애물, 설정 문제, 발견한 우회 방법이나 환경 특이 사항,
- 02:26특정 플래그나 설정이 필요했던 명령, 문제를 일으키는 종속성 또는 import입니다.
- 02:35출력 형식에서 장애물 보고를 명시적으로 요청하면 이 정보가 드러납니다.
- 02:40glob, grep, read만 사용하는 읽기 전용 Subagent는 실수로 파일을 수정할 수 없습니다.
- 02:49이 제약은 Subagent의 역할을 명확히 하고 의도하지 않은 부작용을 방지합니다.
- 02:54그렇다면 Subagent가 실제로 무엇을 해야 하는지 생각해 보세요.
- 02:59단순히 조사하는 것이라면 파일을 읽기만 하면 되므로 읽기 전용으로 유지하세요.
- 03:03그렇게 하면 탐색하는 동안 실수로 무언가를 수정할 수 없습니다.
- 03:06리뷰어는 변경 사항을 확인하려고 git diff를 실행해야 하므로 bash 접근 권한을 주세요. 하지만 여전히
- 03:12파일을 편집할 필요는 없습니다.
- 03:14실제로 코드를 변경해야 하는 Subagent에만 편집 및 쓰기 권한을 주세요. CSS 업데이트를 적용하는 스타일링
- 03:18에이전트 같은 경우입니다.
- 03:20이것은 여러 Subagent를 사용할 때 각 Subagent의 목적이 무엇인지 명확히 하는 데도 도움이 됩니다.
- 03:28따라서 효과적인 Subagent는 구조화된 출력을 사용하고, 장애물을 보고하며, 구체적인 설명을 갖추고,
- 03:34도구 접근을 제한합니다.
서브에이전트 구성 데이터가 사용되는 방식
메인 컨텍스트 윈도우 에이전트에 메시지를 보내면, 사용 가능한 모든 서브에이전트의 이름과 설명이 시스템 프롬프트에 포함됩니다. 이것이 메인 에이전트가 어떤 서브에이전트를 언제 실행할지 결정하는 방식입니다. 서브에이전트가 자동으로 트리거되는 시점을 더 잘 제어하고 싶다면, 조정해야 할 것이 바로 이름과 설명입니다.
설명은 두 번째 역할도 합니다. 메인 에이전트가 서브에이전트를 실행할 때, 작업을 시작하기 위한 입력 프롬프트를 작성합니다. 이때 설명을 해당 프롬프트 작성의 지침으로 사용합니다. 따라서 설명은 서브에이전트가 언제 실행되는지만 제어하는 것이 아니라 -- 서브에이전트가 무엇을 하도록 지시받는지 도 결정합니다.
입력 프롬프트를 형성하는 설명 작성하기
코드 리뷰 서브에이전트를 생각해 보세요. 일반적인 설명을 사용하면, 메인 에이전트는 "get diff를 사용해서 현재 변경 사항을 찾아라"와 같은 입력 프롬프트를 작성할 수 있습니다. 이는 모호합니다. 서브에이전트는 어떤 파일이 중요한지 스스로 파악해야 합니다.
설명을 "에이전트에게 검토해야 할 파일을 정확히 알려줘야 합니다"와 같은 내용으로 업데이트하면, 메인 에이전트는 이제 검토할 실제 파일을 나열하는 훨씬 더 구체적인 입력 프롬프트를 작성하게 됩니다.
이 동일한 기법은 다양한 유형의 서브에이전트에서도 작동합니다. 예를 들어, 웹 검색 서브에이전트의 설명에 "인용할 수 있는 출처를 반환하라"를 추가하면, 메인 에이전트는 작업을 위임할 때 해당 지시를 포함시킵니다.
출력 형식 정의하기
서브에이전트에 적용할 수 있는 가장 중요한 개선 사항은 시스템 프롬프트에서 출력 형식을 정의하는 것입니다. 이는 두 가지 효과가 있습니다:
- 자연스러운 중단 지점을 만듭니다 -- 서브에이전트는 형식의 각 섹션을 채웠을 때 작업이 끝났다는 것을 알게 됩니다.
- 서브에이전트가 너무 오래 실행되는 것을 방지합니다. 정의된 출력이 없으면, 서브에이전트는 충분한 조사가 이루어졌는지 판단하기 어려워하고 필요 이상으로 훨씬 오래 실행되는 경향이 있습니다.
다음은 코드 리뷰 서브에이전트를 위한 구조화된 출력 형식의 예시입니다:
Provide your review in a structured format:
- Summary: Brief overview of what you reviewed and overall assessment
- Critical Issues: Any security vulnerabilities, data integrity risks, or logic errors that must be fixed immediately
- Major Issues: Quality problems, architecture misalignment, or significant performance concerns
- Minor Issues: Style inconsistencies, documentation gaps, or minor optimizations
- Recommendations: Suggestions for improvement, refactoring opportunities, or best practices to apply
- Approval Status: Clear statement of whether the code is ready to merge/deploy or requires changes
이 형식은 서브에이전트에게 진행해야 할 명확한 체크리스트를 제공합니다. 모든 섹션이 채워지면, 서브에이전트는 멈출 수 있다는 것을 알게 됩니다.
장애물 보고하기
서브에이전트가 작업 중에 해결 방법을 발견했을 때 -- 예를 들어 의존성 문제를 해결하거나 특정 명령에 특정 플래그가 필요하다는 것을 발견했을 때 -- 이러한 세부 사항은 서브에이전트가 반환하는 요약에 나타나야 합니다. 그렇지 않으면, 메인 스레드는 동일한 해결책을 스스로 다시 발견해야 하며, 이는 시간과 토큰을 낭비하게 됩니다.
드러내고 싶은 종류의 정보는 다음과 같습니다:
- 설정 문제 또는 환경 특이사항
- 작업 중 발견된 해결 방법
- 특수 플래그나 구성이 필요했던 명령
- 문제를 일으킨 의존성 또는 임포트
이 정보를 얻는 방법은 출력 형식에서 명시적으로 요청하는 것입니다. 출력 템플릿에 "발생한 장애물" 섹션을 추가하면 이 정보를 안정적으로 드러낼 수 있습니다.
- Obstacles Encountered: Report any obstacles encountered during the review process. This can be: setup issues, workarounds discovered or environment quirks. Report commands that needed a special flag or configuration. Report dependencies or imports that caused problems.
도구 접근 제한하기
모든 서브에이전트가 모든 도구에 접근할 필요는 없습니다. 서브에이전트가 실제로 수행해야 하는 작업을 생각하고, 그 작업에 필요한 도구만 제공하세요. 이는 두 가지 효과가 있습니다: 의도하지 않은 부작용을 방지하고, 여러 서브에이전트를 사용할 때 각 서브에이전트의 역할을 더 명확하게 만듭니다.
일반적인 서브에이전트 유형에 대한 도구 접근 방식은 다음과 같습니다:
- 조사 / 읽기 전용 서브에이전트 --
Glob,Grep,Read만 필요합니다. 파일을 실수로 수정할 수 없습니다. - 코드 리뷰어 --
git diff를 실행하고 변경 사항을 확인하기 위해Bash접근이 필요하지만, 여전히Edit나Write는 필요하지 않습니다. - 스타일링 / 코드 수정 에이전트 -- 이 경우에는
Edit와Write접근 권한을 부여합니다. 서브에이전트의 역할이 실제로 코드를 변경하는 것이기 때문입니다.
종합하기
효과적인 서브에이전트는 네 가지 특징을 공유합니다:
- 구체적인 설명 -- 설명은 서브에이전트가 언제 실행되는지와 어떤 지시를 받는지를 제어합니다. 이 둘을 모두 조정할 수 있도록 작성하세요.
- 구조화된 출력 -- 시스템 프롬프트에 출력 형식을 정의하여 서브에이전트가 작업이 끝났음을 알고 메인 스레드가 사용할 수 있는 정보를 반환하도록 하세요.
- 장애물 보고 -- 출력 형식에 해결 방법, 특이사항, 문제를 위한 섹션을 포함시켜 메인 스레드가 이를 다시 발견할 필요가 없도록 하세요.
- 제한된 도구 접근 -- 서브에이전트에게 실제로 필요한 도구만 제공하세요. 조사에는 읽기 전용, 리뷰어에는 bash, 코드를 변경해야 하는 에이전트에만 edit/write를 제공하세요.
이러한 패턴들은 각각 단순하지만, 함께 적용하면 서브에이전트를 모호하게 도움을 주려는 존재에서 제시간에 작업을 마치고 명확하게 보고하는 집중력 있고 예측 가능한 작업자로 바꿔줍니다.