116 lines
6.6 KiB
Markdown
116 lines
6.6 KiB
Markdown
# 멀티에이전트 워크플로우
|
|
|
|
> Claude가 서브에이전트를 스폰하고 조율해 복잡한 작업을 병렬화하는 방법.
|
|
|
|
Claude Code는 서브에이전트 — 독립적으로 실행되어 병렬로 작업을 완료하는 별도의 Claude 인스턴스 — 를 스폰할 수 있습니다. 단일 대화에서 순차적으로 모든 것을 하는 대신, 동시에 실행하는 특화 에이전트로 분할해서 크고 다단계 작업을 처리할 수 있습니다.
|
|
|
|
## 서브에이전트 작동 방식
|
|
|
|
Claude가 `Agent` 도구를 사용하면, 자체 컨텍스트, 시스템 프롬프트, 도구 권한을 가진 새 Claude 인스턴스를 시작합니다. 부모 Claude는 에이전트가 완료될 때까지 기다리거나(또는 에이전트가 백그라운드에서 실행 중이면 다른 작업을 계속합니다), 그 후 에이전트의 결과를 단일 메시지로 받습니다.
|
|
|
|
각 에이전트는:
|
|
- 새 컨텍스트 윈도우로 시작 (fork가 아닌 한)
|
|
- 에이전트 타입에 따라 특화된 시스템 프롬프트 적용
|
|
- 자체 도구 권한 (에이전트 타입별로 설정 가능)
|
|
- 추가 서브에이전트를 스폰 가능 (단, 중첩은 제한됨)
|
|
|
|
## Agent 도구
|
|
|
|
Claude가 `Agent` 도구를 사용해 서브에이전트를 스폰합니다. 이 도구를 직접 호출하는 것이 아니라 Claude가 필요할 때 결정합니다. 터미널에서 에이전트 스폰을 볼 수 있습니다 — 자체 진행 표시기와 함께 나타납니다.
|
|
|
|
도구 파라미터:
|
|
- `description` — 에이전트가 할 일의 3-5단어 요약 (UI에 표시)
|
|
- `prompt` — 에이전트에 대한 전체 작업 설명
|
|
- `subagent_type` — 사용할 특화 에이전트 타입 (선택사항; 기본값은 범용)
|
|
- `run_in_background` — 비동기 실행 여부
|
|
- `isolation` — `"worktree"`로 격리된 git worktree 제공
|
|
|
|
## Claude가 서브에이전트를 사용하는 경우
|
|
|
|
작업이 병렬 처리나 특화에 도움이 될 때 에이전트를 스폰합니다:
|
|
- **독립적 병렬 작업** — 문서 업데이트와 동시에 테스트 작성
|
|
- **특화 작업** — 보안 감사를 위한 코드 리뷰어 에이전트 사용
|
|
- **장시간 실행 작업** — 다른 것을 작업하는 동안 백그라운드 리서치
|
|
- **격리된 탐색** — 메인 컨텍스트를 오염시키지 않고 솔루션 탐색을 위해 자신을 포크
|
|
|
|
## 멀티에이전트 워크플로우 요청
|
|
|
|
Claude에게 명시적으로 여러 에이전트 사용을 요청할 수 있습니다:
|
|
|
|
```
|
|
linter와 test suite를 병렬로 실행해줘.
|
|
```
|
|
|
|
```
|
|
세 경쟁 라이브러리가 이 문제를 어떻게 처리하는지 별도의 에이전트로 조사한 후 결과를 요약해줘.
|
|
```
|
|
|
|
```
|
|
보안 에이전트가 이 코드 변경의 보안 영향을 검토하는 동안 기능 구현을 계속해줘.
|
|
```
|
|
|
|
> 💡 Claude에게 에이전트를 "병렬로" 실행하도록 요청하면, 여러 Agent 도구 호출을 포함하는 단일 메시지를 전송해 모두 동시에 시작합니다.
|
|
|
|
## 포그라운드 vs 백그라운드 에이전트
|
|
|
|
기본적으로 에이전트는 **포그라운드**에서 실행됩니다 — Claude가 계속하기 전에 각 에이전트가 완료될 때까지 기다립니다. Claude가 결과를 계속 작업하는 데 필요한 경우 포그라운드 에이전트를 사용하세요.
|
|
|
|
백그라운드 에이전트는 비동기로 실행됩니다. Claude가 시작하고 다른 작업을 계속합니다. 에이전트가 완료되면 알림을 받습니다.
|
|
|
|
```
|
|
다음 기능을 구현하는 동안 통합 테스트를 백그라운드에서 실행해줘.
|
|
```
|
|
|
|
> ⚠️ 실행 중인 백그라운드 에이전트의 출력 파일을 직접 확인하도록 Claude에게 요청하지 마세요. Claude는 자동으로 완료 알림을 받습니다.
|
|
|
|
## 코디네이터 모드
|
|
|
|
코디네이터 모드에서 Claude는 모든 구현 작업을 서브에이전트에 위임하고 계획, 라우팅, 종합에 집중합니다. 매우 큰 작업에 유용하며 서브에이전트가 실질적인 작업을 수행합니다.
|
|
|
|
## 에이전트 메모리와 컨텍스트 격리
|
|
|
|
각 서브에이전트는 **깨끗한 컨텍스트 윈도우**로 시작합니다. 부모 Claude가 에이전트 프롬프트에 전체 작업 설명과 관련 배경을 제공합니다 — 에이전트는 부모의 대화 기록을 자동으로 상속하지 않습니다.
|
|
|
|
**영속 에이전트 메모리:**
|
|
일부 에이전트 타입은 호출 간에 영속 메모리를 가집니다:
|
|
- **사용자 범위**: `~/.claude/agent-memory/<agent-type>/MEMORY.md`
|
|
- **프로젝트 범위**: `.claude/agent-memory/<agent-type>/MEMORY.md`
|
|
- **로컬 범위**: `.claude/agent-memory-local/<agent-type>/MEMORY.md`
|
|
|
|
## Worktree 격리
|
|
|
|
`isolation: "worktree"`를 설정해 에이전트에게 자체 git worktree를 제공합니다 — 저장소의 격리된 복사본. 에이전트가 만드는 변경 사항은 사용자가 병합하기 전까지 작업 디렉토리에 영향을 주지 않습니다.
|
|
|
|
```
|
|
내가 변경 사항을 검토하고 병합할 수 있도록 격리된 worktree에서 이 기능을 구현해줘.
|
|
```
|
|
|
|
## 효과적인 에이전트 프롬프트 작성
|
|
|
|
서브에이전트는 부모 대화의 컨텍스트가 없이 시작합니다. 좋은 에이전트 프롬프트에는 다음이 포함됩니다:
|
|
- 달성하려는 것과 이유
|
|
- 관련 파일 경로, 함수 이름, 데이터
|
|
- 에이전트가 보고해야 할 내용(형식, 길이, 답해야 할 질문)
|
|
- 에이전트가 하면 안 되는 것(범위 제약)
|
|
- 이미 시도했거나 배제한 것
|
|
|
|
**나쁜 프롬프트:**
|
|
```
|
|
버그를 수정해줘.
|
|
```
|
|
|
|
**좋은 프롬프트:**
|
|
```
|
|
src/services/user.ts:247의 UserService.getProfile()에 있는 null 참조 버그를 수정해줘.
|
|
사용자에게 연관된 프로파일 레코드가 없을 때 버그가 발생합니다 — getProfile()이 profile이 null인지 먼저 확인하지 않고 profile.preferences를 호출합니다. null 체크를 추가하고 기본 설정 객체 { theme: 'light', notifications: true }를 반환하세요.
|
|
그 후 npm test를 실행해 수정 사항이 기존 테스트를 통과하는지 확인하세요.
|
|
```
|
|
|
|
## 제한사항
|
|
|
|
- 서브에이전트는 기본적으로 `acceptEdits` 모드를 사용합니다
|
|
- 에스케이프를 누르면 부모 턴을 취소하지만 실행 중인 백그라운드 에이전트는 취소하지 않습니다 — 작업 패널에서 명시적으로 취소하세요
|
|
- 서브에이전트는 다른 팀메이트를 스폰할 수 없습니다 (팀 로스터는 플랫)
|
|
- 포크 에이전트는 자신을 다시 포크할 수 없습니다
|
|
- 에이전트 결과는 부모에 반환되기 전에 100,000자로 제한됩니다
|