[opencode 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기] 11/12화: opencode 멀티 에이전트 시스템 5가지 협업 패턴 2026
시리즈 안내
이 글은 「opencode 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기」 11일차입니다. 시즌 1에서 opencode의 서브에이전트 개념을 처음 접했던 것, 기억하시나요? 오늘은 그 에이전트들이 동시에 일하고, 서로 기억을 공유하는 opencode 멀티 에이전트 시스템을 직접 구축합니다.
어제 10일차에서 MCP 서버를 연동해 사내 시스템의 데이터를 에이전트 툴로 노출하는 법을 다뤘습니다. 이제 그 툴들을 동시에 활용하는 여러 에이전트가 병렬로 움직이면서도 하나의 팀처럼 협업하는 구조를 만들어 봅니다.
오늘의 핵심 3가지
- 병렬 백그라운드 실행 — 서브에이전트를 동시에 여러 개 띄워 작업 시간을 단축하는 구조
- Hive Mind 패턴 — 에이전트 간 공유 영속 메모리로 중복 작업을 제거하고 학습을 누적하는 방법
- Fallback Chain — 모델 장애·세션 실패 시 자동 복구되는 복원력 있는 시스템 설계
왜 멀티 에이전트 시스템인가 — 단일 에이전트의 한계
6일차에서 서브에이전트 오케스트레이션의 기초를 잡았습니다. Reviewer, Tester, Refactor, SecurityAuditor 네 역할을 나눠 전문가 팀을 구성했죠. 하지만 그때의 구조에는 근본적인 제약이 있었습니다. 모든 서브에이전트가 순차적으로 실행되었다는 점입니다.
코드 리뷰를 하는 동안 테스트 작성은 대기하고, 테스트가 끝나야 보안 감사가 시작됩니다. 파일이 50개인 PR이라면 리뷰만 3~5분, 전체 파이프라인은 15분 이상 걸릴 수 있습니다. 실무에서 이 대기 시간은 개발자의 컨텍스트 스위칭 비용으로 직결됩니다.
오늘 구축할 opencode 멀티 에이전트 시스템은 이 문제를 다섯 가지 패턴으로 해결합니다.
패턴 1 — 병렬 백그라운드 실행
opencode의 백그라운드 세션 메커니즘
opencode는 서브에이전트를 호출할 때 기본적으로 포그라운드 모드로 실행합니다. Primary가 서브에이전트에게 작업을 위임하면 결과가 돌아올 때까지 Primary는 블로킹됩니다. 하지만 에이전트 정의에서 background: true를 설정하면 해당 서브에이전트는 별도의 자식 세션에서 비동기로 실행됩니다.
핵심 원리는 간단합니다. Primary가 “이 작업을 해줘”라고 위임하면, 백그라운드 서브에이전트는 독립된 세션을 생성하고 즉시 제어권을 Primary에게 돌려줍니다. Primary는 다음 서브에이전트에게 또 다른 작업을 위임할 수 있습니다. 모든 서브에이전트의 결과는 완료 시점에 Primary에게 비동기로 보고됩니다.
실제 설정을 보겠습니다.
// .opencode/agents/parallel-reviewer.md
---
name: ParallelReviewer
description: "코드 변경 사항을 병렬로 리뷰합니다. 파일 패턴별로 전문 분야를 나눠 동시 분석합니다."
model: anthropic/claude-sonnet-4-6
background: true
tools:
allow:
- Read
- Grep
- Glob
deny:
- Edit
- Write
- Bash
---
당신은 코드 리뷰 전문 에이전트입니다.
## 리뷰 절차
1. 위임받은 파일 목록을 순회하며 각 파일의 변경 사항을 분석합니다.
2. 다음 체크리스트를 적용합니다:
- 타입 안전성: any 사용, 타입 단언 남용, 누락된 제네릭
- 에러 처리: catch 블록의 구체성, 에러 전파 경로
- 성능: 불필요한 리렌더링, N+1 쿼리 패턴, 메모이제이션 누락
3. 발견 사항을 심각도(critical/warning/info)로 분류합니다.
4. 결과를 .opencode/shared/review-results/ 디렉토리에 마크다운으로 저장합니다.
## 출력 형식
파일명: {파일경로}
심각도: {critical|warning|info}
위치: {라인 번호}
내용: {구체적 설명}
제안: {수정 방향}
// .opencode/agents/parallel-tester.md
---
name: ParallelTester
description: "변경된 코드에 대한 테스트를 병렬로 작성합니다. 기존 테스트 패턴을 분석해 일관된 스타일을 유지합니다."
model: anthropic/claude-sonnet-4-6
background: true
tools:
allow:
- Read
- Grep
- Glob
- Write
- Edit
deny:
- Bash
---
당신은 테스트 작성 전문 에이전트입니다.
## 작업 절차
1. 위임받은 소스 파일의 공개 인터페이스를 분석합니다.
2. 같은 디렉토리 또는 __tests__/ 의 기존 테스트 파일을 읽어 패턴을 파악합니다.
3. 누락된 테스트 케이스를 작성합니다:
- 정상 경로 (happy path)
- 경계값 (boundary)
- 에러 경로 (error path)
4. 결과를 .opencode/shared/test-results/ 에 요약합니다.
## 제약
- 기존 테스트를 삭제하거나 수정하지 않습니다.
- 새 테스트 파일만 생성합니다.
- 테스트 프레임워크는 프로젝트의 기존 설정을 따릅니다.
// .opencode/agents/parallel-security.md
---
name: ParallelSecurity
description: "보안 취약점을 병렬로 스캔합니다. OWASP Top 10 기준으로 코드를 정적 분석합니다."
model: anthropic/claude-sonnet-4-6
background: true
tools:
allow:
- Read
- Grep
- Glob
deny:
- Edit
- Write
- Bash
---
당신은 보안 감사 전문 에이전트입니다.
## 분석 기준
OWASP Top 10 (2025) 기반:
1. Injection (SQL, NoSQL, OS command, LDAP)
2. Broken Authentication
3. Sensitive Data Exposure
4. XML External Entities (XXE)
5. Broken Access Control
6. Security Misconfiguration
7. Cross-Site Scripting (XSS)
8. Insecure Deserialization
9. Using Components with Known Vulnerabilities
10. Insufficient Logging & Monitoring
## 출력
발견된 취약점을 .opencode/shared/security-results/ 에 기록합니다.
심각도는 CVSS v3 기준 (Critical 9.0+, High 7.0-8.9, Medium 4.0-6.9, Low 0.1-3.9) 으로 분류합니다.
병렬 실행을 오케스트레이션하는 Primary 설정
세 서브에이전트를 동시에 띄우려면 Primary 에이전트가 오케스트레이터 역할을 해야 합니다. Primary의 시스템 프롬프트에 병렬 위임 전략을 명시합니다.
// .opencode/agents/orchestrator.md
---
name: Orchestrator
description: "PR 리뷰 요청을 받으면 ParallelReviewer, ParallelTester, ParallelSecurity를 동시에 실행하고 결과를 통합합니다."
model: anthropic/claude-opus-4-7
agent: primary
tools:
allow:
- Read
- Write
- Edit
- Glob
- Grep
- Bash
---
당신은 코드 리뷰 오케스트레이터입니다.
## 병렬 위임 전략
PR 리뷰 요청을 받으면 다음 순서로 진행합니다:
### 1단계: 변경 파일 수집
- git diff --name-only 로 변경된 파일 목록을 확보합니다.
- 파일을 카테고리별로 분류합니다:
- src/**/*.ts → 소스 코드
- test/**/*.ts → 테스트 코드
- *.json, *.yml → 설정 파일
### 2단계: 병렬 위임
다음 세 에이전트를 **동시에** 호출합니다:
- @ParallelReviewer: 소스 코드 파일 리뷰
- @ParallelTester: 소스 코드에 대한 테스트 작성
- @ParallelSecurity: 전체 변경 파일 보안 스캔
각 에이전트에게 담당 파일 목록을 명시적으로 전달합니다.
### 3단계: 결과 통합
세 에이전트의 결과가 모두 .opencode/shared/ 에 기록되면:
1. 각 결과 파일을 읽습니다.
2. 심각도별로 통합 정렬합니다.
3. 최종 리뷰 리포트를 생성합니다.
### 4단계: 보고
통합 리포트를 사용자에게 제시하고, critical 항목이 있으면 즉시 수정을 제안합니다.
## 공유 디렉토리 구조
```
.opencode/shared/
├── review-results/ ← ParallelReviewer 출력
├── test-results/ ← ParallelTester 출력
├── security-results/ ← ParallelSecurity 출력
└── final-report.md ← Orchestrator 통합 결과
```
실행 흐름 — 시간 비교
순차 실행과 병렬 실행의 차이를 구체적으로 보겠습니다. 50개 파일이 변경된 PR을 기준으로 합니다.
순차 실행 (6일차 구조)
- Reviewer: 3분 → Tester: 4분 → Security: 2분 = 총 9분
병렬 실행 (오늘 구조)
- Reviewer, Tester, Security 동시 시작 → 가장 오래 걸리는 Tester 기준 = 총 4분
- 시간 절감: 약 55%
물론 병렬 실행이라고 해서 무조건 빠른 것은 아닙니다. 에이전트가 동시에 같은 파일을 읽거나 쓰면 충돌이 발생할 수 있고, API 요금제의 동시 세션 제한에 걸릴 수도 있습니다. 이 문제는 뒤에서 다룰 공유 메모리 패턴과 fallback chain으로 해결합니다.
패턴 2 — 서브에이전트 자식 세션 탐색
세션의 계층 구조 이해하기
opencode에서 에이전트가 실행되면 세션(session)이 생성됩니다. Primary 에이전트는 루트 세션을 갖고, 서브에이전트를 호출할 때마다 자식 세션이 파생됩니다. 이 세션 트리를 이해하는 것이 멀티 에이전트 디버깅의 핵심입니다.
루트 세션 (Orchestrator)
├── 자식 세션 1 (ParallelReviewer) — background
│ ├── 컨텍스트: 위임받은 파일 목록 + 리뷰 지침
│ └── 출력: .opencode/shared/review-results/
├── 자식 세션 2 (ParallelTester) — background
│ ├── 컨텍스트: 소스 파일 + 기존 테스트 패턴
│ └── 출력: .opencode/shared/test-results/
└── 자식 세션 3 (ParallelSecurity) — background
├── 컨텍스트: 전체 변경 파일 + OWASP 기준
└── 출력: .opencode/shared/security-results/
각 자식 세션은 독립된 컨텍스트 윈도우를 갖습니다. 이것이 병렬 실행을 가능하게 하는 근본 이유입니다. 하지만 동시에, 세션 간 정보 공유가 자동으로 이뤄지지 않는다는 뜻이기도 합니다. Reviewer가 발견한 버그를 Tester가 모른다면 해당 버그에 대한 테스트가 누락될 수 있습니다.
자식 세션의 컨텍스트 전달 전략
서브에이전트에게 작업을 위임할 때, Primary는 두 가지 방법으로 컨텍스트를 전달할 수 있습니다.
방법 1 — 인라인 컨텍스트 (소규모 작업)
위임 메시지 안에 필요한 정보를 직접 포함합니다. 파일이 5개 미만이고 컨텍스트가 간단할 때 적합합니다.
@ParallelReviewer 다음 3개 파일을 리뷰해주세요:
- src/auth/login.ts (인증 로직 변경)
- src/auth/token.ts (토큰 갱신 추가)
- src/middleware/cors.ts (CORS 설정 수정)
이번 PR의 목적: OAuth2 PKCE 플로우 도입
주의사항: 기존 세션 기반 인증과의 하위 호환성 유지 필요
방법 2 — 파일 기반 컨텍스트 (대규모 작업)
변경 파일이 많거나 컨텍스트가 복잡하면, 작업 명세를 파일로 작성하고 경로만 전달합니다. 컨텍스트 윈도우를 효율적으로 사용할 수 있습니다.
// .opencode/shared/tasks/review-task-001.md (Orchestrator가 자동 생성)
# 리뷰 작업 명세
## PR 정보
- PR #142: OAuth2 PKCE 플로우 도입
- 브랜치: feature/oauth2-pkce
- 변경 파일: 23개
## 담당 파일 (소스 코드)
| 파일 | 변경 유형 | 라인 수 |
|------|----------|--------|
| src/auth/login.ts | Modified | +85 -12 |
| src/auth/token.ts | Modified | +142 -3 |
| src/auth/pkce.ts | Added | +203 |
| ... (20개 더) |
## 리뷰 우선순위
1. 새로 추가된 pkce.ts — 핵심 로직
2. 기존 파일의 변경 부분 — 하위 호환성
3. 설정 파일 — 환경별 차이
## 참조
- 기존 인증 아키텍처: docs/auth-architecture.md
- PKCE 스펙: RFC 7636
// Orchestrator의 위임 메시지
@ParallelReviewer .opencode/shared/tasks/review-task-001.md 의 명세대로 리뷰를 진행해주세요.
파일 기반 컨텍스트는 특히 10일차에서 다룬 MCP 연동 환경에서 강력합니다. 사내 Jira 티켓의 요구사항, Confluence 문서의 아키텍처 설명 등을 MCP 툴로 가져와 작업 명세 파일에 통합할 수 있기 때문입니다.
패턴 3 — 공유 영속 메모리: Hive Mind 패턴
왜 공유 메모리가 필요한가
병렬로 실행되는 에이전트들은 각자의 세션 안에서 독립적으로 사고합니다. 문제는 이 독립성이 정보 사일로를 만든다는 것입니다.
- Reviewer가 “이 함수는 null을 반환할 수 있다”고 발견했지만, Tester는 이를 모르고 null 케이스 테스트를 빠뜨림
- Security가 “이 엔드포인트에 rate limiting이 없다”고 경고했지만, Reviewer는 같은 파일에서 성능 개선만 코멘트함
- 이전 PR에서 반복 지적된 패턴을 매번 새로 발견하며 같은 코멘트를 반복함
Hive Mind 패턴은 에이전트들이 공유 영속 메모리를 통해 서로의 발견을 실시간으로 참조하고, 과거의 학습을 누적하는 구조입니다. Anthropic의 에이전트 설계 가이드에서도 에이전트 간 상태 공유의 중요성을 강조합니다.
공유 메모리 아키텍처
opencode 환경에서 에이전트 간 공유 메모리를 구현하는 가장 실용적인 방법은 파일 시스템 기반 공유 디렉토리입니다. 데이터베이스나 메시지 큐 같은 외부 인프라 없이, 프로젝트 디렉토리 안에서 모든 것이 해결됩니다.
.opencode/shared/
├── memory/ # 영속 메모리 (세션 간 유지)
│ ├── patterns.md # 반복 발견 패턴 누적
│ ├── decisions.md # 아키텍처 결정 기록
│ ├── team-conventions.md # 팀 코딩 컨벤션
│ └── known-issues.md # 알려진 이슈 목록
├── session/ # 세션 메모리 (현재 작업용)
│ ├── current-task.md # 현재 작업 명세
│ ├── findings/ # 각 에이전트의 실시간 발견
│ │ ├── reviewer.md
│ │ ├── tester.md
│ │ └── security.md
│ └── conflicts.md # 에이전트 간 충돌 기록
└── artifacts/ # 산출물 (리포트, 생성 코드 등)
├── review-results/
├── test-results/
└── security-results/
Hive Mind 패턴 구현 — 완전한 설정
각 에이전트의 시스템 프롬프트에 공유 메모리 접근 규칙을 포함합니다. 아래는 이 패턴을 적용한 전체 프로젝트 설정입니다.
// opencode.json
{
"default_agent": "Orchestrator",
"agent": {
"Orchestrator": ".opencode/agents/orchestrator.md"
},
"model": {
"primary": "anthropic/claude-opus-4-7",
"subagent": "anthropic/claude-sonnet-4-6"
},
"permission": {
"allow": [
"Read(**)",
"Glob(**)",
"Grep(**)"
],
"ask": [
"Write(.opencode/shared/**)",
"Edit(.opencode/shared/**)"
],
"deny": [
"Bash(rm *)",
"Bash(git push*)"
]
}
}
// .opencode/shared/memory/patterns.md
# 반복 발견 패턴 (에이전트 공유 메모리)
이 파일은 리뷰·테스트·보안 스캔에서 반복적으로 발견되는 패턴을 기록합니다.
모든 에이전트는 작업 시작 시 이 파일을 읽고, 새로운 패턴 발견 시 추가합니다.
## 코드 패턴
### P-001: async 함수의 에러 미처리 (2026-08-10 발견)
- 빈도: 12회 / 최근 5 PR
- 위치: src/services/**/*.ts
- 설명: async 함수에서 try-catch 없이 await를 사용하는 패턴.
Promise rejection이 상위로 전파되지 않아 런타임 크래시 발생.
- 권장 수정: 각 서비스 함수에 try-catch + 구체적 에러 타입 throw.
- 심각도: warning
### P-002: SQL 파라미터 문자열 연결 (2026-08-12 발견)
- 빈도: 3회 / 최근 3 PR
- 위치: src/repositories/**/*.ts
- 설명: parameterized query 대신 문자열 템플릿으로 SQL 조립.
- 권장 수정: prepared statement 또는 ORM query builder 사용.
- 심각도: critical
### P-003: 환경별 설정 하드코딩 (2026-08-15 발견)
- 빈도: 7회 / 최근 4 PR
- 위치: src/config/**/*.ts, src/**/*.constants.ts
- 설명: 개발/스테이징/프로덕션 URL·포트를 if-else로 분기.
- 권장 수정: .env 파일 + config 모듈 중앙 관리.
- 심각도: info
핵심은 각 에이전트가 작업 시작 시 공유 메모리를 읽고, 작업 완료 시 새 발견을 기록하는 루프입니다. 에이전트의 시스템 프롬프트에 이 행동 규칙을 명시합니다.
// .opencode/prompts/hive-mind-protocol.md
# Hive Mind 프로토콜 — 모든 에이전트 공통
## 작업 시작 시
1. .opencode/shared/memory/patterns.md 를 읽습니다.
2. .opencode/shared/memory/known-issues.md 를 읽습니다.
3. .opencode/shared/session/findings/ 에 이미 다른 에이전트의 결과가 있으면 읽습니다.
## 작업 중
- 이미 알려진 패턴(P-xxx)과 동일한 발견은 패턴 번호만 참조합니다.
예: "P-001 패턴 재발견: src/services/payment.ts:42"
- 새로운 패턴 발견 시 .opencode/shared/session/findings/{자신의이름}.md 에 즉시 기록합니다.
## 작업 완료 시
- 새 패턴이 3회 이상 반복 발견되었으면 .opencode/shared/memory/patterns.md 에
새 항목(P-xxx)으로 승격을 제안합니다 (Orchestrator가 최종 결정).
- .opencode/shared/session/findings/{자신의이름}.md 에 최종 결과를 기록합니다.
## 충돌 해결
- 다른 에이전트의 발견과 자신의 발견이 모순되면:
1. .opencode/shared/session/conflicts.md 에 양쪽 내용을 기록합니다.
2. Orchestrator에게 판단을 위임합니다.
3. 스스로 해결하려 하지 않습니다.
각 서브에이전트의 시스템 프롬프트 상단에 다음 한 줄을 추가합니다.
{file:.opencode/prompts/hive-mind-protocol.md}이것으로 모든 에이전트가 동일한 공유 메모리 프로토콜을 따르게 됩니다. 7일차에서 다룬 {file:} 외부화 패턴이 여기서 빛을 발합니다.
영속 메모리 vs 세션 메모리
공유 메모리는 두 계층으로 나뉩니다. 이 구분을 명확히 해야 메모리 비대화를 막을 수 있습니다.
영속 메모리 (.opencode/shared/memory/)
- 세션이 끝나도 유지됩니다. Git으로 버전 관리합니다.
- 반복 패턴, 아키텍처 결정, 팀 컨벤션 등 장기 학습 결과를 저장합니다.
- 새 항목 추가는 Orchestrator의 승인을 거칩니다 (3회 이상 반복 확인).
- 월 1회 정리(prune)를 권장합니다. 6개월간 재발견되지 않은 패턴은 아카이브합니다.
세션 메모리 (.opencode/shared/session/)
- 현재 작업(PR 리뷰, 기능 구현 등) 동안만 유효합니다.
- 에이전트들의 실시간 발견, 중간 결과, 충돌 기록을 저장합니다.
- 작업 완료 후 Orchestrator가 정리합니다. 가치 있는 내용만 영속 메모리로 승격합니다.
.gitignore에 추가해도 무방합니다 (팀 정책에 따라 결정).
패턴 4 — 카테고리 기반 위임 vs 직접 호출
자동 위임의 메커니즘
6일차에서 description 기반 자동 위임을 다뤘습니다. Primary가 작업의 성격을 판단해서 description이 가장 잘 맞는 서브에이전트에게 자동으로 위임하는 방식이었죠. 멀티 에이전트 시스템에서는 이 자동 위임을 카테고리 단위로 확장합니다.
// .opencode/agents/category-router.md
---
name: CategoryRouter
description: "작업을 카테고리별로 분류해 적절한 전문 에이전트에게 라우팅합니다."
model: anthropic/claude-sonnet-4-6
agent: primary
---
## 카테고리 라우팅 테이블
| 카테고리 | 키워드/패턴 | 담당 에이전트 | 우선순위 |
|---------|-----------|-------------|---------|
| 코드 리뷰 | review, PR, diff, 변경 | @ParallelReviewer | 1 |
| 테스트 | test, 검증, coverage, 단위 | @ParallelTester | 2 |
| 보안 | security, 취약점, OWASP, CVE | @ParallelSecurity | 1 |
| 문서 | docs, README, API spec | @DocWriter | 3 |
| 리팩토링 | refactor, 개선, 정리, 중복 | @Refactorer | 2 |
| 인프라 | deploy, CI/CD, docker, k8s | @InfraAgent | 2 |
## 라우팅 규칙
1. **단일 카테고리**: 해당 에이전트에게 직접 위임합니다.
2. **복수 카테고리**: 우선순위 1인 카테고리의 에이전트를 먼저, 나머지를 병렬로 실행합니다.
3. **미분류**: 사용자에게 "이 작업을 어떤 관점으로 처리할까요?"라고 질문합니다.
4. **복합 작업 (예: "이 PR을 리뷰하고 테스트도 작성해줘")**:
- 리뷰와 테스트를 병렬로 실행합니다.
- 리뷰 결과를 세션 메모리에 기록 → 테스터가 참조합니다.
@멘션 직접 호출 — 언제 쓰는가
자동 위임이 편리하지만, 명시적 제어가 필요한 상황이 있습니다.
- 특정 에이전트에게만 맡기고 싶을 때: “보안 스캔은 건너뛰고 리뷰만 해줘” →
@ParallelReviewer - 에이전트에게 추가 지시를 줄 때: “@ParallelTester 이번에는 통합 테스트 위주로 작성해줘”
- 자동 위임이 잘못 분류했을 때: 성능 최적화 요청을 보안 에이전트가 받은 경우, 직접 “@Refactorer 성능 최적화를 진행해줘”
실무에서의 경험칙: 일상적인 작업은 카테고리 자동 위임, 예외적인 작업은 @멘션 직접 호출. 이 비율이 대략 80:20일 때 가장 효율적입니다.
위임 깊이 제한
서브에이전트가 또 다른 서브에이전트를 호출하는 재귀 위임은 가능하지만 위험합니다. 무한 루프에 빠지거나 컨텍스트가 급격히 소비될 수 있습니다.
// Orchestrator 시스템 프롬프트에 추가
## 위임 깊이 제한
- 최대 위임 깊이: 2 (Primary → Subagent → Sub-subagent)
- 깊이 2의 서브에이전트는 다른 에이전트를 호출할 수 없습니다.
- 깊이 2에서 추가 전문가가 필요하면 결과를 Primary에게 보고하고,
Primary가 새로운 위임을 시작합니다.
패턴 5 — Fallback Chain으로 복원력 있는 시스템 만들기
무엇이 실패하는가
멀티 에이전트 시스템에서 발생할 수 있는 실패 유형은 다양합니다.
- 모델 실패: API rate limit, 모델 다운타임, 컨텍스트 윈도우 초과
- 세션 실패: 서브에이전트 세션 타임아웃, 메모리 부족
- 툴 실패: MCP 서버 연결 끊김, 파일 시스템 권한 오류
- 논리 실패: 에이전트가 무한 루프에 빠지거나 잘못된 결과를 반환
각 실패 유형에 대해 fallback 전략을 미리 정의해 두면, 시스템이 한 에이전트의 장애에도 전체가 멈추지 않습니다.
Fallback Chain 설계
// .opencode/agents/resilient-orchestrator.md
---
name: ResilientOrchestrator
description: "장애 복원력이 내장된 오케스트레이터. 서브에이전트 실패 시 자동으로 대체 전략을 실행합니다."
model: anthropic/claude-opus-4-7
agent: primary
tools:
allow:
- Read
- Write
- Edit
- Glob
- Grep
- Bash
---
# Resilient Orchestrator
## Fallback Chain 정의
### 모델 Fallback
각 서브에이전트의 기본 모델이 실패하면 순차적으로 대체 모델을 시도합니다.
| 역할 | 1차 모델 | 2차 (fallback) | 3차 (최후) |
|------|---------|---------------|-----------|
| Reviewer | anthropic/claude-sonnet-4-6 | openai/gpt-4.1 | anthropic/claude-haiku-4-5 |
| Tester | anthropic/claude-sonnet-4-6 | openai/gpt-4.1 | anthropic/claude-haiku-4-5 |
| Security | anthropic/claude-sonnet-4-6 | anthropic/claude-opus-4-7 | openai/gpt-4.1 |
보안 스캔은 품질이 중요하므로 2차 fallback에 Opus를 배치합니다.
### 세션 Fallback
서브에이전트 세션이 타임아웃(5분 무응답)되면:
1. 해당 세션을 종료합니다.
2. 같은 에이전트를 새 세션으로 재시작합니다.
3. .opencode/shared/session/findings/ 에 이전 세션의 부분 결과가 있으면 이어서 작업합니다.
4. 재시작도 실패하면 해당 작업을 '수동 검토 필요'로 표시하고 나머지 작업을 계속합니다.
### 툴 Fallback
MCP 서버 연결이 끊기면:
1. 30초 후 재연결을 시도합니다 (최대 3회).
2. 실패하면 MCP 의존 작업을 건너뛰고 로컬 파일 기반으로 전환합니다.
3. 최종 리포트에 "MCP 연결 실패로 {기능명} 미검증"을 명시합니다.
### 논리 Fallback
서브에이전트가 같은 파일을 3회 이상 반복 읽거나, 10회 이상 같은 패턴의 출력을 생성하면:
1. 해당 세션을 '무한 루프 의심'으로 태깅합니다.
2. 세션을 종료하고 다른 모델로 재시작합니다.
3. 2차 모델도 같은 증상이면 해당 작업을 건너뜁니다.
## 장애 보고
모든 fallback 발동은 .opencode/shared/session/fallback-log.md 에 기록합니다:
```
## {타임스탬프}
- 에이전트: {이름}
- 실패 유형: {model|session|tool|logic}
- 1차 시도: {결과}
- Fallback: {대체 전략}
- 최종 결과: {성공|부분성공|실패}
```
사용자에게는 최종 리포트에서 fallback 발동 횟수와 영향 범위를 한 줄로 요약합니다.
Fallback 동작의 실제 시나리오
구체적인 예를 들어 보겠습니다. 50개 파일 PR을 병렬 리뷰하는 도중 Sonnet 4.6의 rate limit에 걸리는 상황입니다.
1. Orchestrator: 3개 서브에이전트 병렬 실행
2. ParallelReviewer: 15개 파일 리뷰 완료, 16번째에서 rate limit 에러
3. Fallback 발동:
- 1차: 30초 대기 후 재시도 → 실패 (rate limit 지속)
- 2차: 모델을 gpt-4.1 로 전환
- gpt-4.1 로 나머지 8개 파일 리뷰 완료
4. ParallelTester: 정상 완료 (rate limit 영향 없음)
5. ParallelSecurity: 정상 완료
6. Orchestrator: 결과 통합
- Reviewer 결과: Sonnet 15건 + GPT 8건 = 23건 (모델 혼합 표시)
- 최종 리포트에 "Reviewer가 16번째 파일에서 모델 전환 (Sonnet → GPT)" 명시
이런 복원력은 프로덕션 환경에서의 안정성에 직결됩니다. 한 모델의 장애가 전체 리뷰 파이프라인을 멈추지 않습니다.
opencode 멀티 에이전트 시스템 — 통합 구성 예시
다섯 가지 패턴을 모두 결합한 프로젝트 구조를 정리합니다. 이 구조를 그대로 본인의 프로젝트에 복사해서 사용할 수 있습니다.
project-root/
├── opencode.json # 진입점 설정
├── .opencode/
│ ├── agents/
│ │ ├── orchestrator.md # Primary — 오케스트레이터
│ │ ├── parallel-reviewer.md # Subagent — 코드 리뷰 (background)
│ │ ├── parallel-tester.md # Subagent — 테스트 작성 (background)
│ │ ├── parallel-security.md # Subagent — 보안 스캔 (background)
│ │ ├── doc-writer.md # Subagent — 문서 작성
│ │ └── refactorer.md # Subagent — 리팩토링
│ ├── prompts/
│ │ ├── hive-mind-protocol.md # 공유 메모리 프로토콜 (모든 에이전트 공통)
│ │ ├── review-checklist.md # 리뷰 체크리스트 (Reviewer 전용)
│ │ ├── test-strategy.md # 테스트 전략 (Tester 전용)
│ │ └── security-baseline.md # 보안 기준 (Security 전용)
│ ├── commands/
│ │ ├── review.md # /review — PR 병렬 리뷰 실행
│ │ ├── scan.md # /scan — 보안 스캔 단독 실행
│ │ └── report.md # /report — 공유 메모리 현황 리포트
│ └── shared/
│ ├── memory/ # 영속 메모리 (Git 관리)
│ │ ├── patterns.md
│ │ ├── decisions.md
│ │ ├── team-conventions.md
│ │ └── known-issues.md
│ ├── session/ # 세션 메모리 (작업 중 임시)
│ │ ├── current-task.md
│ │ ├── findings/
│ │ ├── conflicts.md
│ │ └── fallback-log.md
│ ├── tasks/ # 작업 명세 (Orchestrator 생성)
│ └── artifacts/ # 산출물
│ ├── review-results/
│ ├── test-results/
│ └── security-results/
└── AGENTS.md # 프로젝트 에이전트 가이드
/review 슬래시 커맨드 — 병렬 리뷰 트리거
8일차에서 배운 슬래시 커맨드로 이 전체 파이프라인을 한 번에 실행합니다.
// .opencode/commands/review.md
---
description: "PR 변경 사항을 병렬로 리뷰합니다 (코드 리뷰 + 테스트 + 보안 스캔)"
arguments:
branch:
description: "리뷰할 브랜치 (기본: 현재 브랜치)"
required: false
base:
description: "비교 대상 브랜치 (기본: main)"
required: false
skip:
description: "건너뛸 에이전트 (comma-separated: reviewer,tester,security)"
required: false
---
다음 절차로 PR 병렬 리뷰를 실행합니다.
1. `git diff --name-only {{ base | default: "main" }}...{{ branch | default: "HEAD" }}` 로 변경 파일을 수집합니다.
2. .opencode/shared/session/ 디렉토리를 초기화합니다.
3. .opencode/shared/memory/patterns.md 를 읽어 기존 패턴을 로드합니다.
{{ if skip }}
건너뛸 에이전트: {{ skip }}
해당 에이전트를 제외하고 나머지만 병렬 실행합니다.
{{ else }}
4. 다음 에이전트를 **병렬로** 실행합니다:
- @ParallelReviewer: 소스 코드 리뷰
- @ParallelTester: 테스트 작성
- @ParallelSecurity: 보안 스캔
{{ endif }}
5. 모든 에이전트의 결과를 통합합니다.
6. .opencode/shared/artifacts/ 에 최종 리포트를 저장합니다.
7. critical 항목이 있으면 즉시 수정을 제안합니다.
사용법은 간단합니다.
# 전체 병렬 리뷰
/review
# 특정 브랜치의 변경만 리뷰
/review branch=feature/new-auth base=develop
# 보안 스캔을 건너뛰고 리뷰+테스트만
/review skip=security
AGENTS.md — 멀티 에이전트 팀 가이드
7일차에서 컨텍스트 엔지니어링의 핵심으로 AGENTS.md를 다뤘습니다. 멀티 에이전트 시스템에서는 이 파일이 팀 운영 매뉴얼 역할을 합니다.
// AGENTS.md
# 에이전트 팀 운영 가이드
## 팀 구성
| 이름 | 역할 | 모델 | 실행 모드 |
|------|------|------|----------|
| Orchestrator | 작업 분배·결과 통합 | Opus | foreground (Primary) |
| ParallelReviewer | 코드 리뷰 | Sonnet | background |
| ParallelTester | 테스트 작성 | Sonnet | background |
| ParallelSecurity | 보안 스캔 | Sonnet | background |
| DocWriter | 문서 작성 | Sonnet | foreground |
| Refactorer | 리팩토링 | Sonnet | foreground |
## 협업 규칙
### 공유 메모리
- 모든 에이전트는 Hive Mind 프로토콜 (.opencode/prompts/hive-mind-protocol.md)을 따릅니다.
- 영속 메모리 변경은 Orchestrator의 승인이 필요합니다.
- 세션 메모리는 자유롭게 기록하되, 작업 완료 시 Orchestrator가 정리합니다.
### 파일 쓰기 충돌 방지
- 같은 파일을 여러 에이전트가 동시에 수정하지 않습니다.
- 각 에이전트는 자신의 전용 출력 디렉토리만 사용합니다:
- Reviewer → .opencode/shared/artifacts/review-results/
- Tester → .opencode/shared/artifacts/test-results/
- Security → .opencode/shared/artifacts/security-results/
- 소스 코드 수정은 Refactorer만 허용됩니다 (다른 에이전트는 read-only).
### Fallback 정책
- 모델 실패 시 fallback chain을 따릅니다 (Orchestrator 시스템 프롬프트 참조).
- 3회 연속 fallback 발동 시 해당 작업을 '수동 검토'로 에스컬레이션합니다.
## 커맨드
- `/review` — 병렬 PR 리뷰 (전체 파이프라인)
- `/review skip=security` — 보안 스캔 제외
- `/scan` — 보안 스캔 단독
- `/report` — 공유 메모리 현황 확인
## 디렉토리 규약
```
.opencode/shared/
├── memory/ → Git 추적, 영속
├── session/ → .gitignore, 임시
├── tasks/ → Orchestrator가 생성
└── artifacts/ → 산출물, Git 추적 선택
```
실전 적용 — 멀티 에이전트의 동작 흐름
지금까지의 설정이 실제로 어떻게 동작하는지 end-to-end 시나리오로 봅니다.
사용자: /review branch=feature/oauth2-pkce
Orchestrator:
1. git diff --name-only main...feature/oauth2-pkce → 23개 파일
2. .opencode/shared/session/ 초기화
3. patterns.md 로드 → P-001, P-002, P-003 확인
4. 작업 명세 생성: .opencode/shared/tasks/review-task-001.md
5. 병렬 위임:
→ @ParallelReviewer (background 세션 시작)
→ @ParallelTester (background 세션 시작)
→ @ParallelSecurity (background 세션 시작)
ParallelReviewer (자식 세션 1):
1. patterns.md 읽음 → P-001 (async 에러 미처리) 주의
2. 23개 파일 순회
3. src/auth/pkce.ts:87 에서 P-001 재발견
→ findings/reviewer.md 에 "P-001 재발견: src/auth/pkce.ts:87" 기록
4. src/auth/token.ts:142 에서 새로운 패턴 발견
→ "토큰 갱신 시 race condition 가능성"
→ findings/reviewer.md 에 신규 패턴으로 기록
5. 리뷰 완료 → review-results/ 에 최종 결과 저장
ParallelTester (자식 세션 2):
1. patterns.md + findings/reviewer.md 읽음
→ Reviewer가 발견한 P-001 재발견 확인
→ pkce.ts:87 의 에러 미처리에 대한 테스트 케이스 추가
2. 기존 테스트 패턴 분석: tests/auth/*.test.ts
3. 테스트 파일 생성:
→ tests/auth/pkce.test.ts (15개 케이스)
→ tests/auth/token-refresh.test.ts (8개 케이스, race condition 포함)
4. 완료 → test-results/ 에 요약 저장
ParallelSecurity (자식 세션 3):
1. patterns.md 읽음 → P-002 (SQL 파라미터 문자열 연결) 주의
2. OWASP Top 10 기준으로 23개 파일 스캔
3. src/auth/pkce.ts: PKCE code_verifier 길이 검증 누락 발견
→ CVSS 5.3 (Medium) — code_verifier가 짧으면 brute-force 가능
4. src/middleware/cors.ts: 와일드카드 origin 허용
→ CVSS 4.3 (Medium)
5. 완료 → security-results/ 에 최종 결과 저장
Orchestrator (결과 통합):
1. 세 에이전트의 결과 파일 수집
2. 심각도별 정렬:
- Critical: 0건
- Medium: 2건 (보안)
- Warning: 4건 (리뷰)
- Info: 3건 (리뷰)
3. 신규 패턴 후보: "토큰 갱신 race condition" (승격 보류 - 1회 발견)
4. 최종 리포트 생성 → artifacts/final-report.md
5. 사용자에게 요약 보고
전체 소요 시간은 약 4분. 순차 실행이었다면 9분 이상이었을 것입니다. 그리고 Reviewer의 발견을 Tester가 즉시 참조해서 race condition 테스트를 추가한 부분 — 이것이 Hive Mind 패턴의 실질적 가치입니다.
멀티 에이전트 시스템의 현실적 고려사항
비용 관리
병렬 실행은 시간을 줄이지만 동시 API 호출이 늘어납니다. 모델 프로바이더의 가격 정책을 확인하고 비용 추정을 해야 합니다.
- 병렬 에이전트 수 제한: 한 번에 3개를 넘기지 않는 것을 권장합니다. 대부분의 API 요금제에서 동시 세션 제한에 걸리지 않는 선입니다.
- 모델 티어링: 5일차에서 다룬 모델 라우팅을 적극 활용합니다. 병렬 서브에이전트는 Sonnet급, Orchestrator만 Opus급으로 배치하면 비용 대비 품질을 최적화할 수 있습니다.
- 스캔 범위 제한: 변경되지 않은 파일까지 전체 스캔하면 비용이 급증합니다. git diff 기반으로 변경 파일만 대상으로 삼아야 합니다.
디버깅
병렬 시스템은 디버깅이 어렵습니다. 어떤 에이전트가 언제 무엇을 했는지 추적하려면 체계적인 로깅이 필수입니다.
// .opencode/shared/session/fallback-log.md 의 형식
## 2026-08-19T10:23:45
- 에이전트: ParallelReviewer
- 이벤트: 작업 시작
- 파일 수: 23
- 모델: anthropic/claude-sonnet-4-6
## 2026-08-19T10:24:12
- 에이전트: ParallelReviewer
- 이벤트: 패턴 매칭
- 내용: P-001 재발견 (src/auth/pkce.ts:87)
## 2026-08-19T10:25:30
- 에이전트: ParallelTester
- 이벤트: 세션 메모리 참조
- 참조 파일: findings/reviewer.md
- 활용: P-001 재발견 항목 → 테스트 케이스 추가
충돌 해결
병렬 에이전트가 같은 파일을 수정하려 할 때의 충돌 해결 전략입니다.
- 쓰기 권한 분리: 각 에이전트는 자신의 전용 출력 디렉토리만 사용합니다. 소스 코드 수정 권한은 하나의 에이전트(보통 Refactorer)에게만 부여합니다.
- Lock 파일: 소스 코드를 수정해야 하는 경우, 먼저
.opencode/shared/session/locks/{파일경로}.lock을 생성합니다. 다른 에이전트는 lock 파일이 있으면 해당 파일 수정을 건너뜁니다. - Orchestrator 중재: 두 에이전트가 모순되는 수정을 제안하면 Orchestrator가 양쪽 근거를 비교해 최종 결정합니다.
Gotcha — 흔히 빠지는 함정
공유 메모리 파일의 동시 쓰기 충돌
병렬 에이전트 A와 B가 거의 동시에 findings/reviewer.md 에 결과를 쓰려 하면, 한쪽의 내용이 덮어씌워질 수 있습니다. 파일 시스템 기반 공유 메모리의 근본적 한계입니다.
해결책: 에이전트별로 전용 출력 파일을 사용합니다. findings/reviewer.md와 findings/tester.md를 분리하고, 통합은 Orchestrator만 수행합니다. 하나의 파일에 여러 에이전트가 쓰는 구조는 반드시 피하세요. 위의 전체 설정 예시에서도 이 원칙을 일관되게 적용했습니다.
정리 — 오늘 만든 것과 내일 추가할 것
오늘 우리는 opencode 멀티 에이전트 시스템의 다섯 가지 핵심 패턴을 구축했습니다. 병렬 백그라운드 실행으로 시간을 줄이고, Hive Mind 패턴으로 에이전트 간 학습을 공유하고, 카테고리 기반 위임으로 자동 라우팅을 만들고, Fallback Chain으로 장애에도 멈추지 않는 시스템을 설계했습니다.
내일 12일차 — 시즌 2의 마지막 날입니다. 지금까지 만든 모든 조각(에이전트 정의, 시스템 프롬프트, 권한, 모델 라우팅, 오케스트레이션, 컨텍스트, 커맨드, 플러그인, MCP, 멀티 에이전트)을 하나로 결합해 도메인 특화 에이전트 팀을 처음부터 끝까지 완성합니다. 시즌 1부터 시즌 2까지 24일의 여정을 한 장 다이어그램으로 요약하는 피날레, 기대해 주세요.
Photo by Jesús Esteban San José on Pexels
Photo by Glen Zi 加侖子 on Pexels
◀ 이전 10화 (다음 차수는 아직 게시되지 않았습니다)
자주 묻는 질문
opencode 멀티 에이전트 시스템에서 병렬 백그라운드 실행은 어떻게 설정하나요?
에이전트 정의 파일에서 background: true 옵션을 설정하면 해당 서브에이전트가 별도의 자식 세션에서 비동기로 실행됩니다. Primary 에이전트가 작업을 위임하면 백그라운드 서브에이전트는 즉시 제어권을 돌려주고, 완료 시점에 결과를 비동기로 보고합니다. 이를 통해 여러 서브에이전트가 동시에 작업하여 전체 처리 시간을 단축할 수 있습니다.
opencode 멀티 에이전트의 Hive Mind 패턴은 어떤 문제를 해결하나요?
Hive Mind 패턴은 에이전트 간 공유 영속 메모리를 구축하여 중복 작업을 제거하고 학습을 누적하는 방법입니다. 여러 에이전트가 동시에 작업할 때 같은 내용을 반복 분석하는 비효율을 방지하고, 이전 작업 결과를 공유 메모리에 저장해 팀 전체의 지식으로 활용할 수 있습니다.
opencode 멀티 에이전트에서 모델 장애나 세션 실패가 발생하면 어떻게 대응하나요?
Fallback Chain 패턴을 통해 모델 장애나 세션 실패 시 자동 복구되는 복원력 있는 시스템을 설계할 수 있습니다. 이 패턴은 다섯 가지 멀티 에이전트 협업 패턴 중 하나로, 특정 에이전트나 모델에 문제가 생겼을 때 대체 경로로 자동 전환하여 전체 파이프라인이 중단되지 않도록 합니다.
[…] 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기 (총 12화 중 12화)◀ 이전 11화 (다음 차수는 아직 게시되지 […]