모두가 클로드 코드를 한 명의 요원처럼 대하지만, 그것은 군대가 될 수 있다

클로드 코드는 개발자가 아니어도 정말 놀라운 도구입니다. 하지만 클로드 프로 구독자들이 결코 시도하지 않는 것들이 엄청나게 많습니다.

그러한 것들 중 하나는 동시에 여러 하위 에이전트를 생성하는 능력을 사용하여 작업을 완료하는 것이며, 이는 완전히 게임 체인저입니다.

클로드 코드를 한 명의 직원처럼 대하는 것을 그만둬라

전체 팀을 구성하세요!

대부분의 사람들이 Claude Code를 사용하는 방식은 이렇습니다: 터미널을 열고, 작업을 지시하고, 파일을 읽고 변경하는 것을 지켜보고, 완료될 때까지 기다린 다음, 다음 작업을 지시합니다. 한 에이전트, 한 작업, 시작부터 끝까지 순차적으로 진행됩니다.

이것은 대부분의 경우 잘 작동합니다. 하지만 한계가 있으며, 실제로 움직이는 부품이 있는 작업을 할 때 그 한계가 드러납니다. 테스트를 작성해야 할 때 새로운 기능을 개발하는 것. 문서를 업데이트해야 할 때 모듈을 리팩토링하는 것. 어떤 것이 어떻게 연결되어 있는지 이해하기 위해 세 가지 다른 각도에서 코드베이스를 탐험하는 것. 단일 세션 모델에서는, 그 모든 것이 대기열입니다. 모든 것이 기다립니다.

다른 문제는 문맥입니다. 하나의 세션이 길어질수록 문맥 창은 모든 것으로 채워집니다: 파일 내용, 중간 추론, 검색 결과, 두 시간 전에 내린 결정들. 스레드가 길어질수록 모델의 집중력은 저하됩니다. 품질은 처음에는 미묘하게, 그다음에는 눈에 띄게 떨어집니다.

서브에이전트는 이 두 가지 문제를 동시에 해결합니다. 한 에이전트가 모든 것을 처리하는 대신, 메인 세션은 조정자가 됩니다. 메인 세션은 작업을 여러 조각으로 나누고, 각각의 조각을 서브에이전트에 위임하며, 각 서브에이전트는 자신만의 고유한 집중 작업을 수행하는 격리된 컨텍스트 창에서 실행됩니다. 이들은 병렬로 실행될 수 있습니다. 작업이 끝나면 메인 세션이 그 결과를 받아 이어서 진행합니다.

메인 세션은 절대 부풀어 오르지 않기 때문에 날카롭게 유지됩니다. 하위 에이전트들은 각각 자기 자신의 좁은 작업만 알고 있기 때문에 날카롭게 유지됩니다. 그리고 전체 과정은 어느 누구도 큐에서 기다리지 않기 때문에 더 빨리 진행됩니다.

서브에이전트 설정 방법

AI를 사용하여... AI를 만들다

이것은 들리는 것보다 쉽습니다. 전달해야 할 특별한 플래그나 찾아야 할 구성 파일은 없습니다. Claude Code의 서브에이전트는 단지 폴더 안에 있는 마크다운 파일일 뿐입니다.

두 가지 장소에 이를 배치할 수 있습니다. ~/.claude/agents/는 전역(global)이며, 이는 여러분의 컴퓨터에서 실행되는 모든 Claude Code 세션이 그곳에 있는 에이전트를 사용할 수 있다는 의미입니다. 특정 프로젝트 내의 .claude/agents/는 해당 프로젝트에만 국한되며, 이는 저장소에 커밋되고 팀과 공유되는 에이전트를 원할 때 유용합니다.

각 에이전트는 상단에 YAML 프론트매터 블록이 있고 본문에 시스템 프롬프트가 있는 단일 마크다운 파일입니다. 매우 기본적인 예시는 다음과 같습니다:

---
name: swift-engineer
description: Use this agent when SwiftUI views or Swift networking code needs to be written. Invoke for any iOS screen, ViewModel, or async/await networking work.
model: claude-sonnet-4-6
tools: Read, Write, Glob
---
You are a senior iOS engineer writing Swift only. Follow MVVM strictly: views are dumb, logic lives in ViewModels, all network calls use async/await.
Before writing anything, read the existing project structure with Glob and match whatever conventions are already in place. Return a list of every file you created or modified.

