ZaxbyHub/opencode-swarm

Architect-centric agentic swarm plugin for OpenCode. Hub-and-spoke orchestration with SME consultation, code generation, and QA review.

OpenCode Swarm – AI 기반, 게이트형 코드 생성 파이프라인

무엇인가요 – OpenCode AI 코딩 플랫폼용 플러그인으로, 단일 AI 세션을 소규모 개발 팀으로 전환합니다. 이 플러그인은 전문 에이전트(아키텍트, 코더, 리뷰어, 테스트 엔지니어, 보안 비평가 등)의 라이브 로스터를 자동 생성하고, 코드 생성 워크플로우를 게이트형 파이프라인으로 실행하여 모든 필수 검사가 통과하기 전까지는 코드가 머지되지 않도록 합니다.

왜 중요한가요 – 대부분의 AI 코딩 도구는 한 모델이 코드를 작성한 후, 같은 모델에게 "코드가 좋은가요?"라고 묻는 방식입니다. Swarm은 역할을 분리합니다: 기획, 구현, 리뷰, 테스트, 보안 스캔, 문서화는 각각 전용의 읽기 전용 모델 인스턴스가 담당합니다. 이로써 "모델이 완료했다고 했지만 실제로 작동하지 않는다"는 신뢰 격차를 줄이고, 수동 전달 없이 프로덕션 수준의 가드레일을 제공합니다.

핵심 개념

