OpenCode Swarm

OpenCode Swarm은 OpenCode용 플러그인으로, 단일 AI 코딩 세션을 아키텍트가 이끄는 전문화된 핵심(core), 선택적(optional), 조건부(conditional) 에이전트 팀으로 변환합니다. /swarm agents를 실행하여 실시간 명단을 확인하세요. 이는 현재 플러그인 구성에서 생성됩니다. 한 에이전트는 코드를 작성하고, 다른 에이전트는 이를 검토하며, 또 다른 에이전트는 테스트를 작성하고 실행합니다. 또 다른 에이전트는 보안을 점검합니다. 모든 필수 게이트가 통과할 때까지 아무것도 배포되지 않습니다.

bunx opencode-swarm install

이 단일 명령은 패키지를 설치하고, OpenCode 플러그인으로 등록하며, 충돌하는 기본 에이전트를 비활성화하고, ~/.config/opencode/opencode-swarm.json에 편집 가능한 구성을 생성합니다. Bun >= 1.3.13 (bun --version으로 확인) 또는 npm 설치의 경우 Node.js >= 22.13이 필요합니다 (Node를 호스팅하는 사이드카는 내장된 node:sqlite를 사용합니다). 반드시 npm을 사용해야 하는 경우: npm install -g opencode-swarm && opencode-swarm install.

첫 실행 참고: 설치 프로그램은 플러그인을 등록하고, 전역 플러그인 구성을 작성하며, 누락된 경우 프로젝트 오버라이드를 생성하고, opencode.json에서 기본 explore 및 general 에이전트를 비활성화합니다. Swarm 아키텍트를 사용하지 않는 경우, Swarm 게이트, 검토자, 테스트 에이전트는 우회됩니다. OpenCode 에이전트 또는 모드 선택기를 열고 필요할 때 Swarm 아키텍트를 선택하세요.

Swarm을 사용하는 이유?

대부분의 AI 코딩 도구는 하나의 모델이 코드를 작성하게 하고, 그 동일한 모델에게 해당 코드가 좋은지 묻는 방식으로 작동합니다. 하지만 이는 너무 많은 것을 놓치고 있습니다. Swarm은 계획(planning), 구현(implementation), 검토(review), 테스트(testing), 문서화(documentation)를 전문화된 내부 역할로 분리하고 — 에이전트들이 스코프가 명확히 분리되지 않은 상태에서 코드베이스를 병렬로 변경하는 것을 막고(v8 병렬 레인, Epic 웨이브), 각 작업을 고립된 작업 트리(isolated worktree) 내에서 수행하도록 강제합니다.

주요 기능 (Key Features)

• 🏗️ 전문화된 코어, 선택적 및 조건부 에이전트 — 아키텍트(architect), 코더(coder), 리뷰어(reviewer), 테스트 엔지니어(test_engineer), 크리틱(critic), 크리틱 발견 검증기(critic_finding_validator), 탐험가(explorer), SME, 문서화 담당자(docs), 디자이너(designer), 크리틱 감독관(critic_oversight), 크리틱 사운딩 보드(critic_sounding_board), 크리틱 드리프트 검증기(critic_drift_verifier), 크리틱 환각 검증기(critic_hallucination_verifier), 큐레이터 초기화(curator_init), 큐레이터 단계(curator_phase), 평의회 일반론자(council_generalist), 평의회 회의적 전문가(council_skeptic), 평의회 도메인 전문가(council_domain_expert). 라이브 명단은 /swarm agents를 실행하여 확인하세요 — 이 목록이 진실의 원천이며, 이 리스트가 아닙니다.
• 🔒 게이티드 파이프라인 (Gated pipeline) — 리뷰어와 테스트 엔지니어의 승인 없이는 코드가 배포되지 않습니다.
• 🔎 독립 자동 검토 엔진 (Independent auto-review engine) — 신선한 읽기 전용 모델 세션에서 경계가 있는 전체 차이(bounded whole-diff) 검토, 구조화된 차이 기반 발견 사항(structured diff-anchored findings), 선택적 독립 검증, 기본값으로 자문하는 단계 검토(advisory-by-default phase review), 그리고 증거 기반의 옵트인 완료 게이트를 제공합니다. v7은 여전히 옵트인이며, v8의 기본값은 커밋된 30개 차이 비용 소진(committed 30-diff cost burn-in)에 고정됩니다.
• 🔍 DEEP_DIVE 프로토콜 (Protocol) — 전문화된 스킬을 통한 높은 엄격도의 온디맨드 읽기 전용 코드베이스 감사(read-only codebase audit).
• 🔬 외부 스킬 큐레이션 파이프라인 (External Skill Curation Pipeline) — 구성된 소스에서 외부 스킬 후보를 옵트인으로 발견, 격리, 평가 및 승격합니다 (기본적으로 비활성화됨; 설정 파일의 external_skills.curation_enabled: true를 통해 활성화).

