Claude Code를 더 잘 활용하기 ⑤｜서브 에이전트(Sub-agent) 만드는 법·실전 사례

안녕하세요, 개발비요리(開発日和)입니다.

Part 4에서 서브 에이전트(Sub-agent)의 개념을 설명했습니다. 이번에는 "실제로 어떻게 사용하는가"를 구체적인 상황에서 살펴보겠습니다. "대충은 알겠는데 내 업무에 어떻게 쓸 수 있을지 모르겠다"는 분들을 위한 내용입니다.

서브 에이전트를 기동하는 방법

방법 ① Claude에게 맡기기 (자동)

복잡한 태스크를 던지면, Claude가 판단하여 서브 에이전트를 사용합니다. 의식하지 않아도 사용되고 있는 경우가 많습니다.

처음에는 대부분 이 상태일 것이며, 어느샌가 움직이고 있다는 느낌을 받게 될 것입니다.

> 이 리포지토리(Repository) 전체를 조사해서, 퍼포먼스(Performance)에 문제가 있을 법한 부분을 모두 리스트업해줘

배후에서 Explore 에이전트가 조사를 수행하고, 결과를 메인 세션(Main Session)으로 반환해 줍니다.

방법 ② /background로 명시적으로 기동하기

> /background 모든 테스트를 실행하고 실패한 것을 알려줘

백그라운드(Background)에서 에이전트가 움직이기 시작하며, 완료되면 알림이 옵니다. 그동안 다른 작업을 할 수 있습니다.

방법 ③ 프롬프트(Prompt)로 역할 지정하기

> 조사 전문 에이전트로서, app/Services/ 디렉토리를 읽고
각 클래스의 역할과 의존 관계를 정리해줘

명시적으로 역할을 부여함으로써, 해당 태스크에 집중하는 에이전트를 만들 수 있습니다.

실전 사례 ① 대규모 리팩터링 (Refactoring)

상황: 오래된 프로젝트의 코드를 정리하고 싶을 때

> 다음을 병행해서 진행해줘:
1. app/Http/Controllers/를 조사해서, 비즈니스 로직(Business Logic)이 혼재된 컨트롤러를 리스트업
2. app/Services/로 이동해야 할 처리를 정리
...

3개의 조사가 동시에 실행되므로, 직렬로 처리하는 것보다 훨씬 빠릅니다. 단, 비용(Cost)도 3배 가까이 들기 때문에, 정말 병행이 필요한 양인지 생각한 뒤에 사용합시다.

결국 전부 다 할 거라면 똑같다고 생각하기에, 병행할 수 있다면 병행시켜 버려도 좋다고 생각합니다만.

AI는 상당히 빠른 속도로 진행되기 때문에, 병행해서 움직이는 작업 각각을 파악하고 있어야 하는 작업이라면 하나씩 진행하는 편이 좋을지도 모릅니다.

실전 사례 ② 코드 리뷰와 수정의 분업

상황: 구현한 코드를 철저하게 검토하고 싶을 때

> 다음을 서로 다른 에이전트로 진행해줘:
- 에이전트 A: 보안 관점에서 리뷰하고 문제점을 리스트업
- 에이전트 B: 퍼포먼스 관점에서 개선점을 리스트업
...

관점을 나누면 각각의 시야가 깊어집니다.

사람과 같습니다.

혼자서 작업을 진행하다 보면 알 수 없는 것도, 다른 사람의 관점에서 보면 사소한 것이라도 발견되는 경우가 자주 있습니다.

실전 사례 ③ 문서 생성 (Documentation)

상황: 대량의 컨트롤러 API 문서를 한꺼번에 만들고 싶을 때

> /background app/Http/Controllers/ 이하의 모든 컨트롤러를 읽고,
각 엔드포인트(Endpoint)의 Markdown 형식 API 문서를 docs/api/에 생성해줘

시간이 걸리는 작업을 백그라운드에 맡기고, 자신은 다른 작업으로 넘어갈 수 있습니다.

예를 들어, 문서 작성도 한차례 만들어 두고 싶지만, 자신은 구현 작업을 진행하거나 행동 계획을 세우고 싶을 때 등입니다.

자신의 작업이 끝날 때쯤 AI도 작업을 마쳐서, 이를 조합한 뒤 다음 작업으로 넘어가는 것도 가능합니다.

인간 팀 멤버에게 일을 맡기는 것과 비슷한 느낌이네요.

막혔던 포인트: 정보를 전달하지 않으면 아무것도 모른다

서브 에이전트는 독립되어 있으므로, 메인 세션의 대화 문맥(Context)을 알지 못합니다. 이를 잊으면 "아까 결정한 사양대로 해줘"라는 말이 통하지 않아 막히게 됩니다.

나쁜 예:

> /background 아까 그 설계대로 구현해줘

(서브 에이전트는 "아까 그 설계"를 모릅니다)

좋은 예:

> /background 다음 사양으로 UserService 클래스를 구현해줘:
- 사용자 등록·로그인·탈퇴의 3가지 메서드(Method)를 가질 것
- 유효성 검사(Validation)는 FormRequest에 맡길 것
...

필요한 정보는 매번 명시적으로 전달하는 것이 기본입니다.

다만, 이것은 에이전트 단독일 때뿐만 아니라 동일 세션 내에서도 일어날 수 있는 일이므로,

너무 모호한 표현은 피하고, 가능한 한 구체적으로 AI가 이해하기 쉬운 언어로 소통하면,

의도나 목적이 더 잘 전달되어 기대한 대로 동작할 확률이 높아집니다.

너무 세세하게 작성하면 효율이 떨어진다고 생각할 수도 있지만, 그럼에도 작업 속도가 매우 빠르기 때문에,

다소 시간을 할애하여 AI를 위한 지시서(Instruction) 작성이나 표현 방법을 고민해 보는 것도 좋을 것입니다.

상태 확인 및 정지

> /agents

현재 동작 중인 에이전트, 완료된 에이전트, 실패한 에이전트의 목록을 확인할 수 있습니다.

의도치 않게 계속 동작하고 있는 에이전트가 있다면 여기서 정지할 수 있습니다. 긴 작업이 끝난 후에는 한 번씩 확인하는 습관을 들여두면 안심할 수 있습니다.

요약

사용법	커맨드·방법
Claude가 자동 판단하게 하기	복잡한 태스크를 그대로 던지기
...

다음 Part 6에서는 Claude Code의 Skill 기능(슬래시 커맨드 커스터마이징)에 대해 해설합니다.

개발비요(開発日和)에서는 Claude Code의 사용법을 실제 경험을 바탕으로 발신하고 있습니다.

질문이나 감상은 댓글 또는 X의 @webpull로 보내주세요.

Discussion