개념	README에 설명된 내용
에이전트	플러그인 설정에서 생성되는 라이브 로스터 (`/swarm agents`). 핵심 에이전트로는 아키텍트, 코더, 리뷰어, test_engineer, 크리티크, 크리티크_오버사이트, SME, docs가 있으며, 디자이너, 다양한 크리티크, 큐레이터, 평의회 등 많은 선택적/조건적 에이전트가 있습니다.
게이트형 파이프라인	리뷰어 + 테스트 엔지니어 승인이 없으면 코드는 배포되지 않습니다. 각 단계마다 크리티크, 드리프트 검증기, 환각 검증기 등 추가 게이트를 활성화할 수 있습니다.
DEEP_DIVE 프로토콜	전용 에이전트를 사용해 전체 코드베이스를 온디맨드로 읽기 전용 감사합니다.
외부 기술 큐레이션	선택적 파이프라인으로, 정규표현식 기반 인젝션/안전하지 않은 명령어 스캔과 출처 검증을 통해 외부 "기술" 플러그인을 탐지, 격리, 검증한 후 승격 가능하게 합니다.
기술 최적화기	수동으로 단일 기술을 최적화하는 (`/swarm skill-opt …`) 기능으로, `SKILL.md` 후보를 초안 작성, 스모크 테스트, 검증, 원자적 활성화를 수행합니다.
단계 완료 게이트	각 단계는 완료 검증 및 드리프트 검증 게이트를 통과해야 아키텍트가 다음 단계로 이동할 수 있습니다.
재개 가능한 세션	모든 상태는 `.swarm/` 아래에 저장되며, 세션은 일시 중지 후 나중에 재개할 수 있습니다.
PR 모니터	선택적 GitHub PR 구독 기능으로, `gh` CLI를 통해 CI 상태를 페칭하고 결과를 AutomationEventBus에 전달합니다.
언어 지원	13개의 1급 언어 프로파일(TS/JS, Python, Go, Rust, Java, Kotlin, C/C++, C#, Ruby, Swift, Dart, PHP)과 20개 문법에 대한 tree-sitter 파싱을 지원합니다.
보안 가드레일	내장된 SAST, 시크릿 스캔, 종속성 감사, 정적 쉘 쓰기 감지(POSIX, PowerShell, cmd), 범위 강제, 파괴적 명령어 차단 기능이 있습니다.
실행 모드	세션 수준 모드(`Balanced`, `Turbo`, `Lean Turbo`, `Full-Auto`)는 안전성과 속도의 트레이드오프를 제공하며, 프로젝트 수준의 `execution_mode`(`strict`, `balanced`, `fast`)는 기본 훅을 설정합니다.

설치 및 첫 실행

# Bun ≥1.3.13 또는 Node ≥22.13 권장 단일 명령어 설치
bunx opencode-swarm install

설치 프로그램은 플러그인을 OpenCode에 등록하고, 내장된 explore 및 general 에이전트를 비활성화하며, ~/.config/opencode/opencode-swarm.json에 글로벌 설정을 작성하고, 프로젝트 오버라이드 스텁이 없으면 생성합니다.

npm을 선호하는 경우:

npm install -g opencode-swarm && opencode-swarm install

설치 후 OpenCode를 시작하고 에이전트 선택기에서 Swarm 아키텍트를 선택하거나(자동 선택된 기본값을 사용할 수도 있음), 첫 실행 시 `.swarm/` 디렉터리가 생성되고 설정이 채워집니다.

일반적인 워크플로우 (README 데모에 표시됨)

프롬프트 – 예: JWT 인증 헬퍼와 테스트를 만들어줘.
아키텍트가 단계별 구현 계획을 생성하고 크리티크 게이트를 통과시킵니다.
코더가 현재 작업의 코드를 작성합니다.
자동 검사 (SAST, 시크릿, 종속성 감사)가 실행됩니다.
리뷰어가 정확성과 보안을 검증합니다.
테스트 엔지니어가 테스트를 작성하고 실행합니다.
아키텍트가 리그레션 스위프를 실행합니다. 게이트가 실패하면 구조화된 피드백이 책임 있는 에이전트로 반환됩니다.
docs와 리트로스펙티브가 자동 업데이트됩니다.
모든 아티팩트(계획, 증거, 텔레메트리)는 .swarm/에 저장되어 나중에 검토 가능합니다 (/swarm evidence, /swarm status).

주요 명령어 (슬래시 스타일, OpenCode 세션 내에서 사용)

명령어	목적
`/swarm help`	모든 Swarm 명령어 목록을 표시합니다.
`/swarm agents`	등록된 에이전트의 라이브 로스터를 표시합니다.
`/swarm status`	현재 단계/작업 정보를 표시합니다.
`/swarm show-plan`	전체 구현 계획을 표시합니다(옵션으로 단계별 필터링 가능).
`/swarm evidence`	작업의 테스트, 리뷰, 보안 결과를 표시합니다.
`/swarm pr subscribe …`	GitHub PR에 대한 CI 피드백을 구독합니다.
`/swarm auto-proceed [on	off]`
`/swarm turbo [on	off]`,` /swarm full-auto [on
`/swarm reset --confirm`	모든 Swarm 상태를 삭제합니다.
`/swarm diagnose`	건강 상태 점검 및 버전 정보를 표시합니다.

설정

글로벌 설정은 ~/.config/opencode/opencode-swarm.json에 위치합니다.
프로젝트 수준 오버라이드는 .opencode/opencode-swarm.json에 배치 가능(옵트인).
중요한 토글에는 다음이 포함됩니다:
- external_skills.curation_enabled – 외부 기술 탐지 파이프라인을 활성화합니다.
- skill_opt.enabled – 단일 기술 최적화기를 활성화합니다.
- pr_monitor.enabled – GitHub PR 모니터링을 활성화합니다.
- execution_mode – 기본 보안 프로파일 설정(strict, balanced, fast). |

업데이트

OpenCode는 플러그인을 캐시하므로, 일반적인 재시작은 더 새로운 npm 버전을 가져오지 않습니다. 제공된 헬퍼를 사용하세요:

bunx opencode-swarm update   # 캐시만 갱신
# 또는
bunx opencode-swarm install  # 완전 재설치 (설정 재적용)

`/swarm diagnose`는 실행 중 및 최신 npm 버전을 보고합니다. 백그라운드 검사를 무시하려면 `version_check: false`를 설정하세요.

누구에게 적합한가요?

AI 코드 생성에 의존하지만 프로덕션 수준의 안전성(보안 리뷰, 테스트 커버리지, 감사 트레일)이 필요한 개발자.
코드 리뷰와 테스트 정책을 강제하면서도 "단일 프롬프트" 경험을 원하는 팀.
여러 언어를 아우르는 추적 가능하고 재개 가능한 AI 기반 개발 세션을 필요로 하는 조직.

결론

OpenCode Swarm는 실제 설치 가능한 플러그인으로, OpenCode AI 코딩 환경에 완전한 스택의 다중 에이전트 워크플로우를 추가합니다. 단일 모델을 조율된 팀으로 전환하고 게이트형 실행을 강제함으로써, AI 생성 코드가 프로덕션 사용에 충분히 신뢰할 수 있도록 하면서도, 설정 가능하고 언어에 독립적인 설계를 유지합니다.