7가지 도구(external_skill_discover, external_skill_list, external_skill_inspect, external_skill_promote, external_skill_reject, external_skill_delete, external_skill_revoke)를 포함합니다. 후보군은 평가 전에 3단계 게이트 검증 파이프라인을 거칩니다: 프롬프트 인젝션 스캔 (12개 정규식 패턴), 안전하지 않은 명령어 스캔 (25개 패턴), 그리고 출처 무결성 확인 (SHA-256, 타임스탬프, URL, 게시자 및 해시 검증).

• 🎯 거버넌스 스킬 최적화기(Governed Skill Optimizer) — 수동 활성화되는 단일 스킬 최적화기( /swarm skill-opt plan|run|status|diff|approve|reject|rollback|history)로, 허용된 SKILL.md 후보 하나를 결정론적 초안 → 연기(smoke) → 평가 기반 검증 → 수동 승인 → 원자적 활성화/롤백 과정을 거치도록 구동합니다. 경계가 설정되어 있고, 재시작 가능하며, 되돌릴 수 있으며, 소스/하우징/보안 표면을 변경할 수 없습니다. 기본적으로 비활성화되어 있습니다 (skill_opt.enabled: false); docs/skill-optimizer.md를 참조하십시오.
• 🌊 에픽 모드 (Epic Mode) (선택적 미리보기) — 하나의 계획은 하나의 에픽이 되며, 선언된 범위가 충돌하지 않는 병렬 작업 파도로 단계별로 실행됩니다. 위임 게이트는 활성 웨이브를 강제하며; Git 프로젝트에서 각 코더는 에픽 브랜치에 격리된 워크트리에서 작업하고, 이는 /swarm epic close를 통해 스테이징된 변경사항으로 스쿼시(squash)-적재됩니다. 태스크별 QA는 항상 실행되며, phase_complete 전에 단계 검토자 + 비평가 게이트(epic_phase_review)가 실행됩니다. 에픽은 에픽 전반에 걸친 파일별 쓰기 위험을 학습하고, 예측된 속도 향상과 함께 계획 재구성을 제안하며, 스코어카드를 보고합니다 (/swarm epic report). epic.mode.enabled: true로 활성화하십시오; docs/modes.md를 참조하십시오.
• 🔄 단계 완료 게이트(Phase completion gates) — 단계 완료 전에 완료 검증 및 드리프트 검증 게이트가 강제됩니다.
• 🔁 재개 가능한 세션(Resumable sessions) — 모든 상태는 .swarm/에 저장되며, 언제든지 어떤 프로젝트든 다시 시작할 수 있습니다.

