Claude docs 클로드 공식문서 뽀개기 2. Agents 와 병렬 작업

Agents 병렬으로 실행하기

클로드 코드에서 여러 작업을 동시에 수행(병렬)하기 위한 4가지 주요 방식

방식	주요 기능	추천 사용 상황
Subagents	한 세션 내에서 부가 작업을 독립 컨텍스트로 수행하고 요약만 반환	검색 결과, 로그, 파일 내용 등으로 메인 대화창이 더러워지는 것을 방지하고 싶을 때
Agent view	`claude agents` 명령어로 백그라운드 세션들을 한 화면에서 모니터링/제어	여러 독립 작업을 맡겨두고 상태만 확인하다 필요할 때만 개입하고 싶을 때
Agent teams	리드 에이전트가 관리하는 여러 세션이 작업 목록을 공유하며 상호 통신	큰 프로젝트를 분할, 할당하고 작업자 간 동기화를 유지하고 싶을 때
Dynamic workflows	스크립트를 통해 수많은 서브에이전트를 실행하고 결과를 교차 검증	전체 코드베이스 감사, 500개 파일 마이그레이션 등 규모가 매우 큰 작업을 할 때

병렬 작업 지원하는 주요 보조 도구

1) Worktrees: 각 세션에 별도 Git Checkout을 제공하여 병렬 세션 간 파일 편집 충돌 방지

2) /batch(스킬): 하나의 큰 변경사항을 5~30개의 작업트리 분리 서브에이전트로 나눠 각각 PR을 올리게 하는 기능

(ex. 프로젝트 전체의 200개 API 엔드포인트에 변경사항이 있을 경우, 알아서 서브에이전트를 나눠 각각 PR하게 함. 만약 이걸 한 번에 한 세션에서 돌리면 에러가 나거나 토큰을 다 써버릴 수 있음.)

에이전트 분할과 목적이 다른 보조 기능들

1) Background Bash Command: 대화를 막지 않고 백그라운드에서 터미널 명령을 돌림(에이전트를 생성하는 것은 아님)

2) Forked Subagent: 지금까지 대화 맥락을 전부 상속받은 새로운 서브에이전트 생성 가능
 > 지금까지 대화한 내용을 따로 설명하지 않고, 한 쪽에서는 A안 다른쪽에서는 B안을 실행해서 테스트 해볼 수 있음.

3) Routine: 앤트로픽 클라우드 서버에서 세션을 자동실행하는 스케줄러. 

Custom Subagents 생성

Built-in subagents

- Explore: 코드 베이스 검색 및 분석에 최적화된 읽기 전용 에이전트

- Plan: 작업 계획을 세우는 에이전트

- General-purpose: 일반적인 백그라운드 처리용 에이전트

Configure subagents

1. Subagent scope 선택하기

- 서브에이전트를 어디에 저장하느냐에 따라 누가, 어디서 사용할 수 있는지 범위가 결정됨.

- 같은 이름의 에이전트가 존재할 경우, 우선순위 높은 파일이 적용됨.

저장 위치	적용 범위	우선 순위	만드는 법
Managed settings	조직(회사) 전체	1	관리자가 배포
`--agents` CLI flag	현재 실행중인 세션 전용	2	Cluade 실행 시 JSON 파라미터 전달
`.claude/agents`	현재 프로젝트 전용	3	Claude에게 부탁하거나 직접 md 파일 작성
`~/.claude/agents`	PC 내 모든 프로젝트	4	Claude에게 부탁하거나 직접 md 파일 작성
Plugin의 `agents/`	플러그인 활성 공간	5	플러그인 설치 시 자동 포함

 

2. Subagnet file 작성하기

- YAML Frontmatter 로 설정값을 적고, 시스템 프롬프트는 마크다운으로 작성.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

 

3. 모델 선택하기

- 서브에이전트가 사용할 모델을 필드로 지정할 수 있으며, 지정하지 않을 경우 매인 대화 세션과 동일한 모델 사용

Agent view로 다중 Agents 관리하기

- 여러 개의 백그라운드 Claude code 세션을 한 화면에서 관찰하고 통제할 수 있는 중앙 대시보드 인터페이스

에이전트 팀 오케스트레이션

- Agent Team은 여러 Claude code 인스턴스가 메인 리드 에이전트의 지휘 아래 하나의 팀처럼 협업하여 복잡한 작업을 분담/진행하는 기능

Subagent와 차이점

	Subagents	Agent teams
Context	자체 컨텍스트 사용, 결과는 메인으로 반환	자체 컨텍스트 사용, 완전 독립적인 세션
Communication	메인 에이전트에게만 결과 보고	팀원(에이전트)끼리 직접 메시지 주고 받음
Coordination	메인 에이전트가 모든 작업 중앙 통제	공유 작업 목록을 통한 자율적 할 일 분담
Best for	결과만 받으면 되는 단발성/집중 작업	서로 토론, 검증, 협업이 필요한 복잡한 작업
Token cost	상대적으로 낮음 (요약 결과만 전달 받음)	상대적으로 높음 (각 팀원이 독립된 Claude 세션)

Best Practices

1. 팀원에게 충분한 맥락(Context) 제공하기
- 팀원 에이전트들은 프로젝트 파일은 자동으로 읽지만, 리드 에이전트와의 이전 대화 기록은 상속받지 않음
- 팀원 생성 요청시, 해당 작업에 필요한 세부 정보와 범위, 요구사항을 명확히 포함 시켜야 함

 

2. 적절한 팀 규모 선택하기
- 팀원 1명당 독립적인 컨텍스트 창을 새로 소비하므로, 수가 늘어날수록 토큰 비용이 급증함
- 팀원이 많아질수록 서로 간의 메시지 교환, 작업 분담, 코드 충돌 관리 부담이 커짐
- 대부분 작업에서는 3~5명의 팀원으로 시작하는 것이 효율적

 

3. 작업 단위는 작고 독립적으로 나누기
- 팀원이 서로 같은 파일이나 의존성이 복잡하게 얽힌 작업을 동시에 하며 충돌이 발생함. 따라서 영역이 완전 분리된 작업 위주로 역할을 부여하는 것이 좋음.

Dynamic workflow를 통한 Subagent 오케스트레이션

: 자바스크립트 기반으로 수십~수백개의 서브에이전트를 백그라운드에서 실행/통제하는 대규모 자동화 기능

주요 사용 상황

- 전체 코드베이스 감사, 대규모 마이그레이션, 교차 검증 연구

Worktree를 활용한 병렬 세션 처리

- 여러 Claude code 세션을 동시에 실행할 때 Git worktree를 사용해 작업 공간을 독립시키고, 파일 변경사항이 서로 충돌하지 않도록 격리할 수 있음. 

>> 각 에이전트가 각자 다른 일들을 수행함에 있어, 중복된 파일을 수정한다거나 하는 일들을 방지하는 것.