Process independent tasks concurrently with parallel subagents.
When to use
여러 작업? → 독립적? → 공유 상태 없음? → 병렬 디스패치!
Use:
- 3+ test files fail for different reasons
- Multiple subsystems fail independently
- Each issue can be understood without the context of the other issues
- Different types of tasks such as research + implementation + testing
Do not:
- Failures are related (fixing one may also resolve the others)
- Need to understand the overall system state
- Agents need to edit the same files
- Exploratory debugging (when you do not even know what the problem is)
Pattern
1. Identify independent domains
Group tasks by domain:
- Task A: Fix UI bug
- Task B: Optimize API performance
- Task C: Write tests
Verify that each domain is independent.
2. Write focused prompts
Good prompt:
- Specific scope: one clear problem
- Self-contained: includes all necessary context
- Output specified: what the agent should return
❌ "모든 테스트 고쳐" — 범위 너무 넓음
✅ "src/game/physics.test.ts의 3개 실패 테스트 수정" — 집중됨
❌ "레이스 컨디션 고쳐" — 맥락 없음
✅ "에러 메시지 + 테스트 이름 + 스택 트레이스 포함" — 맥락 충분
❌ "고쳐" — 출력 불명
✅ "근본 원인 요약 + 변경 사항 반환" — 출력 명시
3. Dispatch in Clawdbot
# sessions_spawn으로 병렬 서브에이전트 생성
서브에이전트 1: "physics.test.ts의 충돌 감지 버그 수정"
서브에이전트 2: "render pipeline 성능 최적화"
서브에이전트 3: "새 게임 레벨 에셋 생성" (MiniPC)
4. Integrate results
When agents return:
- Review each summary — understand the changes
- Check for conflicts — did they edit the same code?
- Full test — whether all fixes work together
- Spot check — subagents can also make mistakes
Common mistakes
| Mistake | Correction |
|---|---|
| Scope too broad | 1 agent = 1 domain |
| Lack of context | Include error messages and file paths |
| No constraints | Such as "Do not change production code" |
| Unclear output | Specify "root cause + summary of changes" |
Time-saving effect
Processing 3 issues sequentially = 3T time Processing 3 issues in parallel = ~1T time
The more independent domains there are, the greater the benefit.
Guardrails
- Concurrent agent limit of 5 — The maximum number of subagents running at once is 5. If exceeded, clean up completed agents, then dispatch new agents.
- Prevent shared resource conflicts — If multiple agents use the same file, DB table, or port at the same time, specify a mutex or file separation strategy. Include in the agent prompt
수정 금지 파일list. - Automatically clean up failed agents — When an agent fails (timeout, error), immediately clean up that agent's temporary files, lock files, and partial commits. After cleanup is complete, retry or report the error.
- Setting an overall pipeline timeout is required — Sets the maximum execution time for the entire parallel pipeline in addition to individual agent timeouts. Default 600 seconds (individual agent 300 seconds × 2 stages). If the timeout is exceeded, all running agents are forcibly terminated and reported to the Master.