@kood/claude-code 0.7.3 → 0.7.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,87 +1,61 @@
|
|
|
1
1
|
# Agent Teams 활용 가이드
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> **Agent Teams를 기본으로 사용한다.** 토큰 비용(5-7x)은 Model Routing으로 최적화.
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
<
|
|
8
|
-
|
|
9
|
-
## ⚠️ 필수 사용 규칙
|
|
7
|
+
<tool_primitives>
|
|
10
8
|
|
|
11
|
-
|
|
9
|
+
## 7가지 Tool Primitives
|
|
12
10
|
|
|
13
|
-
|
|
|
14
|
-
|
|
15
|
-
| **
|
|
16
|
-
|
|
|
17
|
-
| **
|
|
18
|
-
|
|
|
11
|
+
| 도구 | 역할 | 토큰 영향 |
|
|
12
|
+
|------|------|----------|
|
|
13
|
+
| **TeamCreate** | 팀 생성, config.json + task 디렉토리 | 낮음 |
|
|
14
|
+
| **TaskCreate** | 작업 단위 정의 (JSON) | 낮음 |
|
|
15
|
+
| **TaskUpdate** | 상태 변경 (pending→in_progress→completed) | 낮음 |
|
|
16
|
+
| **TaskList** | 사용 가능한 작업 조회 | 낮음 |
|
|
17
|
+
| **Task** (team_name) | 팀원 스폰 | **높음** (~200k/팀원) |
|
|
18
|
+
| **SendMessage** | 팀원 간 메시징 | 중간 |
|
|
19
|
+
| **TeamDelete** | 팀 정리 | 낮음 |
|
|
19
20
|
|
|
20
|
-
###
|
|
21
|
+
### 실행 흐름
|
|
21
22
|
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
Task({ subagent_type: "...", team_name: "skill-team", name: "worker-2", ... })
|
|
27
|
-
Task({ subagent_type: "...", team_name: "skill-team", name: "worker-3", ... })
|
|
28
|
-
|
|
29
|
-
// ❌ 금지: 3개+ 에이전트를 Agent Teams 없이 호출
|
|
30
|
-
Task({ subagent_type: "...", ... })
|
|
31
|
-
Task({ subagent_type: "...", ... })
|
|
32
|
-
Task({ subagent_type: "...", ... }) // Agent Teams 미사용 → 위반
|
|
23
|
+
```
|
|
24
|
+
SETUP: TeamCreate → TaskCreate × N → Task(team_name) × N
|
|
25
|
+
EXECUTION: TaskList → TaskUpdate(claim) → 작업 → TaskUpdate(complete) → SendMessage
|
|
26
|
+
TEARDOWN: shutdown_request × N → TeamDelete
|
|
33
27
|
```
|
|
34
28
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
| 단계 | 필수 행동 |
|
|
38
|
-
|------|----------|
|
|
39
|
-
| **시작** | `TeamCreate` → 팀원 spawn |
|
|
40
|
-
| **완료** | 팀원별 `shutdown_request` 전송 |
|
|
41
|
-
| **해산** | 모든 팀원 종료 확인 → `TeamDelete` |
|
|
42
|
-
|
|
43
|
-
**팀 정리 없이 스킬 종료 금지.**
|
|
44
|
-
|
|
45
|
-
</mandatory_rules>
|
|
29
|
+
</tool_primitives>
|
|
46
30
|
|
|
47
31
|
---
|
|
48
32
|
|
|
49
|
-
<
|
|
33
|
+
<mandatory_rules>
|
|
50
34
|
|
|
51
|
-
##
|
|
35
|
+
## 필수 사용 규칙
|
|
52
36
|
|
|
53
|
-
|
|
37
|
+
| 상황 | 행동 |
|
|
38
|
+
|------|------|
|
|
39
|
+
| **기본 (대부분 작업)** | Agent Teams 사용 |
|
|
40
|
+
| Agent Teams 미가용 | Task 병렬 호출 (폴백) |
|
|
41
|
+
| 단일 파일 읽기/수정 | 직접 처리 (예외) |
|
|
42
|
+
| 단순 질문 응답 | 직접 처리 (예외) |
|
|
54
43
|
|
|
55
|
-
|
|
56
|
-
# Agent Teams 사용 가능 여부 확인
|
|
57
|
-
.claude/scripts/agent-teams/check-availability.sh
|
|
44
|
+
> **"굳이 Agent Teams 안 써도 될 것 같은데" 판단 금지.**
|
|
58
45
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
```
|
|
46
|
+
### 수명주기 필수 관리
|
|
47
|
+
|
|
48
|
+
```typescript
|
|
49
|
+
// 시작
|
|
50
|
+
TeamCreate({ team_name: "...", description: "..." })
|
|
51
|
+
Task({ subagent_type: "...", team_name: "...", name: "worker-1", model: "sonnet" })
|
|
62
52
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
# 1. 환경변수 확인
|
|
67
|
-
if [[ "$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" == "1" ]]; then
|
|
68
|
-
AGENT_TEAMS_AVAILABLE=true
|
|
69
|
-
fi
|
|
70
|
-
|
|
71
|
-
# 2. settings.json 확인 (글로벌 + 프로젝트)
|
|
72
|
-
for f in ~/.claude/settings.json .claude/settings.json; do
|
|
73
|
-
if grep -q '"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS".*"1"' "$f" 2>/dev/null; then
|
|
74
|
-
AGENT_TEAMS_AVAILABLE=true
|
|
75
|
-
fi
|
|
76
|
-
done
|
|
77
|
-
|
|
78
|
-
# 3. 에이전트 디렉토리 확인
|
|
79
|
-
if [[ -d ".claude/agents" ]] && [[ $(ls .claude/agents/*.md 2>/dev/null | wc -l) -gt 0 ]]; then
|
|
80
|
-
AGENTS_AVAILABLE=true
|
|
81
|
-
fi
|
|
53
|
+
// 완료 후 정리 (필수)
|
|
54
|
+
SendMessage({ type: "shutdown_request", recipient: "worker-1", ... })
|
|
55
|
+
TeamDelete()
|
|
82
56
|
```
|
|
83
57
|
|
|
84
|
-
</
|
|
58
|
+
</mandatory_rules>
|
|
85
59
|
|
|
86
60
|
---
|
|
87
61
|
|
|
@@ -89,93 +63,60 @@ fi
|
|
|
89
63
|
|
|
90
64
|
## Subagent vs Agent Teams
|
|
91
65
|
|
|
92
|
-
| 항목 |
|
|
93
|
-
|
|
94
|
-
|
|
|
95
|
-
|
|
|
96
|
-
|
|
|
97
|
-
| **토큰 비용** | 낮음 (결과 요약) | 높음 (각 팀원 별도 인스턴스) |
|
|
98
|
-
| **적합** | 결과만 필요한 집중 작업 | 토론과 협업이 필요한 복잡한 작업 |
|
|
66
|
+
| 항목 | Subagent (Task) | Agent Teams (기본) |
|
|
67
|
+
|------|-----------------|-------------------|
|
|
68
|
+
| **통신** | 메인에게만 보고 | 팀원 간 직접 메시징 |
|
|
69
|
+
| **조율** | 메인이 관리 | 공유 TaskList로 자기조율 |
|
|
70
|
+
| **토큰** | 낮음 | Model Routing으로 최적화 |
|
|
99
71
|
|
|
100
72
|
### 선택 기준
|
|
101
73
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
| 토큰 비용 민감 | Subagent 또는 단독 세션 |
|
|
107
|
-
| 병렬 연구/리뷰 | Agent Teams |
|
|
108
|
-
| 단순 작업 (1-2 파일) | 직접 처리 |
|
|
109
|
-
|
|
110
|
-
</subagent_vs_teams>
|
|
111
|
-
|
|
112
|
-
---
|
|
113
|
-
|
|
114
|
-
<decision_matrix>
|
|
115
|
-
|
|
116
|
-
## 사용 결정 매트릭스
|
|
74
|
+
```
|
|
75
|
+
기본 (대부분 작업) → Agent Teams
|
|
76
|
+
단일 파일 읽기/수정 → 직접 처리
|
|
77
|
+
```
|
|
117
78
|
|
|
118
|
-
|
|
119
|
-
|------|----------|------|
|
|
120
|
-
| Agent Teams 비활성화 | Task (subagent) | 환경 미지원 |
|
|
121
|
-
| 단순 작업 (1-2 파일) | 직접 처리 | 오버헤드 불필요 |
|
|
122
|
-
| 독립적 병렬 작업 | Agent Teams | 진정한 병렬 실행 |
|
|
123
|
-
| 팀원 간 소통 필요 | Agent Teams | 메시지 교환 가능 |
|
|
124
|
-
| 순차 의존성 있음 | blockedBy 또는 Subagent | 의존성 관리 |
|
|
125
|
-
| tmux/iTerm2 환경 | split-pane 모드 | 시각적 모니터링 |
|
|
126
|
-
| VS Code/일반 터미널 | in-process 모드 | 호환성 |
|
|
79
|
+
**Subagent 대신 Agent Teams를 쓴다.** 토큰 비용은 Model Routing(Sonnet/Haiku)으로 해결.
|
|
127
80
|
|
|
128
|
-
</
|
|
81
|
+
</subagent_vs_teams>
|
|
129
82
|
|
|
130
83
|
---
|
|
131
84
|
|
|
132
|
-
<
|
|
85
|
+
<cost_optimization>
|
|
133
86
|
|
|
134
|
-
##
|
|
87
|
+
## 토큰 비용 최적화
|
|
135
88
|
|
|
136
|
-
###
|
|
89
|
+
### 비용 구조
|
|
137
90
|
|
|
138
|
-
|
|
|
139
|
-
|
|
140
|
-
|
|
|
141
|
-
|
|
|
142
|
-
|
|
|
91
|
+
| 구성 | 토큰 | 배수 |
|
|
92
|
+
|------|------|------|
|
|
93
|
+
| Solo Session | ~200k | 1x |
|
|
94
|
+
| 3 Subagents | ~440k | 2.2x |
|
|
95
|
+
| 3-Person Team | ~800k | **4x** |
|
|
96
|
+
| Plan Mode Team | - | **7x** |
|
|
143
97
|
|
|
144
|
-
###
|
|
98
|
+
### 절약 전략 (우선순위순)
|
|
145
99
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
}
|
|
154
|
-
```
|
|
100
|
+
| 전략 | 효과 | 방법 |
|
|
101
|
+
|------|------|------|
|
|
102
|
+
| **Model Routing** | 40% 절감 | Lead: Opus, Teammates: Sonnet/Haiku |
|
|
103
|
+
| **Plan-First** | 낭비 방지 | 계획(10k) → 승인 → 실행 |
|
|
104
|
+
| **팀 즉시 정리** | 유휴 비용 제거 | 완료 즉시 shutdown + TeamDelete |
|
|
105
|
+
| **message > broadcast** | N배 절감 | broadcast = 팀원 수 × 비용 |
|
|
106
|
+
| **스폰 프롬프트 간결** | 초기 비용 감소 | CLAUDE.md/MCP/Skills 자동 로드됨 |
|
|
155
107
|
|
|
156
|
-
###
|
|
108
|
+
### Model Routing 패턴
|
|
157
109
|
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
|
|
110
|
+
```typescript
|
|
111
|
+
// Lead: Opus (복잡한 조율)
|
|
112
|
+
// Teammates: Sonnet (대부분 작업)
|
|
113
|
+
Task({ subagent_type: "researcher", model: "sonnet", team_name: "...", ... })
|
|
161
114
|
|
|
162
|
-
|
|
163
|
-
|
|
115
|
+
// 단순 탐색: Haiku
|
|
116
|
+
Task({ subagent_type: "explore", model: "haiku", ... })
|
|
164
117
|
```
|
|
165
118
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
| 터미널 | Split Panes |
|
|
169
|
-
|--------|-------------|
|
|
170
|
-
| tmux | ✅ |
|
|
171
|
-
| iTerm2 | ✅ |
|
|
172
|
-
| WezTerm | ❌ (요청 중) |
|
|
173
|
-
| Zellij | ❌ (요청 중) |
|
|
174
|
-
| VS Code | ❌ |
|
|
175
|
-
| Windows Terminal | ❌ |
|
|
176
|
-
| Ghostty | ❌ |
|
|
177
|
-
|
|
178
|
-
</teammate_modes>
|
|
119
|
+
</cost_optimization>
|
|
179
120
|
|
|
180
121
|
---
|
|
181
122
|
|
|
@@ -183,47 +124,27 @@ tmux -CC
|
|
|
183
124
|
|
|
184
125
|
## 활용 패턴
|
|
185
126
|
|
|
186
|
-
###
|
|
127
|
+
### Plan-First (권장)
|
|
187
128
|
|
|
188
129
|
```typescript
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
}
|
|
130
|
+
// Phase 1: 계획 (~10k 토큰, 저렴)
|
|
131
|
+
EnterPlanMode()
|
|
132
|
+
// 코드베이스 탐색 + 구현 계획 수립
|
|
133
|
+
// 사용자 승인
|
|
134
|
+
|
|
135
|
+
// Phase 2: 실행 (고비용, 고속)
|
|
136
|
+
TeamCreate({ team_name: "impl-team" })
|
|
137
|
+
Task({ ..., model: "sonnet" }) // 승인된 계획을 병렬 실행
|
|
197
138
|
```
|
|
198
139
|
|
|
199
|
-
###
|
|
140
|
+
### 팀 + 태스크 분배
|
|
200
141
|
|
|
201
142
|
```typescript
|
|
202
|
-
// 1. 팀 생성
|
|
203
143
|
TeamCreate({ team_name: "review-team", description: "코드 리뷰" })
|
|
204
|
-
|
|
205
|
-
// 2. 태스크 생성
|
|
206
144
|
TaskCreate({ subject: "보안 검토", description: "...", activeForm: "보안 검토 중" })
|
|
207
145
|
TaskCreate({ subject: "성능 검토", description: "...", activeForm: "성능 검토 중" })
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
Task({ subagent_type: "security-reviewer", team_name: "review-team", name: "security" })
|
|
211
|
-
Task({ subagent_type: "code-reviewer", team_name: "review-team", name: "performance" })
|
|
212
|
-
|
|
213
|
-
// 4. 완료 대기 후 종합
|
|
214
|
-
TaskList()
|
|
215
|
-
```
|
|
216
|
-
|
|
217
|
-
### 패턴 3: Plan-First (비용 최적화)
|
|
218
|
-
|
|
219
|
-
```typescript
|
|
220
|
-
// Phase 1: 계획 (저렴)
|
|
221
|
-
EnterPlanMode()
|
|
222
|
-
// 코드베이스 탐색 + 구현 계획 수립
|
|
223
|
-
|
|
224
|
-
// Phase 2: 실행 (고비용, 고속)
|
|
225
|
-
TeamCreate({ team_name: "impl-team" })
|
|
226
|
-
// 승인된 계획을 팀에 전달하여 병렬 실행
|
|
146
|
+
Task({ subagent_type: "security-reviewer", team_name: "review-team", name: "security", model: "sonnet" })
|
|
147
|
+
Task({ subagent_type: "code-reviewer", team_name: "review-team", name: "performance", model: "sonnet" })
|
|
227
148
|
```
|
|
228
149
|
|
|
229
150
|
</usage_patterns>
|
|
@@ -232,54 +153,51 @@ TeamCreate({ team_name: "impl-team" })
|
|
|
232
153
|
|
|
233
154
|
<send_message>
|
|
234
155
|
|
|
235
|
-
## SendMessage
|
|
156
|
+
## SendMessage 타입
|
|
236
157
|
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
|
240
|
-
|
|
241
|
-
| **
|
|
242
|
-
| **
|
|
243
|
-
| **shutdown_request** | 팀원에게 종료 요청 |
|
|
244
|
-
| **shutdown_response** | 종료 요청에 응답 |
|
|
245
|
-
| **plan_approval_response** | 계획 승인/거부 |
|
|
246
|
-
|
|
247
|
-
### 사용 예시
|
|
158
|
+
| 타입 | 용도 | 비용 |
|
|
159
|
+
|------|------|------|
|
|
160
|
+
| **message** | 특정 팀원에게 DM | 낮음 |
|
|
161
|
+
| **broadcast** | 모든 팀원에게 전송 | **높음** (N배) |
|
|
162
|
+
| **shutdown_request** | 종료 요청 | 낮음 |
|
|
163
|
+
| **shutdown_response** | 종료 응답 | 낮음 |
|
|
248
164
|
|
|
249
165
|
```json
|
|
250
|
-
// DM
|
|
251
|
-
{ "type": "message", "recipient": "researcher",
|
|
252
|
-
"content": "...", "summary": "Brief status" }
|
|
166
|
+
// DM (권장)
|
|
167
|
+
{ "type": "message", "recipient": "researcher", "content": "...", "summary": "..." }
|
|
253
168
|
|
|
254
|
-
//
|
|
255
|
-
{ "type": "broadcast", "content": "...", "summary": "Critical" }
|
|
256
|
-
|
|
257
|
-
// 종료 요청
|
|
169
|
+
// 종료
|
|
258
170
|
{ "type": "shutdown_request", "recipient": "researcher", "content": "완료" }
|
|
259
|
-
|
|
260
|
-
// 종료 응답
|
|
261
|
-
{ "type": "shutdown_response", "request_id": "abc-123", "approve": true }
|
|
262
171
|
```
|
|
263
172
|
|
|
264
|
-
**중요**: 텍스트 출력은 팀원에게 보이지 않음. 반드시 SendMessage 사용.
|
|
265
|
-
|
|
266
173
|
</send_message>
|
|
267
174
|
|
|
268
175
|
---
|
|
269
176
|
|
|
270
|
-
<
|
|
177
|
+
<teammate_modes>
|
|
178
|
+
|
|
179
|
+
## teammateMode 설정
|
|
180
|
+
|
|
181
|
+
| 모드 | 특징 | 권장 |
|
|
182
|
+
|------|------|------|
|
|
183
|
+
| **auto** | tmux면 split-pane, 아니면 in-process | 기본값 |
|
|
184
|
+
| **tmux** | 각 팀원 별도 pane | 3명+ 팀 |
|
|
185
|
+
| **in-process** | 단일 터미널, Shift+Up/Down 전환 | VS Code |
|
|
186
|
+
|
|
187
|
+
```json
|
|
188
|
+
// ~/.claude/settings.json
|
|
189
|
+
{ "teammateMode": "auto", "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
|
|
190
|
+
```
|
|
271
191
|
|
|
272
|
-
|
|
192
|
+
### 키보드 단축키 (in-process)
|
|
273
193
|
|
|
274
194
|
| 단축키 | 기능 |
|
|
275
195
|
|--------|------|
|
|
276
196
|
| `Shift+Up/Down` | 팀원 선택 |
|
|
277
|
-
| `
|
|
278
|
-
| `
|
|
279
|
-
| `Ctrl+T` | 태스크 목록 토글 |
|
|
280
|
-
| `Shift+Tab` | Delegate mode 전환 |
|
|
197
|
+
| `Shift+Tab` | Delegate mode |
|
|
198
|
+
| `Ctrl+T` | 태스크 목록 |
|
|
281
199
|
|
|
282
|
-
</
|
|
200
|
+
</teammate_modes>
|
|
283
201
|
|
|
284
202
|
---
|
|
285
203
|
|
|
@@ -287,25 +205,21 @@ TeamCreate({ team_name: "impl-team" })
|
|
|
287
205
|
|
|
288
206
|
## 베스트 프랙티스
|
|
289
207
|
|
|
290
|
-
| 원칙 |
|
|
208
|
+
| 원칙 | 방법 |
|
|
291
209
|
|------|------|
|
|
292
|
-
|
|
|
293
|
-
|
|
|
294
|
-
|
|
|
295
|
-
|
|
|
296
|
-
|
|
|
297
|
-
|
|
|
298
|
-
|
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
### Context 제공 예시
|
|
210
|
+
| **일단 Agent Teams** | 단순 작업 아니면 무조건 사용 |
|
|
211
|
+
| **Model Routing** | Lead: Opus, Teammates: Sonnet/Haiku |
|
|
212
|
+
| **Plan-First** | 큰 작업은 계획 승인 후 실행 |
|
|
213
|
+
| **풍부한 컨텍스트** | 팀원은 Lead 대화 미상속, 상세 프롬프트 필수 |
|
|
214
|
+
| **적정 태스크** | 팀원당 5-6개, 명확한 결과물 |
|
|
215
|
+
| **파일 충돌 방지** | 한 파일 = 한 팀원 |
|
|
216
|
+
| **즉시 정리** | 완료 시 shutdown → TeamDelete |
|
|
217
|
+
|
|
218
|
+
### Context 예시
|
|
303
219
|
|
|
304
220
|
```
|
|
305
221
|
❌ "인증 모듈 검토해"
|
|
306
|
-
✅ "src/auth/ 인증
|
|
307
|
-
토큰 핸들링, 세션 관리, 입력 검증에 집중해.
|
|
308
|
-
JWT 토큰을 httpOnly 쿠키에 저장함."
|
|
222
|
+
✅ "src/auth/ 인증 모듈 보안 검토. 토큰 핸들링/세션 관리/입력 검증 집중. JWT는 httpOnly 쿠키 저장."
|
|
309
223
|
```
|
|
310
224
|
|
|
311
225
|
</best_practices>
|
|
@@ -314,17 +228,15 @@ TeamCreate({ team_name: "impl-team" })
|
|
|
314
228
|
|
|
315
229
|
<common_mistakes>
|
|
316
230
|
|
|
317
|
-
## 흔한
|
|
231
|
+
## 흔한 실수
|
|
318
232
|
|
|
319
|
-
| 문제 |
|
|
320
|
-
|
|
321
|
-
| Lead가 직접 구현 |
|
|
322
|
-
| 팀원 안 보임 |
|
|
323
|
-
|
|
|
324
|
-
|
|
|
325
|
-
|
|
|
326
|
-
| 고아 tmux 세션 | 정리 안 됨 | `tmux ls` → `tmux kill-session` |
|
|
327
|
-
| 4+ 팀원 동시 spawn | tmux race condition | 2-3개씩 순차 spawn |
|
|
233
|
+
| 문제 | 해결책 |
|
|
234
|
+
|------|--------|
|
|
235
|
+
| Lead가 직접 구현 | `Shift+Tab` delegate mode |
|
|
236
|
+
| 팀원 안 보임 | `Shift+Down` 팀원 순환 |
|
|
237
|
+
| Lead 조기 종료 | "모든 팀원 완료까지 대기" 명시 |
|
|
238
|
+
| 고아 tmux 세션 | `tmux ls` → `tmux kill-session` |
|
|
239
|
+
| 4+ 동시 spawn | 2-3개씩 순차 spawn |
|
|
328
240
|
|
|
329
241
|
</common_mistakes>
|
|
330
242
|
|
|
@@ -332,75 +244,38 @@ TeamCreate({ team_name: "impl-team" })
|
|
|
332
244
|
|
|
333
245
|
<limitations>
|
|
334
246
|
|
|
335
|
-
## 제한사항
|
|
336
|
-
|
|
337
|
-
### 아키텍처 제한
|
|
247
|
+
## 제한사항
|
|
338
248
|
|
|
339
249
|
| 제한 | 설명 |
|
|
340
250
|
|------|------|
|
|
341
251
|
| 세션 재개 불가 | `/resume` 시 in-process 팀원 복원 안 됨 |
|
|
342
252
|
| 세션당 한 팀 | 중첩 팀 불가 |
|
|
343
253
|
| 리더십 고정 | 팀 생성 세션이 전체 수명 동안 리더 |
|
|
344
|
-
|
|
|
345
|
-
| 종료 지연 | 현재 작업 완료까지 대기 |
|
|
346
|
-
| Working Dir 공유 | 팀원에 다른 repo 할당 불가 |
|
|
347
|
-
|
|
348
|
-
### 알려진 버그
|
|
349
|
-
|
|
350
|
-
| 버그 | 영향 | 워크어라운드 |
|
|
351
|
-
|------|------|-------------|
|
|
352
|
-
| 컨텍스트 압축 시 팀 손실 | Lead가 팀 인식 상실 | 200K 토큰 전 작업 완료 |
|
|
353
|
-
| tmux split-pane race | `send-keys` corruption | 2-3개씩 순차 spawn |
|
|
354
|
-
| PermissionRequest hook 미작동 | 서브에이전트 권한 hook 무시 | 사전 승인 또는 수동 확인 |
|
|
355
|
-
| TaskUpdate 상태 비동기 | TeamDelete 후 상태 손실 | TeamDelete 후 재확인 |
|
|
254
|
+
| 컨텍스트 압축 | 200K 전 작업 완료 권장 |
|
|
356
255
|
|
|
357
256
|
</limitations>
|
|
358
257
|
|
|
359
258
|
---
|
|
360
259
|
|
|
361
|
-
<
|
|
362
|
-
|
|
363
|
-
## 비용 최적화
|
|
364
|
-
|
|
365
|
-
### 토큰 비용 구조
|
|
366
|
-
|
|
367
|
-
- 솔로 세션: ~200k tokens
|
|
368
|
-
- 3인 팀: ~800k tokens (4x)
|
|
369
|
-
- 각 팀원 별도 컨텍스트 윈도우
|
|
370
|
-
|
|
371
|
-
### 비용 절감 팁
|
|
372
|
-
|
|
373
|
-
| 전략 | 효과 |
|
|
374
|
-
|------|------|
|
|
375
|
-
| 모델 혼합 (Opus Lead + Sonnet Teammates) | ~40% 절감 |
|
|
376
|
-
| Plan-First 패턴 | 계획에서 실패 조기 발견 |
|
|
377
|
-
| 적절한 범위 지정 | 과도한 탐색 방지 |
|
|
378
|
-
| 단순 작업은 단독 세션 | 조율 오버헤드 제거 |
|
|
379
|
-
|
|
380
|
-
</cost_optimization>
|
|
381
|
-
|
|
382
|
-
---
|
|
383
|
-
|
|
384
|
-
<ideal_use_cases>
|
|
260
|
+
<use_cases>
|
|
385
261
|
|
|
386
|
-
##
|
|
262
|
+
## 활용 예시
|
|
387
263
|
|
|
388
|
-
|
|
|
389
|
-
|
|
390
|
-
|
|
|
391
|
-
|
|
|
392
|
-
|
|
|
393
|
-
|
|
|
394
|
-
| **QA
|
|
264
|
+
| 작업 | 팀 구성 |
|
|
265
|
+
|------|--------|
|
|
266
|
+
| **리서치** | researcher 2-3 + explore 1 |
|
|
267
|
+
| **코드 리뷰** | security + performance + test 검토자 |
|
|
268
|
+
| **기능 개발** | 프론트 + 백엔드 + 테스트 |
|
|
269
|
+
| **디버깅** | 각 가설별 팀원 |
|
|
270
|
+
| **QA** | pages + links + seo + a11y |
|
|
271
|
+
| **리팩토링** | 파일/모듈별 팀원 분배 |
|
|
395
272
|
|
|
396
|
-
###
|
|
273
|
+
### 예외 (직접 처리)
|
|
397
274
|
|
|
398
|
-
-
|
|
399
|
-
-
|
|
400
|
-
- 의존성 많은 작업
|
|
401
|
-
- 단순 단일 파일 수정
|
|
275
|
+
- 단일 파일 읽기/수정
|
|
276
|
+
- 단순 질문 응답
|
|
402
277
|
|
|
403
|
-
</
|
|
278
|
+
</use_cases>
|
|
404
279
|
|
|
405
280
|
---
|
|
406
281
|
|
|
@@ -408,11 +283,10 @@ TeamCreate({ team_name: "impl-team" })
|
|
|
408
283
|
|
|
409
284
|
## 참조
|
|
410
285
|
|
|
411
|
-
| 문서 |
|
|
412
|
-
|
|
286
|
+
| 문서 | URL |
|
|
287
|
+
|------|-----|
|
|
413
288
|
| 공식 문서 | https://code.claude.com/docs/en/agent-teams |
|
|
414
|
-
|
|
|
415
|
-
|
|
|
416
|
-
| agent-teams-setup 스킬 | `.claude/skills/agent-teams-setup/SKILL.md` |
|
|
289
|
+
| 비용 관리 | https://code.claude.com/docs/en/costs |
|
|
290
|
+
| 토큰 최적화 리서치 | .claude/research/08.Claude_Code_Agent_Teams_토큰_최적화_가이드.md |
|
|
417
291
|
|
|
418
292
|
</reference>
|