🌐 13개 전체 언어 프로필 (TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, C/C++, C#, Ruby, Swift, Dart, PHP)을 지원하며, 20개의 문법에 걸친 tree-sitter 구문 유효성 검사를 제공합니다 (CSS, Bash, PowerShell, INI, Regex 추가 — 그리고 .tsx / .c 별칭 포함). 자세한 내용은 docs/adding-a-language.md를 참조하세요.
🛡️ 내장 보안 기능 — 작업별 SAST(정적 분석 보안 테스트), 비밀 정보 스캐닝, 의존성 감사
🔒 스코프 강제 적용 — 프로세스 간 지속성, TTL 만료 및 스코프 인식 파괴 명령 차단과 연계하여 쓰기 대상이 선언된 스코프와 일치하는지 검증합니다. 다중 파일 도구 호출을 통해 스코프 우회(scope bypass)를 방지하기 위해 단일 문자열 및 배열 기반 경로 인수(files[], paths[], targetFiles[])를 처리합니다.
📝 셸 쓰기 감지 — 실행 전에 POSIX/PowerShell/cmd 명령의 파일 쓰기를 감지하기 위한 정적 분석을 수행합니다 (리디렉션, 빌트인 명령어, 인플레이스 편집기, 네트워크 다운로드, 아카이브 추출, git 파괴 작업 포함)
🆓 무료 티어 — OpenCode Zen의 무료 모델 목록과 함께 작동합니다
⚙️ 완벽하게 구성 가능 — 모든 에이전트의 모델을 재정의하거나, 에이전트를 비활성화하거나, 가드레일을 조정할 수 있습니다.

Swarm 아키텍트는 모든 내부 에이전트를 자동으로 조정합니다. 사용자가 내부 역할을 수동으로 전환할 필요가 없습니다. 활성 OpenCode 에이전트가 Swarm 아키텍트가 아니면 플러그인 워크플로우는 우회됩니다.

셸 쓰기 감지 (Shell Write Detection)

Swarm은 실행 전에 파일 쓰기 작업을 감지하고 가로채기하기 위해 셸 명령어에 대한 포괄적인 정적 분석을 포함합니다.

셸 쓰기 감지 기능 (Shell Write Detection Features)

• POSIX 셸 감지 — bash-parser AST를 사용하여 다음을 정확하게 탐지합니다:

  • 리디렉션 연산자 (>, >>, >|, <<, <<-)
  • Here-documents 및 here-strings
  • 쓰기 효과 내장 명령어 (cp, mv, install, ln, truncate, dd)
  • 인플레이스 에디터 (sed -i, perl -i, awk -i)
  • 인터프리터 eval (python -c, node -e, bun -e, ruby -e, php -r)
  • 네트워크 다운로더 (curl -o, wget -O, scp)
  • 아카이브 추출 (tar -x, unzip, gunzip)
  • Git 파괴적 작업 (git clean -fd, git reset --hard)

• Windows 셸 감지 — PowerShell 및 cmd.exe에 대해 정규 표현식 휴리스틱을 사용합니다:

  • PowerShell cmdlet: Out-File, Set-Content, Add-Content, Copy-Item, Move-Item
  • cmd.exe 내장 명령어: copy, move, ren, del, rd, md
  • 리디렉션 연산자 (>, >>)

• 대화형 세션 거부 — 영구적이거나 무한한 세션을 생성하는 명령을 차단합니다:

  • POSIX: watch, screen, tmux new-session
  • PowerShell: Start-Process

• 크로스 프로세스 범위 강제 적용 — 선언된 범위는 다음을 포함하여 .swarm/scopes/scope-{taskId}.json에 영구 저장됩니다:

  • TTL 만료 (기본 24시간)
  • 심볼릭 링크 가드 (O_NOFOLLOW + realpath containment)
  • 스키마 버전 관리 및 fail-closed 검증
  • 범위 인식 파괴적 명령어 차단 — 재귀 삭제 패턴 (rm -rf, rmdir /s, del /s, Remove-Item -Recurse, rsync --delete)은 모든 대상 경로가 선언된 범위 내에 있지 않으면 차단됩니다 (코더 에이전트 전용)

보안 패턴

가드레일 시스템은 다음을 대상으로 하는 파괴적 셸 명령을 차단합니다:

• 시스템 경로 (/root, /etc, C:\Windows 등)
• 외부 대상을 가진 심볼릭 링크/정션 생성
• .swarm/ 디렉토리 내 파일 작업
• 포크 폭탄 및 무한 루프
• 디스크 지우기 및 랜섬웨어급 작업

실제로 발생하는 일

당신이 말합니다:

Build me a JWT auth system.

Swarm은 다음과 같이 작동합니다:

1. 추론할 수 없는 것만 명확히 합니다.
2. 코드베이스를 스캔하여 이미 존재하는 것을 이해합니다.
3. 필요할 때 도메인 전문가와 상담하고 그 지침을 캐싱합니다.
4. 단계별 구현 계획을 작성합니다.
5. 코딩을 시작하기 전에 해당 계획을 비평가 게이트(critic gate)를 통해 보냅니다.
6. QA 파이프라인을 통해 작업을 실행합니다 — 한 번에 하나씩, 또는 증명 가능한 파일 분할 작업 그룹(file-disjoint task groups)을 가진 계획의 경우 격리된 워크트리에서 동시에 (새로운 계획의 v8 기본값, #1674; 범위가 겹치거나 알 수 없는 경우 자동 폴백은 순차적 방식):

• 코더가 코드를 작성합니다.
• 자동화된 검사가 실행됩니다.
• 리뷰어가 정확성을 확인합니다.
• 테스트 엔지니어가 테스트를 작성하고 실행합니다.
• 아키텍트가 회귀 스윕(regression sweep)을 실행합니다.
• 실패 시 구조화된 피드백과 함께 되돌아갑니다.

Epic Mode가 활성화되면, epic_next_wave는 각 단계를 충돌 없는 작업 웨이브로 발행하며 (동일한 작업별 파이프라인이 모든 웨이브 내부에서 실행됨), epic_phase_review는 phase_complete 전에 전체 단계에 대해 리뷰어 + 비평가를 실행합니다.

7. 각 단계가 끝난 후, 문서와 회고록(retrospectives)이 업데이트됩니다.

모든 프로젝트 상태는 .swarm/에 저장됩니다 — 계획, 증거, 컨텍스트, 지식 및 텔레메트리입니다. 설계상 재개 가능합니다. 만약 .swarm/가 이미 존재하면, 아키텍트는 발견 과정을 반복하는 대신 재개(RESUME) → **실행(EXECUTE)**으로 바로 들어갑니다.

실행 모드 (Execution Modes)

Swarm은 두 가지 독립적인 모드 시스템을 가지고 있습니다:

세션 모드 (Session modes) — 슬래시 명령어로 세션별 토글이 가능합니다:

Full-Auto는 안전한 작업(읽기 전용 도구, 범위 내 쓰기, 안전 셸)을 결정론적으로 허용하고, 모든 모호하거나 위험도가 높은 작업(플러그인/빌드/가드레일 경로에 대한 쓰기, 네트워크, 의존성 변경, 계획/단계 변이, 서브 에이전트 위임)을 실행하기 전에 읽기 전용 critic_oversight 에이전트를 통해 라우팅함으로써 승인 마찰(approval friction)을 줄입니다. 거부 사항은 구조화된 신호로 에이전트에게 반환되어 안전한 경로를 선택할 수 있게 하며; 반복적인 거부 사항은 실행을 일시 중지시키고; 단계 완료에는 승인된 감독 기록(APPROVED oversight record)이 필요합니다. mode, permission_policy, denials, oversight 구성 키, 실패 폐쇄 의미론(fail-closed semantics), 그리고 일시 중지된 실행의 복구에 대해서는 docs/modes.md를 참조하십시오.