agent-teams · diff
git:20260422.c75d972 to git:20260613.bb5ed3b
46 added, 84 removed. Audit A to A.
---
name: agent-teams
- description: |
- Agent Teams를 활용하여 대규모 작업을 병렬 처리합니다.
- Team Lead가 Teammates를 조율하여 독립 작업을 병렬 실행합니다.
- Opus 4.6 필수, 환경변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 필요.
+ description: Large-scale parallel work guidance. Routes 10+ parallel independent tasks to native dynamic workflows (ultracode), with legacy experimental Agent Teams as fallback.
model: opus
effort: high
---
- # Agent Teams 스킬
+ # Agent Teams / 대규모 병렬 처리 스킬
- > ⚠️ 실험적 기능 — `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 환경변수 필요
- > Opus 4.6의 Agent Teams로 대규모 작업을 병렬 처리
+ > **Spec 2 / W-006 업데이트:** 대규모 병렬 오케스트레이션의 1순위는 이제 네이티브
+ > **dynamic workflow(`ultracode`)** 입니다. 실험적 자체 Agent Teams 조율은 네이티브가
+ > 흡수했으며, 이 스킬은 그 경로를 안내합니다.
---
## 사용 시점
```
- ✅ 사용:
+ ✅ 대규모 병렬:
- Large 작업 (10개 이상 파일 변경)
- 병렬 가능한 독립 작업 (테스트 + 문서 + 구현)
- - 장기 실행 작업 (1시간 이상)
+ - 장기 실행 작업
❌ 사용하지 않음:
- - Small 작업 (기존 Task tool 사용)
- - 순차 의존 작업 (A 완료 후 B 시작)
- - Sonnet/Haiku 모델 사용 시
+ - Small/Medium 작업 → auto-dev 스킬 주도 플랫 위임 (main이 Agent 병렬 dispatch)
+ - 순차 의존 작업 (A 완료 후 B)
```
- ---
-
- ## 사전 조건
-
- ```bash
- # 환경변수 설정 필수
- export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
-
- # 설정 여부 확인
- echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
- ```
+ > 오케스트레이션 모델 전체: `CLAUDE.md` → "Orchestration Model — Scale-Appropriate Primitives"
---
- ## 실행 방법
+ ## 1순위: 네이티브 Dynamic Workflow (`ultracode`)
- ### 1. 팀 구성
+ 네이티브 워크플로우 엔진이 백그라운드에서 10~100+ 에이전트를 오케스트레이션하며,
+ main 컨텍스트를 소비하지 않습니다.
```
- TeamCreate(
- team_name: "feature-team",
- description: "기능 구현 팀",
- agent_type: "facilitator-teams" # Lead 에이전트
- )
- ```
-
- ### 2. Teammates 할당
+ 사용자가 프롬프트에 ultracode 키워드로 트리거:
+ ultracode <대규모 작업 설명>
+ - 백그라운드 오케스트레이션 + 라이브 에이전트 카운트
+ - /workflows 로 실행 현황 확인
```
- # 병렬로 Teammates 생성
- Task(subagent_type="implement-code", team_name="feature-team",
- name="implementer", prompt="...")
- Task(subagent_type="write-tests", team_name="feature-team",
- name="tester", prompt="...")
-
- Task(subagent_type="review-code", team_name="feature-team",
- name="reviewer", prompt="...")
- ```
+ > ⚠️ `ultracode`는 **사용자 대화형 트리거 전용**입니다 — 스킬/비대화형에서 프로그래밍
+ > 호출이 불가합니다(2026.6 기준). 따라서 auto-dev는 Large 작업을 감지하면 청크로
+ > 분할해 안내하고, 실제 대규모 병렬은 사용자가 `ultracode`로 시작합니다.
- ### 3. Lead가 조율
+ ### auto-dev와의 연계
- ```
- # Lead(facilitator-teams)가 자동으로:
- - Teammate 진행 상황 모니터링
- - 결과 통합 (synthesizer 역할)
- - 충돌 해결 (consensus-builder 역할)
- - 최종 보고서 생성
- ```
+ auto-dev가 Work `size: Large`를 만나면:
+ 1. 독립 청크로 분할 (blockedBy 기반)
+ 2. 청크가 소수면 → 스킬 주도 병렬 dispatch
+ 3. 청크가 다수(10+)면 → 사용자에게 `ultracode` 트리거 안내
---
- ## 역할 배분 가이드
-
- ### 권장 팀 구성
-
- | 작업 유형 | Lead | Teammates |
- | --------------- | ----------------- | ----------------------------------------------------- |
- | **기능 구현** | facilitator-teams | implement-code, write-tests, sync-docs |
- | **리팩토링** | facilitator-teams | plan-refactor, implement-code, verify-code |
- | **다관점 리뷰** | facilitator-teams | 관점별 에이전트 (/multi-perspective-review 사용 권장) |
+ ## 역할 배분 가이드 (병렬 구성 참고)
- ### Teammate 수 제한
+ | 작업 유형 | 병렬 구성 (Teammates/에이전트) |
+ | --------------- | ----------------------------------------------------- |
+ | **기능 구현** | implement-code, write-tests, sync-docs |
+ | **리팩토링** | plan-refactor, implement-code, verify-code |
+ | **다관점 리뷰** | `/multi-perspective-review` 사용 권장 |
- ```
- 권장: 3-5개 Teammates
- 최대: 8개 (그 이상은 조율 오버헤드 증가)
- ```
+ 권장 병렬 수: 3-8개 (그 이상은 `ultracode`에 위임).
---
- ## multi-perspective-review와의 관계
-
- MPR 스킬은 CALC-001 점수 >= 9일 때 자동으로 Agent Teams 모드를 사용합니다.
- 이 스킬은 MPR 외의 **일반 작업**에서 Agent Teams를 직접 사용할 때 활용합니다.
+ ## 레거시: 실험적 Agent Teams (선택)
- | 상황 | 사용 스킬 |
- | ---------------- | --------------------------------------------------- |
- | 다관점 리뷰 | `/multi-perspective-review` (Agent Teams 자동 선택) |
- | 대규모 기능 구현 | `/agent-teams` (이 스킬) |
- | 대규모 리팩토링 | `/agent-teams` (이 스킬) |
+ `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 환경에서 `TeamCreate` + `Task(team_name=...)`
+ 조합이 여전히 동작할 수 있으나, **네이티브 `ultracode`로 대체**되었습니다. 신규 작업은
+ `ultracode`를 사용하세요. 이 경로는 하위호환을 위해서만 남아 있습니다.
---
- ## 제약사항
+ ## multi-perspective-review와의 관계
- - **모델**: Opus 4.6 필수
- - **환경변수**: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
- - **비용**: 여러 세션 동시 실행으로 토큰 비용 증가
- - **안정성**: 실험적 기능 (프로덕션 주의)
- - **POL-002**: 토큰 한도 300K (Subagent 모드의 2배)
+ | 상황 | 사용 |
+ | ---------------- | ------------------------------------------------- |
+ | 다관점 리뷰 | `/multi-perspective-review` |
+ | 대규모 기능/리팩토링 | `ultracode` (네이티브) 또는 auto-dev 청크 분할 |
---
## 참조
- | 문서 | 위치 |
- | --------------------------- | ------------------------------------------------------- |
- | facilitator-teams 에이전트 | plugins/common/agents/meta/facilitator-teams.md |
- | MPR 스킬 (Agent Teams 모드) | plugins/common/skills/multi-perspective-review/SKILL.md |
- | Phase Gate 패턴 | docs/architecture/phase-gate-pattern.md |
+ | 문서 | 위치 |
+ | ------------------- | ------------------------------------------------------- |
+ | 오케스트레이션 모델 | `CLAUDE.md` → Orchestration Model |
+ | auto-dev 파이프라인 | `plugins/common/skills/auto-dev/SKILL.md` |
+ | MPR 스킬 | `plugins/common/skills/multi-perspective-review/SKILL.md` |