name은 당신과 Claude가 그것을 지칭하는 방식입니다. description은 실제로 주요 에이전트가 언제 그것을 사용할지를 결정할 때 중요한 부분입니다. 설명을 작성할 때는 라우팅 규칙처럼 작성하여, 언제 호출할지와 무엇을 반환하는지 구체적으로 기술하세요. 모호한 설명은 모호한 라우팅을 초래합니다. '이 에이전트를 사용할 때...'라는 특정 조건을 뒤따르는 패턴이 효과적입니다.

tools 필드는 허용 목록입니다. 테스트 작성자는 아마도 파일을 삭제할 필요가 없습니다. 코드 리뷰어는 아마도 쓰기 권한이 전혀 없어야 합니다. 에이전트별로 도구를 잠그는 것은 보안과 안정성 측면에서 여기서 할 수 있는 가장 유용한 작업 중 하나입니다.

파일을 직접 작성하고 싶지 않은 경우, Claude Code에는 대화형 관리자를 여는 /agents 명령어가 있습니다. 원하는 것을 설명하면 Claude가 에이전트 구성을 작성해 주고, 저장할 범위를 선택할 수 있습니다. Claude가 만드는 설명은 대부분 사람들이 처음 시도할 때 수동으로 작성하는 것보다 더 좋은 편입니다.

이제 Claude에게 에이전트가 수행하도록 만들어진 일을 요청하면, 설명이 충분히 구체적일 경우 자동으로 경로를 지정합니다.

병렬 작업의 경우, 주요 에이전트에 대한 프롬프트는 간단합니다. 예를 들어:

I'm building an iOS app with a Swift frontend and a Swift Vapor backend.
Spawn three subagents in parallel:
1. Use the swift-engineer subagent. Build the SwiftUI login screen and dashboard.
2. Use the backend-engineer subagent. Build Vapor API endpoints for /auth/login
3. Use the test-writer subagent. Write tests for the API endpoints and Swift ViewModels.

각 하위 에이전트는 자체 컨텍스트에서 동시에 실행되며, 독립적으로 보고합니다. 세 개가 모두 종료되면 메인 세션이 다시 시작됩니다. 점점 부풀어 오르는 컨텍스트 스레드로 세 번의 연속 검색이 진행되었을 작업이 이제 동시에 실행되는 세 개의 깨끗하게 분리된 작업자가 됩니다.

많은 작업에 타당합니다

더 나은 일을 더 빠르게 수행하세요

모든 것이 하위 에이전트로부터 이익을 얻는 것은 아닙니다. 변수를 이름 바꾸기 위해 세 명의 에이전트를 사용하는 것은 누구의 시간이나 토큰을 사용하는 데에도 좋은 방법이 아닙니다. 토큰 비용은 실제로 존재합니다: 하위 에이전트가 많이 사용된 워크플로우는 같은 작업을 단일 세션 방식으로 처리하는 것보다 훨씬 더 많은 토큰을 사용할 수 있습니다. 때로는 그 이상일 수도 있습니다. 이러한 거래(offering)는 절대 가치가 있지만, 올바른 상황에서만 그렇게 할 가치가 있습니다.

코드베이스 탐색은 에디터와 함께 사용할 때 가장 확실한 이점입니다. 큰 프로젝트에서 무언가가 어떻게 동작하는지 이해해야 할 때, 본질적으로 여러 각도에서 여러 검색을 수행하는 것과 같습니다. 각 각도마다 하나의 서브 에이전트가 있으며, 모두 동시에 실행되고 각자는 자신의 문맥에서 필요한 것을 읽고 집중된 요약을 반환합니다.

테스트 커버리지는 내가 계속 돌아오는 또 다른 주제입니다. 테스트를 작성하는 것은 거의 정의상 병렬화가 가능합니다. 모듈당 한 개의 서브에이전트가 각각 커버리지를 독립적으로 작성하며, 어느 누구도 다른 사람을 기다리지 않습니다.

익숙해지려면 약간의 연습이 필요하다

이 모든 것을 연결하는 패턴은 독립성입니다. 두 작업이 상태를 공유해야 하거나 한 작업이 다른 작업의 출력을 필요로 한다면, 그것들은 메인 스레드에 속합니다. 서로에 대해 알 필요 없이 실행될 수 있다면, 그것들은 서브 에이전트의 후보가 됩니다. 이 경계는 일단 주의를 기울이면 보통 꽤 명확합니다.

그러나 이 접근 방식에는 한 가지 문제가 있는데, 그것은 토큰 사용입니다. 여러 에이전트를 동시에 사용하면 토큰이 빠르게 소모되지만 걱정하지 마세요. 로컬 LLM과 결합하여 Claude Code를 무료로 사용할 수도 있으므로 토큰이 절대 부족하지 않습니다.