[opencode 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기] 6/12화: opencode 서브에이전트 오케스트레이션 4인 전문가 팀 구성법 2026
이 글은 「opencode 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기」 6일차입니다. Phase C 오케스트레이션·컨텍스트의 첫 번째 관문으로, 오늘부터 에이전트 ‘한 명’이 아닌 ‘팀’을 다룹니다.
시즌 1 6일차에서 opencode의 서브에이전트 개념을 처음 만났던 걸 기억하시나요? 그때는 내장 에이전트(Explore, Scout)를 ‘쓰는’ 수준이었습니다. 오늘은 그 서브에이전트를 직접 설계하고, 팀으로 엮어 자동 위임까지 구현합니다.
어제 5일차에서는 에이전트별로 최적의 모델을 배치하는 라우팅 전략을 다뤘습니다. 모델 배치가 ‘개인의 능력치 세팅’이었다면, 오늘의 opencode 서브에이전트 오케스트레이션은 ‘팀 편성과 작전 수립’에 해당합니다. 아무리 뛰어난 개인도 혼자서 모든 역할을 완벽히 수행할 수 없듯, 에이전트도 마찬가지입니다.
오늘의 핵심 3가지
- 1 Primary + N Subagent 허브 앤 스포크 모델 — Primary가 지휘관, Subagent가 전문가 팀원으로 동작하는 오케스트레이션 구조를 이해합니다.
- description 자동 위임 vs @멘션 수동 호출 — 두 가지 위임 메커니즘의 작동 원리, 장단점, 사용 시점을 비교합니다.
- Reviewer·Tester·Refactor·SecurityAuditor 4인 팀 실전 구성 — 즉시 동작하는 에이전트 정의 파일 4개를 직접 만들고, 역할 분담 매트릭스로 정리합니다.
혼자 일하는 에이전트의 한계 — 왜 팀이 필요한가
3일차에서 시스템 프롬프트를 설계할 때, 하나의 프롬프트에 너무 많은 역할을 담으면 품질이 떨어진다는 점을 경험했습니다. “코드를 리뷰하고, 테스트도 작성하고, 보안 취약점도 점검하고, 리팩토링 제안도 해줘”라고 하나의 에이전트에게 시키면 어떻게 될까요?
실제로 이런 만능 에이전트를 만들어 써보면 세 가지 문제가 반복됩니다.
문제 1: 역할 충돌
리뷰어는 “이 코드는 이상하니 바꿔라”고 말해야 하고, 리팩토러는 “바꿀 때 이 패턴을 적용하라”고 제안해야 합니다. 두 역할이 하나의 시스템 프롬프트에 섞이면, LLM은 리뷰와 리팩토링 제안을 뒤죽박죽으로 내놓습니다. 코드에서 문제를 ‘발견’하는 관점과 문제를 ‘해결’하는 관점은 근본적으로 다른 사고 모드를 요구합니다.
문제 2: 컨텍스트 낭비
보안 감사에 필요한 OWASP Top 10 체크리스트, 테스트 작성에 필요한 프레임워크별 가이드, 리팩토링에 필요한 디자인 패턴 카탈로그를 모두 한 프롬프트에 넣으면 어떻게 될까요? 토큰이 부족해지기 전에, 에이전트가 이 방대한 지침 중 어떤 것을 우선할지 혼란에 빠집니다. 컨텍스트 윈도우가 유한한 자원이라는 것을 3일차에서 배웠습니다. 역할을 분리하면 각 에이전트에게 꼭 필요한 컨텍스트만 제공할 수 있습니다.
문제 3: 권한의 모순
4일차에서 배운 권한 설계를 떠올려 보세요. 코드 리뷰어는 읽기 전용이어야 안전합니다. 그런데 같은 에이전트가 테스트 코드도 작성해야 한다면? 파일 쓰기 권한을 줘야 합니다. 보안 감사 중에 파일 쓰기 권한이 열려 있다면? 의도치 않은 코드 변경이 발생할 수 있습니다. 역할별로 에이전트를 분리하면, 각 역할에 정확히 맞는 최소 권한을 부여할 수 있습니다.
이 세 가지 문제의 해법이 바로 오케스트레이션입니다. 한 명의 만능 에이전트 대신, 전문화된 에이전트 여러 명이 협업하는 구조를 만드는 것입니다.
opencode 서브에이전트 오케스트레이션 구조 이해하기
opencode의 오케스트레이션 모델은 허브 앤 스포크(Hub and Spoke) 구조입니다. Anthropic의 에이전트 설계 가이드에서 말하는 “orchestrator-workers” 패턴과 같은 계열입니다. 중앙의 Primary 에이전트가 허브 역할을 하고, Subagent들이 스포크로 뻗어 나갑니다.
1 Primary + N Subagent — 허브 앤 스포크 모델
opencode의 에이전트 계층을 다시 정리하겠습니다. 1일차에서 다룬 5계층 구조 중, 오케스트레이션에 직접 관여하는 것은 Primary 계층과 Subagent 계층입니다.
- Primary 에이전트 (Build, Plan): 사용자와 직접 대화하며, 전체 작업의 흐름을 관장합니다. 작업을 분석하고, 적절한 Subagent에게 위임하고, 결과를 종합합니다.
- Subagent (General, Explore, Scout + 커스텀): Primary로부터 위임받은 작업을 전문적으로 수행합니다. 자체 시스템 프롬프트, 권한, 모델을 가지며, 작업이 끝나면 결과를 Primary에게 반환합니다.
이 구조에서 핵심 규칙은 단순합니다.
- 사용자 ↔ Primary: 항상 사용자는 Primary와 대화합니다.
- Primary → Subagent: Primary가 Subagent에게 작업을 위임합니다.
- Subagent → Primary: Subagent가 결과를 Primary에게 돌려줍니다.
- Subagent ↔ Subagent: Subagent끼리 직접 통신하지 않습니다. 반드시 Primary를 경유합니다.
이 마지막 규칙이 중요합니다. Subagent끼리 직접 대화하면 흐름 추적이 불가능해지고, 순환 호출의 위험이 생깁니다. Primary가 모든 소통의 중심에 있기 때문에 작업 흐름이 예측 가능하고, 문제가 생겼을 때 어디서 잘못됐는지 파악할 수 있습니다.
이제 Primary가 어떻게 “적절한 Subagent”를 골라서 위임하는지 알아봅시다. opencode는 두 가지 위임 메커니즘을 제공합니다.
description 기반 자동 위임의 원리
2일차에서 에이전트를 정의할 때 description 필드를 작성한 것을 기억하시나요? 그때는 단순히 “이 에이전트가 뭘 하는지 설명”이라고 넘어갔습니다. 하지만 이 필드의 진짜 역할은 오케스트레이션의 라우팅 키입니다.
자동 위임은 이런 과정으로 일어납니다.
- 사용자가 Primary에게 작업을 요청합니다. (예: “이 PR의 보안 취약점을 점검해줘”)
- Primary는 등록된 모든 Subagent의
description을 읽습니다. - 요청 내용과 각 description을 대조하여 가장 적합한 Subagent를 판단합니다.
- 선택된 Subagent에게 작업을 위임합니다.
- Subagent가 자신의 시스템 프롬프트와 권한 범위 내에서 작업을 수행합니다.
- 결과를 Primary에게 반환하고, Primary가 사용자에게 전달합니다.
여기서 description의 품질이 오케스트레이션의 정확도를 결정합니다. 나쁜 description과 좋은 description을 비교해 보겠습니다.
# ❌ 나쁜 description — 너무 모호함
description: "코드 관련 작업을 합니다"
# ❌ 나쁜 description — 너무 넓음
description: "코드를 분석하고 개선합니다"
# ✅ 좋은 description — 구체적 역할 + 트리거 키워드
description: "코드 변경사항을 리뷰하여 버그·성능·가독성 문제를 찾고,
개선 방향을 제안합니다. PR 리뷰, 코드 리뷰, diff 분석 요청 시 호출됩니다"
# ✅ 좋은 description — 경계가 명확함
description: "단위 테스트와 통합 테스트를 작성합니다. 테스트 커버리지를 분석하고,
누락된 엣지 케이스를 식별합니다. 테스트 코드 작성, 커버리지 확인 요청 시 호출됩니다"좋은 description의 공통점이 보이시나요? 세 가지 요소를 갖추고 있습니다.
- 구체적인 역할 서술: “무엇을 하는지”가 명확합니다.
- 트리거 키워드: 사용자가 쓸 법한 단어(리뷰, 테스트, 보안, 리팩토링)가 포함됩니다.
- 역할 경계: “이것은 하지만 저것은 하지 않는다”가 암시됩니다.
description이 서로 겹치면 Primary가 헷갈립니다. 예를 들어 Reviewer의 description에 “코드 개선 제안”이 있고, Refactor의 description에도 “코드 개선”이 있다면, “이 함수를 개선해줘”라는 요청에 어느 에이전트를 골라야 할지 모호해집니다. 각 에이전트의 description은 겹치지 않는 고유 영역을 가져야 합니다.
@멘션 수동 호출 — 정확한 전문가 지목
자동 위임이 항상 최선은 아닙니다. 때로는 사용자가 직접 특정 에이전트를 지명하고 싶을 때가 있습니다. opencode에서는 @에이전트이름으로 수동 호출이 가능합니다.
# 자동 위임 — Primary가 알아서 적합한 에이전트를 고름
> 이 함수의 테스트를 작성해줘
# 수동 호출 — 특정 에이전트를 직접 지목
> @tester 이 함수의 엣지 케이스 테스트를 작성해줘
> @security-auditor 이 API 엔드포인트의 인증 로직을 점검해줘
> @refactor 이 클래스를 전략 패턴으로 리팩토링해줘수동 호출이 유용한 상황은 명확합니다.
- 자동 위임이 원하는 에이전트를 못 고를 때: description이 아직 정교하지 않거나, 요청이 애매한 경우.
- 순차 파이프라인을 직접 구성하고 싶을 때: “@reviewer 이 코드를 리뷰해줘” → (결과 확인) → “@refactor 리뷰 결과를 반영해서 리팩토링해줘” → “@tester 리팩토링된 코드의 테스트를 작성해줘”
- 같은 작업을 다른 관점으로 보고 싶을 때: “@reviewer 이 코드를 봐줘” 그리고 “@security-auditor 같은 코드를 보안 관점에서 봐줘”
자동 위임과 수동 호출의 선택 기준을 표로 정리하겠습니다.
| 기준 | 자동 위임 (description) | 수동 호출 (@멘션) |
|---|---|---|
| 적합한 상황 | 일상적이고 반복적인 작업 | 정밀한 제어가 필요한 작업 |
| 사용자 개입 | 없음 — Primary가 판단 | 사용자가 직접 지목 |
| 정확도 의존 | description 품질에 좌우 | 사용자 판단에 좌우 |
| 파이프라인 구성 | Primary가 자동 조합 | 사용자가 순서 제어 가능 |
| 학습 곡선 | 에이전트 이름 몰라도 됨 | 에이전트 이름·역할 숙지 필요 |
| 추천 시점 | 팀 구성 안정화 이후 | 초기 세팅·디버깅·정밀 작업 |
실무적으로는 초기에 @멘션으로 시작해서, description을 다듬어가며 점차 자동 위임 비율을 높이는 전략이 효과적입니다. description을 처음부터 완벽하게 쓸 수 없으니까요. 써보면서 “이 요청에 엉뚱한 에이전트가 호출됐네?” 하는 경우를 관찰하고 description을 개선하는 반복 사이클이 필요합니다.
전문가 팀 설계 — 역할 분담 매트릭스
이제 구체적인 팀을 구성할 차례입니다. 소프트웨어 개발에서 가장 범용적이면서도 효과가 확실한 4인 전문가 팀을 설계합니다. Reviewer, Tester, Refactor, SecurityAuditor — 이 네 역할은 대부분의 프로젝트에 바로 적용할 수 있습니다.
역할 분담 매트릭스
| 역할 | 핵심 책임 | 트리거 키워드 | 권한 수준 | 추천 모델 티어 |
|---|---|---|---|---|
| Reviewer | 코드 변경사항의 버그·성능·가독성 문제 발견 | 리뷰, review, PR, diff, 검토 | Read-only | Strong (Opus급) |
| Tester | 테스트 코드 작성, 커버리지 분석, 엣지 케이스 식별 | 테스트, test, 커버리지, coverage, 검증 | Read + Write (테스트 파일) | Mid (Sonnet급) |
| Refactor | 코드 구조 개선, 중복 제거, 패턴 적용 | 리팩토링, refactor, 개선, 구조, 패턴 | Read + Write (소스 파일) | Strong (Opus급) |
| SecurityAuditor | 보안 취약점 점검, OWASP 기준 감사 | 보안, security, 취약점, 감사, audit, XSS, SQL injection | Read-only | Strong (Opus급) |
이 매트릭스에서 주목할 점은 세 가지입니다.
첫째, 권한 수준의 차이. Reviewer와 SecurityAuditor는 Read-only입니다. “발견하는” 역할은 코드를 변경할 필요가 없고, 변경 권한이 없어야 더 안전합니다. 반면 Tester와 Refactor는 Write 권한이 필요하지만, 쓸 수 있는 파일 패턴을 제한합니다. 4일차에서 배운 권한 설계가 여기서 실전 적용됩니다.
둘째, 모델 티어의 차이. Reviewer, Refactor, SecurityAuditor는 깊은 분석과 판단이 필요하므로 Strong 티어(5일차에서 다룬 Opus급 모델)를 배치합니다. Tester는 상대적으로 패턴화된 작업(테스트 프레임워크에 맞춰 코드 생성)이므로 Mid 티어(Sonnet급)로도 충분한 경우가 많습니다. 물론 프로젝트 복잡도에 따라 조정합니다.
셋째, 트리거 키워드의 분리. 네 역할의 트리거 키워드가 겹치지 않도록 설계했습니다. “리뷰”는 Reviewer에게만, “테스트”는 Tester에게만, “리팩토링”은 Refactor에게만, “보안”은 SecurityAuditor에게만 매칭됩니다. description에 이 키워드들을 명시적으로 넣어서 자동 위임의 정확도를 높입니다.
각 역할의 상세 설계
Reviewer — 냉정한 코드 심판관
Reviewer의 핵심은 “발견”입니다. 코드를 직접 고치지 않습니다. 문제를 찾고, 왜 문제인지 설명하고, 어떤 방향으로 고쳐야 하는지 가이드만 합니다. 이 제약이 중요한 이유는 두 가지입니다.
- 리뷰어가 직접 코드를 수정하면, 리뷰 관점의 객관성이 흐려집니다.
- Read-only 권한을 유지할 수 있어 의도치 않은 코드 변경 위험이 사라집니다.
Reviewer가 점검해야 할 관점은 크게 다섯 가지입니다: 정확성(버그), 성능(병목), 가독성(네이밍·구조), 유지보수성(결합도·응집도), 그리고 일관성(코드 스타일·컨벤션).
Tester — 빈틈을 찾는 품질 보증관
Tester는 “검증 코드를 생산”합니다. 함수나 모듈을 받으면 단위 테스트를 작성하고, 엣지 케이스를 식별하고, 테스트 커버리지가 부족한 영역을 짚어냅니다. Write 권한이 필요하지만, 테스트 파일 경로에만 쓸 수 있도록 제한합니다.
좋은 Tester 에이전트는 프로젝트의 테스트 프레임워크를 인지합니다. Python이면 pytest, TypeScript면 vitest나 jest, Go면 내장 testing 패키지. 시스템 프롬프트에 프로젝트의 테스트 컨벤션을 명시하면 일관된 테스트 코드를 생산합니다.
Refactor — 구조를 다듬는 장인
Refactor는 “동작은 바꾸지 않고 구조만 개선”합니다. 가장 넓은 Write 권한이 필요하지만, 그만큼 위험도 큽니다. 그래서 시스템 프롬프트에 “기존 테스트가 모두 통과하는 것을 보장할 것”이라는 제약을 명시합니다. Refactor가 코드를 바꾼 뒤, Tester가 테스트를 돌리는 파이프라인을 구성하면 안전망이 됩니다.
SecurityAuditor — 보안의 파수꾼
SecurityAuditor는 “위협을 식별”합니다. Reviewer와 마찬가지로 Read-only이지만, 관점이 다릅니다. Reviewer가 “이 코드가 올바르게 작동하는가?”를 보는 반면, SecurityAuditor는 “이 코드가 공격에 안전한가?”를 봅니다. OWASP Top 10, 인젝션 공격, 인증·인가 결함, 민감 정보 노출 등 보안 특화 체크리스트로 코드를 심사합니다.
실전 구성 — 4인 전문가 팀 에이전트 파일 완전판
이론은 충분합니다. 지금부터 실제로 동작하는 에이전트 정의 파일 4개를 만들겠습니다. 2일차에서 배운 .opencode/agents/*.md 방식을 사용합니다. 3일차의 시스템 프롬프트 설계 원칙, 4일차의 권한 매트릭스, 5일차의 모델 라우팅을 모두 적용한 종합 실전편입니다.
프로젝트 루트에 다음 구조를 만듭니다.
.opencode/
└── agents/
├── reviewer.md
├── tester.md
├── refactor.md
└── security-auditor.md1. Reviewer 에이전트
# .opencode/agents/reviewer.md
---
description: |
코드 변경사항을 리뷰하여 버그·성능·가독성 문제를 찾고 개선 방향을 제안합니다.
PR 리뷰, 코드 리뷰, diff 분석, 변경사항 검토 요청 시 호출됩니다.
코드를 직접 수정하지 않고 발견한 문제와 개선 제안만 보고합니다.
model: anthropic/claude-opus-4-6
permission:
allow:
- Read
- Glob
- Grep
- Explore
deny:
- Edit
- Write
- Bash
---
당신은 시니어 코드 리뷰어입니다. 코드를 읽고 문제를 발견하는 것이 역할입니다.
## 리뷰 관점 (우선순위 순)
1. **정확성**: 로직 버그, off-by-one, null 참조, 경쟁 조건
2. **성능**: 불필요한 반복, N+1 쿼리, 메모리 누수 가능성
3. **가독성**: 불명확한 네이밍, 과도한 중첩, 매직 넘버
4. **유지보수성**: 높은 결합도, 낮은 응집도, 테스트 불가능한 구조
5. **일관성**: 프로젝트 코딩 컨벤션 위반
## 출력 형식
각 발견 사항을 다음 형식으로 보고하세요:
- **위치**: 파일명:라인 번호
- **심각도**: Critical / Major / Minor / Suggestion
- **문제**: 한 줄 요약
- **설명**: 왜 문제인지
- **제안**: 어떤 방향으로 개선할 수 있는지
## 제약
- 코드를 직접 수정하지 마세요. 발견과 제안만 합니다.
- 스타일 취향(탭 vs 스페이스, 따옴표 종류)은 프로젝트 설정을 따릅니다.
- 칭찬할 점이 있으면 함께 언급합니다 — 좋은 코드도 인정해야 리뷰가 건강합니다.2. Tester 에이전트
# .opencode/agents/tester.md
---
description: |
단위 테스트와 통합 테스트를 작성하고 테스트 커버리지를 분석합니다.
누락된 엣지 케이스를 식별하고 테스트 품질을 개선합니다.
테스트 작성, 커버리지 확인, 검증, test 관련 요청 시 호출됩니다.
model: anthropic/claude-sonnet-4-6
permission:
allow:
- Read
- Glob
- Grep
- Explore
- "Edit(tests/**)"
- "Write(tests/**)"
- "Edit(test_*)"
- "Write(test_*)"
- "Bash(pytest*)"
- "Bash(pnpm test*)"
- "Bash(npm test*)"
deny:
- "Edit(src/**)"
- "Write(src/**)"
- "Bash(rm*)"
---
당신은 테스트 전문가입니다. 코드를 받으면 테스트를 작성하고 실행합니다.
## 테스트 작성 원칙
1. **AAA 패턴**: Arrange(준비) → Act(실행) → Assert(검증)
2. **테스트 이름**: 한글 또는 영문으로 "무엇을_하면_어떻게_되어야_한다" 패턴
3. **엣지 케이스 우선**: 해피 패스보다 경계값·에러 경로를 먼저 커버
4. **격리**: 외부 의존성은 mock/stub으로 격리. DB·네트워크·파일시스템 직접 접근 금지
5. **결정적**: 실행할 때마다 같은 결과. 난수·시각 의존 시 seed/freeze 사용
## 커버리지 분석 시
- 현재 커버리지 수치를 먼저 확인
- 분기(branch) 커버리지 기준으로 누락된 경로 식별
- 새 테스트가 어떤 분기를 추가 커버하는지 명시
## 프레임워크 감지
프로젝트의 설정 파일(pyproject.toml, package.json, go.mod 등)을 읽고
사용 중인 테스트 프레임워크를 자동 감지합니다. 감지된 프레임워크의 컨벤션을 따릅니다.
## 제약
- 소스 코드(src/)는 수정하지 마세요. 테스트 파일만 생성·수정합니다.
- 테스트 작성 후 반드시 실행하여 통과를 확인합니다.3. Refactor 에이전트
# .opencode/agents/refactor.md
---
description: |
기존 코드의 구조를 개선하고 중복을 제거하며 적절한 디자인 패턴을 적용합니다.
동작(외부 관찰 가능한 행위)은 변경하지 않고 내부 구조만 개선합니다.
리팩토링, refactor, 구조 개선, 중복 제거, 패턴 적용 요청 시 호출됩니다.
model: anthropic/claude-opus-4-6
permission:
allow:
- Read
- Glob
- Grep
- Explore
- "Edit(src/**)"
- "Write(src/**)"
- "Bash(pytest*)"
- "Bash(pnpm test*)"
ask:
- "Edit(*.config.*)"
- "Write(*.config.*)"
deny:
- "Edit(tests/**)"
- "Bash(rm*)"
- "Bash(git*)"
---
당신은 리팩토링 전문가입니다. 코드의 외부 동작을 보존하면서 내부 구조를 개선합니다.
## 리팩토링 프로세스
1. **현상 파악**: 대상 코드를 읽고 현재 구조의 문제점을 식별
2. **영향 범위 분석**: 변경 시 영향받는 파일·함수·테스트 목록 작성
3. **계획 수립**: 적용할 리팩토링 기법과 순서를 설명
4. **단계적 실행**: 한 번에 하나의 리팩토링만 적용 (Small Steps)
5. **검증**: 각 단계 후 기존 테스트 실행하여 동작 보존 확인
## 적용 가능한 기법 (우선 고려)
- Extract Method / Extract Class
- Replace Conditional with Polymorphism
- Introduce Parameter Object
- Replace Magic Number with Named Constant
- Move Method / Move Field
- Strategy / Template Method 패턴 도입
## 제약
- 외부 관찰 가능한 동작(API 시그니처, 반환값, 부수효과)을 바꾸지 마세요.
- 테스트 파일은 수정하지 마세요. 테스트는 @tester의 영역입니다.
- 리팩토링 전후로 기존 테스트가 모두 통과해야 합니다.
- 한 번에 너무 많은 것을 바꾸지 마세요. 작은 단위로 나눠서 진행합니다.4. SecurityAuditor 에이전트
# .opencode/agents/security-auditor.md
---
description: |
코드의 보안 취약점을 점검하고 OWASP Top 10 기준으로 감사합니다.
인젝션, 인증·인가 결함, 민감 정보 노출, 의존성 취약점 등을 식별합니다.
보안, security, 취약점, 감사, audit, XSS, 인젝션 관련 요청 시 호출됩니다.
model: anthropic/claude-opus-4-6
permission:
allow:
- Read
- Glob
- Grep
- Explore
- "Bash(npm audit*)"
- "Bash(pip-audit*)"
- "Bash(safety check*)"
deny:
- Edit
- Write
- "Bash(curl*)"
- "Bash(wget*)"
- "Bash(rm*)"
---
당신은 보안 감사 전문가입니다. 코드를 보안 관점에서 심사합니다.
## 감사 체크리스트 (OWASP Top 10 2021 기반)
### A01: Broken Access Control
- [ ] 인가 검증 누락된 엔드포인트가 있는가?
- [ ] IDOR(Insecure Direct Object Reference) 가능성이 있는가?
- [ ] CORS 설정이 과도하게 열려 있지 않은가?
### A02: Cryptographic Failures
- [ ] 평문으로 저장되는 민감 정보(비밀번호, 토큰, 키)가 있는가?
- [ ] 약한 해시 알고리즘(MD5, SHA1)을 사용하고 있는가?
- [ ] TLS/HTTPS가 강제되는가?
### A03: Injection
- [ ] SQL 쿼리에 사용자 입력이 직접 삽입되는가?
- [ ] 셸 명령에 사용자 입력이 전달되는가?
- [ ] XSS 가능한 미이스케이프 출력이 있는가?
### A04: Insecure Design
- [ ] 비즈니스 로직에 우회 가능한 허점이 있는가?
- [ ] Rate limiting이 적용되어 있는가?
### A05: Security Misconfiguration
- [ ] 디버그 모드가 프로덕션에서 활성화되어 있는가?
- [ ] 불필요한 기능/포트/서비스가 노출되어 있는가?
- [ ] 기본 비밀번호/키가 그대로 사용되고 있는가?
### A06-A10 (축약)
- [ ] 취약한 의존성(A06), 인증 결함(A07), 무결성 검증 부재(A08), 로깅 부족(A09), SSRF(A10)
## 출력 형식
각 발견 사항을 다음 형식으로 보고하세요:
- **위치**: 파일명:라인 번호
- **CWE**: 해당 CWE 번호 (알 수 있는 경우)
- **심각도**: Critical / High / Medium / Low / Info
- **취약점**: 한 줄 요약
- **공격 시나리오**: 어떻게 악용될 수 있는지
- **수정 방안**: 구체적인 코드 수준 해결책
## 제약
- 코드를 직접 수정하지 마세요. 발견과 권고만 합니다.
- 의존성 감사 도구(npm audit, pip-audit)는 실행할 수 있지만,
외부 네트워크 호출(curl, wget)은 사용하지 마세요.
- 위양성(false positive)이 의심되면 명시적으로 표시합니다.opencode.json에서 팀 통합 설정
위 .opencode/agents/*.md 파일들은 프로젝트에 놓으면 자동으로 인식됩니다. 추가로 opencode.json에서 기본 에이전트와 모델 fallback을 설정할 수 있습니다.
{
"default_agent": "build",
"model": {
"primary": "anthropic/claude-opus-4-6",
"secondary": "anthropic/claude-sonnet-4-6"
},
"agent": {
"build": {
"description": "코드 구현과 기능 개발을 담당하는 기본 에이전트입니다. 새 기능 추가, 버그 수정, 코드 작성 요청 시 호출됩니다.",
"model": "anthropic/claude-opus-4-6"
}
}
}여기서 agent 키에 Build(Primary) 에이전트를 정의하고, 나머지 4인 전문가 팀은 .opencode/agents/의 Markdown 파일로 정의합니다. 왜 이렇게 분리할까요?
- Primary(Build)는 opencode.json에: 프로젝트 전체의 기본 동작을 결정하는 핵심 설정이므로 JSON에서 명시적으로 관리합니다.
- Subagent들은 .opencode/agents/에: 역할별로 파일이 분리되어 있어 시스템 프롬프트가 길어져도 관리가 편하고, 팀원 추가·제거가 파일 단위로 가능합니다.
2일차에서 배운 두 가지 정의 방식의 장점을 모두 활용하는 하이브리드 전략입니다.
opencode 서브에이전트 오케스트레이션 실전 시나리오
4인 팀이 구성됐습니다. 이제 실제 개발 작업에서 이 팀이 어떻게 협업하는지, 시나리오를 통해 살펴봅시다.
시나리오: “결제 API에 할인 쿠폰 기능 추가”
사용자가 Primary(Build)에게 말합니다.
> 결제 API에 할인 쿠폰 적용 기능을 추가해줘.
쿠폰 코드를 입력하면 할인율이 적용되어야 하고,
만료된 쿠폰이나 잘못된 코드는 거부해야 해.단계 1: Primary(Build)가 기능을 구현합니다.
Primary는 이 요청이 “새 기능 구현”이라고 판단하고, 자기가 직접 처리합니다. 쿠폰 모델 정의, 검증 로직, API 엔드포인트 추가 등을 수행합니다.
단계 2: 구현 완료 후, 리뷰를 요청합니다.
> 구현이 끝났으니 코드를 리뷰해줘Primary는 이 요청의 키워드 “리뷰”를 감지하고, Reviewer 에이전트의 description과 매칭합니다. 자동 위임이 발동되어 Reviewer가 호출됩니다. Reviewer는 Read-only 권한으로 변경된 파일들을 읽고, 정해진 형식으로 리뷰 결과를 보고합니다.
[Reviewer 보고 예시]
- **위치**: src/api/coupon.py:45
- **심각도**: Critical
- **문제**: 쿠폰 할인율 검증 누락
- **설명**: discount_rate이 음수이거나 100을 초과하는 경우를 처리하지 않음
- **제안**: 0 < discount_rate <= 100 범위 검증 추가
- **위치**: src/api/coupon.py:62
- **심각도**: Major
- **문제**: 만료 시간 비교에 timezone 미고려
- **설명**: datetime.now()와 coupon.expires_at 비교 시 timezone-aware vs naive 불일치 가능
- **제안**: datetime.now(tz=UTC) 사용 또는 프로젝트 표준 시간 유틸리티 활용단계 3: 리뷰 결과를 반영하고, 보안 점검을 요청합니다.
> 리뷰 결과를 반영했어. @security-auditor 쿠폰 관련 코드를 보안 점검해줘이번에는 @멘션 수동 호출입니다. 결제 관련 코드이므로 보안 점검을 건너뛰면 안 된다는 사용자의 판단입니다. SecurityAuditor가 호출되어 OWASP 체크리스트 기반으로 감사합니다.
[SecurityAuditor 보고 예시]
- **위치**: src/api/coupon.py:38
- **CWE**: CWE-20
- **심각도**: High
- **취약점**: 쿠폰 코드 입력값 길이 제한 없음
- **공격 시나리오**: 매우 긴 문자열 입력으로 ReDoS 또는 메모리 고갈 유발 가능
- **수정 방안**: 쿠폰 코드 길이를 최대 32자로 제한하는 검증 추가
- **위치**: src/api/coupon.py:72
- **CWE**: CWE-362
- **심각도**: Medium
- **취약점**: 쿠폰 사용 횟수 차감에 원자적 연산 미적용
- **공격 시나리오**: 동시 요청으로 같은 쿠폰을 여러 번 사용 가능 (TOCTOU)
- **수정 방안**: DB 레벨 원자적 차감 또는 비관적 락 적용단계 4: 보안 이슈를 수정하고, 테스트를 작성합니다.
> 보안 이슈를 수정했어. @tester 쿠폰 기능에 대한 테스트를 작성해줘Tester가 호출됩니다. 소스 코드를 읽어서(Read 권한) 기능을 이해하고, 테스트 파일을 생성합니다(Write(tests/**) 권한). 해피 패스, 만료 쿠폰 거부, 잘못된 코드 거부, 할인율 경계값, 동시 사용 방지 등을 테스트합니다.
단계 5: 테스트 통과를 확인하고 완료.
이 전체 흐름을 정리하면:
사용자 → Build(구현) → Reviewer(리뷰) → Build(수정)
→ SecurityAuditor(보안) → Build(수정) → Tester(테스트) → 완료Primary(Build)가 허브로서 모든 단계를 조율하고, 각 Subagent가 자기 전문 영역에서만 기여합니다. 이것이 opencode 서브에이전트 오케스트레이션의 실전 모습입니다.
위임 전략 심화 — 자동과 수동의 균형 잡기
위 시나리오에서 Reviewer는 자동 위임으로, SecurityAuditor와 Tester는 수동 호출(@멘션)로 동작했습니다. 이 차이는 의도적입니다. 언제 자동을, 언제 수동을 쓸지 결정하는 기준을 정리하겠습니다.
자동 위임이 효과적인 경우
- 루틴한 작업: “코드 리뷰해줘”처럼 매번 같은 패턴의 요청. description이 잘 작성되어 있으면 매번 정확하게 위임됩니다.
- 키워드가 명확한 요청: “테스트 작성”, “리팩토링”, “보안 점검”처럼 트리거 키워드가 요청에 그대로 포함된 경우.
- 단일 에이전트 매칭: 요청이 하나의 에이전트에만 해당하는 경우. 여러 에이전트가 매칭될 여지가 없는 경우.
수동 호출(@멘션)이 효과적인 경우
- 순차 파이프라인: “먼저 A가 하고, 그 다음 B가 하고” 같은 명시적 순서가 필요한 경우.
- 교차 검증: 같은 코드를 Reviewer와 SecurityAuditor 두 관점에서 동시에 보고 싶은 경우.
- description 미세 조정 중: 새 에이전트를 추가했는데 자동 위임이 아직 불안정한 초기 단계.
- 비전형적 요청: “이 함수의 시간 복잡도를 분석해줘” — Reviewer가 해야 할지, 별도의 분석 에이전트가 해야 할지 모호한 경우.
위임 정확도를 높이는 description 튜닝 팁
자동 위임의 정확도를 실전에서 높이기 위한 구체적인 팁입니다.
팁 1: 부정 조건을 명시하세요.
# Reviewer의 description에 추가
description: |
...
코드를 직접 수정하지 않고 발견한 문제와 개선 제안만 보고합니다.
⚠ 테스트 작성, 리팩토링 실행, 보안 전문 감사는 이 에이전트의 역할이 아닙니다.“이것은 하지 않는다”를 명시하면 Primary가 역할 경계를 더 정확하게 인식합니다.
팁 2: 트리거 키워드를 사용자의 실제 언어에 맞추세요.
개발자들이 실제로 쓰는 표현을 수집해서 description에 넣습니다. “코드 좀 봐줘”는 리뷰입니다. “이거 깨끗하게 정리해줘”는 리팩토링입니다. “이거 안전한지 확인해줘”는 보안 감사입니다. 사용자의 자연어 패턴을 트리거로 매핑합니다.
팁 3: 주기적으로 위임 로그를 확인하세요.
자동 위임이 어떤 에이전트를 선택했는지 관찰합니다. 잘못된 매칭이 반복되면 해당 에이전트의 description을 조정합니다. 예를 들어 “성능 개선해줘”라는 요청에 Reviewer가 호출되어야 하는데 Refactor가 호출된다면, Refactor의 description에서 “성능”이라는 단어를 빼고 “구조 개선”으로 대체합니다.
팀 확장 — 도메인별 커스텀 에이전트 추가
4인 기본 팀을 구성했으면, 프로젝트 특성에 맞게 전문 에이전트를 추가할 수 있습니다. 몇 가지 확장 예시를 보여드립니다.
확장 예시 1: DocWriter — 문서 작성 전문가
# .opencode/agents/doc-writer.md
---
description: |
API 문서, README, 사용 가이드, JSDoc/docstring을 작성합니다.
문서화, documentation, README, API 문서, 가이드 작성 요청 시 호출됩니다.
model: anthropic/claude-sonnet-4-6
permission:
allow:
- Read
- Glob
- Grep
- "Write(docs/**)"
- "Edit(docs/**)"
- "Write(README*)"
- "Edit(README*)"
deny:
- "Edit(src/**)"
- Bash
---
당신은 기술 문서 작성 전문가입니다. 코드를 읽고 명확한 문서를 생산합니다.
## 원칙
- 코드의 '무엇(what)'과 '왜(why)'를 설명합니다. 'how'는 코드 자체가 답합니다.
- 독자는 이 프로젝트를 처음 보는 개발자라고 가정합니다.
- 예제 코드는 복사-붙여넣기로 바로 동작해야 합니다.확장 예시 2: Migrator — DB 마이그레이션 전문가
# .opencode/agents/migrator.md
---
description: |
데이터베이스 스키마 변경과 마이그레이션 스크립트를 작성합니다.
마이그레이션, migration, 스키마 변경, DB 변경, 테이블 수정 요청 시 호출됩니다.
model: anthropic/claude-opus-4-6
permission:
allow:
- Read
- Glob
- Grep
- "Write(migrations/**)"
- "Edit(migrations/**)"
- "Bash(alembic*)"
- "Bash(prisma*)"
deny:
- "Edit(src/**)"
- "Bash(rm*)"
- "Bash(DROP*)"
---
당신은 DB 마이그레이션 전문가입니다. 안전한 스키마 변경을 설계합니다.
## 원칙
- 모든 마이그레이션은 롤백 가능해야 합니다 (up + down).
- 대용량 테이블 변경 시 무중단 마이그레이션 전략을 제안합니다.
- 데이터 손실 가능성이 있는 변경은 반드시 경고합니다.이런 식으로 프로젝트의 필요에 따라 에이전트를 추가합니다. 각 에이전트는 .opencode/agents/에 파일 하나를 추가하는 것만으로 팀에 합류합니다. 제거할 때도 파일을 삭제하면 끝입니다. 이 유연성이 Markdown 기반 에이전트 정의의 큰 장점입니다.
오케스트레이션 패턴 정리
지금까지 다룬 내용을 세 가지 오케스트레이션 패턴으로 정리합니다. 오늘은 기본 패턴을 확실히 잡고, 고급 패턴(병렬 실행, 공유 메모리)은 11일차에서 깊이 다룹니다.
패턴 1: 순차 파이프라인 (Sequential Pipeline)
Build(구현) → Reviewer(리뷰) → Build(수정) → Tester(테스트) → 완료가장 기본적인 패턴입니다. 각 단계가 이전 단계의 결과에 의존합니다. 코드를 구현해야 리뷰할 수 있고, 리뷰를 반영해야 테스트를 작성할 수 있습니다. @멘션으로 순서를 직접 제어하거나, 자연스러운 대화 흐름으로 Primary가 자동 조율합니다.
패턴 2: 교차 검증 (Cross-Validation)
Build(구현) → Reviewer(코드 품질)
→ SecurityAuditor(보안) → Build(종합 수정) → 완료같은 코드를 서로 다른 관점으로 동시에 검토합니다. Reviewer는 “올바른가?”를, SecurityAuditor는 “안전한가?”를 봅니다. 두 보고서를 합치면 단일 에이전트로는 얻기 어려운 다각적 피드백을 얻습니다.
패턴 3: 조건부 위임 (Conditional Delegation)
사용자 요청 → Primary 분석
├─ "테스트 관련" → Tester
├─ "보안 관련" → SecurityAuditor
├─ "구조 개선 관련" → Refactor
├─ "리뷰 관련" → Reviewer
└─ "구현 관련" → Build(자기 자신)자동 위임의 본질입니다. Primary가 요청을 분석해서 적절한 전문가에게 라우팅합니다. description의 품질이 이 라우팅의 정확도를 결정합니다.
에이전트 팀 설계 시 주의할 점 5가지
4인 팀을 실전에 투입하기 전에 점검할 사항들입니다.
1. 역할 경계를 명확히 하세요
“이 작업은 누가 해야 하지?”라는 질문에 항상 하나의 답이 나와야 합니다. 두 에이전트의 역할이 겹치면 자동 위임이 불안정해지고, 같은 작업을 두 번 수행하는 낭비가 생깁니다. 역할이 모호한 영역이 있다면 description에 “이것은 이 에이전트가, 저것은 저 에이전트가”를 명시적으로 구분합니다.
2. 팀 규모를 적정하게 유지하세요
에이전트가 많을수록 좋은 게 아닙니다. Primary가 위임 대상을 판단할 때, 후보 에이전트가 10개면 오판 확률이 올라갑니다. 경험적으로 3~6개가 관리 가능한 범위입니다. 더 세분화가 필요하면 11일차에서 다룰 카테고리 기반 계층 구조를 고려하세요.
3. 권한은 최소로, 점진적으로
4일차의 원칙을 다시 강조합니다. 새 에이전트를 추가할 때는 deny-first로 시작합니다. 필요한 권한만 하나씩 열어갑니다. 특히 Write와 Bash 권한은 꼭 필요한 경로·명령어 패턴만 허용합니다.
4. 모델 비용을 의식하세요
4인 모두 Opus급 모델을 쓰면 비용이 빠르게 올라갑니다. 5일차에서 다룬 모델 라우팅 전략을 적용해서, 정밀 판단이 필요한 역할(Reviewer, SecurityAuditor)에만 Strong 모델을, 패턴화된 작업(Tester)에는 Mid 모델을 배치합니다.
5. 점진적으로 도입하세요
처음부터 4인 팀을 한꺼번에 도입할 필요는 없습니다. 가장 시급한 역할 하나(예: Reviewer)부터 시작해서 안정화한 뒤, 다음 역할을 추가합니다. 각 에이전트의 description과 시스템 프롬프트를 실제 사용 중에 다듬어가는 것이 중요합니다.
Gotcha 미니 코너 — description 겹침 함정
함정: Reviewer의 description에 “코드 개선 제안”을 넣고, Refactor의 description에도 “코드 개선”을 넣었더니, “이 코드를 개선해줘”라는 요청에 매번 다른 에이전트가 호출됩니다.
증상: 같은 요청을 두 번 보내면 첫 번째는 Reviewer가, 두 번째는 Refactor가 응답합니다. Primary가 두 description 사이에서 동전 던지기를 하는 셈입니다.
원인: “코드 개선”이라는 키워드가 두 에이전트의 description에 모두 존재합니다. Primary 입장에서 어느 쪽이 더 적합한지 판단할 근거가 부족합니다.
해결: 각 에이전트의 description에서 겹치는 표현을 제거하고, 고유한 표현으로 대체합니다.
# Reviewer — "개선"이라는 단어를 빼고, "발견"/"지적"으로 교체
description: |
코드 변경사항의 버그·성능·가독성 문제를 발견하고 지적합니다.
코드를 직접 수정하지 않습니다.
# Refactor — "개선" 유지하되, "구조"를 강조
description: |
코드의 내부 구조를 개선하고, 중복을 제거하며, 디자인 패턴을 적용합니다.
외부 동작은 변경하지 않고 직접 코드를 수정합니다.이렇게 하면 “이 코드에서 문제를 찾아줘”는 Reviewer에게, “이 코드를 구조적으로 개선해줘”는 Refactor에게 정확히 라우팅됩니다. description 작성 후 반드시 다른 에이전트의 description과 교차 비교하세요. 겹치는 키워드가 하나라도 있으면 오케스트레이션이 흔들립니다.
오케스트레이션 디버깅 — 위임이 잘못될 때
자동 위임이 원하는 대로 동작하지 않을 때 확인할 체크리스트입니다.
체크리스트
- description을 다시 읽어보세요: Primary의 관점에서 읽습니다. 사용자의 요청과 description이 매칭되는 키워드가 있는지 확인합니다.
- 다른 에이전트와 겹치는 표현이 있는지 확인하세요: 모든 에이전트의 description을 한 화면에 놓고 비교합니다.
- @멘션으로 수동 확인합니다: @멘션으로 직접 호출해서 해당 에이전트가 작업을 올바르게 수행하는지 먼저 확인합니다. 위임 문제인지 에이전트 자체 문제인지 구분합니다.
- 요청의 표현을 바꿔봅니다: “테스트를 작성해줘” 대신 “단위 테스트를 만들어줘”로 바꿔서 트리거 키워드 매칭을 확인합니다.
- description의 첫 문장을 강화합니다: LLM은 첫 문장에 가중치를 더 두는 경향이 있습니다. 가장 핵심적인 역할 서술을 첫 문장에 배치합니다.
디버깅 예시
# 문제: "이 API의 인증 로직을 확인해줘"에 Reviewer가 호출됨 (SecurityAuditor를 원했음)
# 원인 분석: "확인"이라는 키워드가 Reviewer의 "검토" 역할과 매칭
# SecurityAuditor의 description에는 "인증" 키워드가 있지만,
# Reviewer의 description에 "확인", "검토"가 먼저 매칭
# 해결: SecurityAuditor의 description 첫 문장에 "인증" 강조
description: |
인증·인가 로직과 보안 취약점을 전문적으로 점검하고 감사합니다.
...실전 오케스트레이션 흐름 — opencode.json 통합 설정 완전판
지금까지의 모든 내용을 하나의 opencode.json으로 통합한 완전판입니다. .opencode/agents/ 파일들과 함께 사용합니다.
{
"default_agent": "build",
"model": {
"primary": "anthropic/claude-opus-4-6",
"secondary": "anthropic/claude-sonnet-4-6"
},
"agent": {
"build": {
"description": "코드 구현과 기능 개발을 담당합니다. 새 기능 추가, 버그 수정, 코드 작성 요청 시 직접 처리합니다. 리뷰·테스트·보안·리팩토링은 전문 에이전트에게 위임합니다.",
"model": "anthropic/claude-opus-4-6",
"permission": {
"allow": [
"Read",
"Glob",
"Grep",
"Explore",
"Edit",
"Write",
"Bash"
],
"deny": [
"Bash(rm -rf*)",
"Bash(git push --force*)"
]
}
}
},
"permission": {
"deny": [
"Bash(curl*)",
"Bash(wget*)"
]
}
}이 설정에서 눈여겨볼 점입니다.
- Build(Primary)의 description에 위임 힌트: “리뷰·테스트·보안·리팩토링은 전문 에이전트에게 위임합니다”라는 문구가 Primary에게 “이 작업들은 나 대신 다른 에이전트에게 넘기라”는 신호를 줍니다.
- 글로벌 permission.deny: 모든 에이전트에게 공통으로 적용되는 차단 규칙입니다. 외부 네트워크 호출을 기본 차단합니다.
- Subagent들은 .opencode/agents/ 에 분리: JSON이 복잡해지지 않고, 각 에이전트의 시스템 프롬프트를 자유롭게 작성할 수 있습니다.
전체 프로젝트 구조를 최종 확인합니다.
my-project/
├── opencode.json # Primary(Build) + 글로벌 설정
├── .opencode/
│ └── agents/
│ ├── reviewer.md # Read-only 코드 리뷰어
│ ├── tester.md # 테스트 작성 전문가
│ ├── refactor.md # 리팩토링 전문가
│ └── security-auditor.md # 보안 감사관
├── src/ # 소스 코드
├── tests/ # 테스트 코드
└── docs/ # 문서이 구조를 그대로 프로젝트에 복사하면 opencode 서브에이전트 오케스트레이션이 바로 동작합니다. 각 파일의 전체 내용은 위에서 제공한 코드 블록을 사용하세요.
팀 운영의 현실적 조언
마지막으로, 에이전트 팀을 실전에 투입할 때 현실적으로 도움이 되는 조언 세 가지입니다.
조언 1: 모든 작업에 팀을 동원하지 마세요
간단한 버그 수정이나 한 줄 변경에 Reviewer → SecurityAuditor → Tester 풀 파이프라인을 돌리면 과잉입니다. 변경의 크기와 위험도에 비례해서 팀을 활용합니다. 5줄 수정에는 Build 혼자면 충분하고, 새 API 엔드포인트 추가에는 팀을 동원하는 식입니다.
조언 2: 에이전트의 피드백을 누적하세요
Reviewer가 같은 유형의 문제를 반복적으로 지적한다면, 그건 프로젝트의 코딩 컨벤션에 반영해야 할 패턴입니다. 에이전트의 반복 피드백을 관찰해서 opencode의 AGENTS.md나 프로젝트 가이드라인에 규칙으로 추가하면, 이후에는 Build(Primary)가 처음부터 올바르게 코드를 작성하게 됩니다. 7일차에서 다룰 컨텍스트 엔지니어링의 핵심입니다.
조언 3: 실패를 학습 기회로
자동 위임이 엉뚱한 에이전트를 골랐다면, 그건 description을 개선할 기회입니다. SecurityAuditor가 너무 많은 위양성을 보고한다면, 체크리스트를 정교화할 기회입니다. Tester가 프레임워크 컨벤션에 맞지 않는 테스트를 생성했다면, 시스템 프롬프트에 프레임워크 가이드를 보강할 기회입니다. 에이전트 팀은 한 번에 완성되지 않습니다. 쓰면서 다듬는 반복이 핵심입니다.
정리 — 오늘 만든 것과 내일 이어갈 것
오늘 만든 것을 정리합니다.
- 오케스트레이션 구조: 1 Primary + N Subagent 허브 앤 스포크 모델을 이해하고, 자동 위임과 수동 호출의 차이를 파악했습니다.
- 4인 전문가 팀: Reviewer(리뷰) · Tester(테스트) · Refactor(리팩토링) · SecurityAuditor(보안) 에이전트를 실제
.opencode/agents/파일로 완성했습니다. - 역할 분담 매트릭스: 각 역할의 책임 · 트리거 키워드 · 권한 · 모델 티어를 체계적으로 정리했습니다.
- 위임 전략: description 튜닝 팁과 디버깅 체크리스트로 오케스트레이션 정확도를 높이는 방법을 확보했습니다.
오늘 에이전트 팀을 편성했다면, 내일은 그 팀이 최고의 성능을 발휘하도록 무대를 세팅합니다. 7일차에서는 컨텍스트 엔지니어링 — AGENTS.md 심화, MVI(Minimum Viable Info) 원칙, 로컬→글로벌 컨텍스트 폴백 전략을 다룹니다. 오늘 만든 4인 팀이 프로젝트의 맥락을 정확히 이해하고, 한 번에 올바른 코드를 생산하도록 만드는 핵심 기술입니다.
◀ 이전 5화 (다음 차수는 아직 게시되지 않았습니다)
자주 묻는 질문
opencode 서브에이전트 오케스트레이션에서 허브 앤 스포크 모델이란 무엇인가요?
허브 앤 스포크 모델은 중앙의 Primary 에이전트가 허브(지휘관) 역할을 하고, 여러 Subagent가 스포크(전문가 팀원)로 뻗어 나가는 구조입니다. Anthropic의 에이전트 설계 가이드에서 말하는 “orchestrator-workers” 패턴과 같은 계열로, Primary가 작업을 판단하고 적절한 Subagent에게 위임하는 방식으로 동작합니다.
opencode에서 서브에이전트 자동 위임과 @멘션 수동 호출의 차이점은 무엇인가요?
자동 위임은 description을 기반으로 Primary 에이전트가 작업 내용을 판단해 적절한 Subagent에게 자동으로 작업을 넘기는 방식이고, @멘션 수동 호출은 사용자가 직접 특정 Subagent를 지정하여 호출하는 방식입니다. 두 메커니즘은 작동 원리와 장단점, 사용 시점이 다르며, 상황에 따라 적절한 방식을 선택해야 합니다.
하나의 에이전트에 여러 역할을 맡기면 안 되는 이유는 무엇인가요?
하나의 에이전트에 리뷰, 테스트, 보안 감사, 리팩토링 등 여러 역할을 동시에 부여하면 세 가지 문제가 발생합니다. 첫째 역할 충돌로 문제 발견과 해결 관점이 뒤섞이고, 둘째 각 역할에 필요한 지침을 모두 담으면 컨텍스트 윈도우가 낭비되며, 셋째 읽기 전용이어야 할 리뷰어에게 파일 쓰기 권한까지 줘야 하는 권한의 모순이 생깁니다. 이 문제를 해결하기 위해 역할별로 전문화된 에이전트를 분리하고 팀으로 엮는 오케스트레이션 구조를 사용합니다.
[…] 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기 (총 12화 중 7화)◀ 이전 6화 (다음 차수는 아직 게시되지 […]