the-open-engine/zeroshot

zeroshot CLI

🎉 v5.4 새로운 기능: 이제 OpenCode CLI를 지원합니다! Claude, Codex, Gemini 또는 OpenCode를 AI 제공자로 사용할 수 있습니다. 또한 GitHub, GitLab, Jira, Azure DevOps를 이슈 백엔드로 지원합니다. 제공자 및 멀티 플랫폼 이슈 지원을 참조하세요.

<p align="center"> <code>npm install -g @the-open-engine/zeroshot</code> </p>

<p align="center"> <img src="./docs/assets/zeroshot-demo.gif" alt="데모" width="700"> <br> <em>데모 (100배속, 90분 실행, 승인까지 5회 반복)</em> </p>

!플랫폼: Linux | macOS

Zeroshot은 오픈소스 AI 코딩 에이전트 오케스트레이션 CLI로, 멀티 에이전트 워크플로우를 실행하여 코드 변경을 자율적으로 구현, 리뷰, 테스트 및 검증합니다.

플래너, 구현자, 그리고 독립적인 검증자를 격리된 환경에서 실행하며, 변경 사항이 검증되거나 실행 가능하고 재현 가능한 실패와 함께 거부될 때까지 반복합니다.

정확성이 속도보다 중요한 작업을 위해 설계되었습니다.

작동 방식

• 계획: 작업을 구체적인 승인 기준으로 변환
• 구현: 격리된 작업 공간(로컬, worktree 또는 Docker)에서 변경 수행
• 검증: 독립적인 검증자로 자동화된 검사 실행
• 반복: 검증될 때까지 반복하거나, 실행 가능한 실패 반환
• 재개: 충돌 안전 상태를 SQLite에 저장하여 복구 가능

빠른 시작

zeroshot run 123                    # GitHub 이슈 번호
zeroshot run feature.md             # Markdown 파일
zeroshot run "Add dark mode"        # 인라인 텍스트

또는 복잡한 작업을 인라인으로 설명:

zeroshot run "Add optimistic locking with automatic retry: when updating a user,
retry with exponential backoff up to 3 times, merge non-conflicting field changes,
and surface conflicts with details. Handle the ABA problem where version goes A->B->A."

단일 AI 에이전트만 사용하지 않는 이유

	접근 방식	코드 작성	테스트 실행	블라인드 검증	검증될 때까지 반복
	채팅 기반 어시스턴트	✅	⚠️	❌	❌
	단일 코딩 에이전트	✅	⚠️	❌	⚠️
	Zeroshot (멀티 에이전트)	✅	✅	✅	✅

사용 사례

• 자율 AI 코드 리팩토링
• AI 기반 풀 리퀘스트 자동화
• 검증이 포함된 자동 버그 수정
• 소프트웨어 엔지니어링을 위한 멀티 에이전트 코드 생성
• 블라인드 검증을 통한 에이전틱 코딩 워크플로우

대상 사용자

• 정확성과 재현성을 중시하는 시니어 엔지니어
• PR 워크플로우 및 코드 리뷰 게이트를 자동화하는 팀
• 에이전틱 워크플로우를 표준화하는 인프라/플랫폼 팀
• 이슈 백로그를 처리하는 오픈소스 관리자
• 분위기보다 검증을 원하는 AI 파워 유저

설치 및 요구 사항

플랫폼: Linux, macOS. Windows(네이티브/WSL)는 안정성 및 멀티 제공자 정확성을 강화하는 동안 연기되었습니다.

npm install -g @the-open-engine/zeroshot

필요 사항: Node 18+, 최소 하나의 제공자 CLI(Claude Code, Codex, Gemini, Opencode).

# 하나 이상의 제공자 설치
npm i -g @anthropic-ai/claude-code
npm i -g @openai/codex
npm i -g @google/gemini-cli
# Opencode: https://opencode.ai 참조

# 제공자 CLI 인증
claude login        # Claude
codex login         # Codex
gemini auth login   # Gemini
opencode auth login # Opencode

# GitHub 인증 (이슈 번호용)
gh auth login

제공자

Zeroshot은 제공자 CLI를 호출합니다. 기본값을 선택하고 실행 시 재정의할 수 있습니다:

zeroshot providers
zeroshot providers set-default codex
zeroshot run 123 --provider gemini

설정, 모델 레벨 및 Docker 마운트는 docs/providers.md를 참조하세요. 엄격한 TypeScript 제공자 헬퍼, zeroshot-agent-provider JSON 실행 가능 계약 및 Orchestra와의 경계는 docs/provider-cli-helper.md를 참조하세요.

여러 에이전트를 사용하는 이유

단일 에이전트 세션은 성능이 저하됩니다. 컨텍스트가 수천 개의 토큰 아래에 묻힙니다. 모델은 "완료"보다 "정확"을 최적화합니다.

Zeroshot은 서로의 작업을 확인하는 격리된 에이전트로 이 문제를 해결합니다. 검증자는 자신이 작성하지 않은 코드에 대해 거짓말을 할 수 없습니다. 검사에 실패하면 실제로 작동할 때까지 수정하고 재시도합니다.

차별점

• 블라인드 검증 - 검증자는 작업자의 컨텍스트나 코드 기록을 볼 수 없음
• 반복 가능한 워크플로우 - 작업 복잡성에 따라 에이전트 수와 모델 선택 결정
• 수락/거부 루프 - 거부에는 모호한 불만이 아닌 실행 가능한 결과 포함
• 충돌 복구 - 모든 상태를 SQLite에 저장; 언제든지 재개 가능
• 격리 모드 - 없음, git worktree 또는 Docker 컨테이너
• 비용 제어 - 모델 상한선으로 API 지출 폭주 방지

필수 핸드오프 품질 게이트

Zeroshot은 --pr 및 --ship 흐름을 위한 도구 중립적인 핸드오프 계약을 소유합니다. 어떤 도구가 게이트를 생성했는지 알지 못합니다. 저장소는 필수 게이트를 구성하고, 검증자는 일치하는 qualityGates 증거를 게시하며, git-pusher 트리거는 IMPLEMENTATION_READY 이후 각 구성된 게이트에 새로운 통과 증거가 있을 때까지 깨어나기를 거부합니다.

게이트 구성은 실행 옵션 또는 저장소 설정에서 올 수 있습니다:

{
  "ship": {
    "requiredQualityGates": [
      {
        "id": "repo-quality",
        "scope": "repo",
        "description": "Repository quality gate",
        "command": "repo-quality --changed --json"
      }
    ]
  }
}

id와 선택적 scope는 일반적입니다. 저장소는 repo-quality를 로컬 품질 명령, CI 상태 명령 또는 Zeroshot 외부의 다른 품질 명령에 바인딩할 수 있습니다. 검증자는 구성된 게이트 목록을 받고 status, completedAt 또는 timestamp, evidence.command, evidence.exitCode, 문자열 evidence.output을 포함하는 항목을 게시해야 합니다. 실패하거나 사용할 수 없는 명령은 게이트 상태 FAIL 또는 UNAVAILABLE과 함께 approved: false를 의미합니다.

푸셔는 구성된 게이트가 누락되었거나, 실패했거나, 사용할 수 없거나, 오래되었거나, IMPLEMENTATION_READY보다 오래되었거나, 사용 가능한 증거가 없는 경우 커밋, 푸시, PR 생성 또는 병합 전에 실패-폐쇄합니다. requiredQualityGates가 구성되지 않은 경우 Zeroshot은 기존 검증자 합의 동작을 유지합니다.

Cmdproof 명령 재사용

클러스터는 cmdproof를 사용하여 비용이 많이 드는 정확한 명령을 작업자와 검증자 간에 재사용 가능하게 만들 수 있습니다. Zeroshot은 임의의 셸 명령을 가로채지 않습니다. 에이전트에게 구성된 명령 증명을 위한 클러스터 범위 헬퍼를 제공합니다.

이슈 본문은 실행당 옵트인할 수 있습니다:

[ { "id": "repo-ci", "profile": "ci-equivalent", "scope": "repo", "description": "Repository local CI-equivalent gate", "command": "bash./scripts/ci/run-local-ci-equivalent.sh" } ]

저장소는 .zeroshot/settings.json에서 동일한 명령을 구성할 수도 있습니다:

{
  "ship": {
    "commandProofs": [
      {
        "id": "repo-ci",
        "profile": "ci-equivalent",
        "scope": "repo",
        "description": "Repository local CI-equivalent gate",
        "command": "bash./scripts/ci/run-local-ci-equivalent.sh"
      }
    ]
  }
}

에이전트는 다음을 사용하라는 지침을 받습니다:

zeroshot cmdproof check repo-ci

헬퍼는 ~/.zeroshot/cmdproof/<cluster-id>/ 아래의 클러스터 로컬 캐시와 신뢰할 수 있는 에이전트 키를 사용하며, 먼저 cmdproof verify를 실행하고, 미스 시 cmdproof prove --fallback run으로 대체합니다. --ship 흐름에서 구성된 명령 증명은 필수 핸드오프 품질 게이트이기도 합니다.

Zeroshot 사용 시기

Zeroshot은 작업에 명확한 승인 기준이 있을 때 가장 잘 작동합니다.

	시나리오	사용	이유
	속도 제한 추가 (슬라이딩 윈도우, IP당, 429)	예	명확한 요구 사항
	인증을 JWT로 리팩토링	예	정의된 최종 상태
	로그인 버그 수정	예	성공 측정 가능
	2410 린트 위반 수정	예	명확한 완료 기준
	앱을 더 빠르게 만들기	아니요	먼저 탐색 필요
	코드베이스 개선	아니요	승인 기준 없음
	불안정한 테스트 파악	아니요	탐색적

경험 법칙: "완료"가 무엇을 의미하는지 설명할 수 없으면 검증자도 검증할 수 없습니다.

명령 개요

# 실행
zeroshot run 123                      # GitHub 이슈
zeroshot run feature.md               # Markdown 파일
zeroshot run "Add dark mode"          # 인라인 텍스트

# 격리
zeroshot run 123 --worktree       # git worktree
zeroshot run 123 --docker         # 컨테이너

# 자동화 (--ship은 --pr을 의미하고, --pr은 --worktree를 의미)
zeroshot run 123 --pr             # worktree + PR 생성
zeroshot run 123 --ship           # PR + 승인 시 자동 병합

# 백그라운드 모드
zeroshot run 123 -d
zeroshot run 123 --ship -d

# 제어
zeroshot list
zeroshot status <id>
zeroshot logs <id> -f
zeroshot resume <id>
zeroshot stop <id>
zeroshot kill <id>

# 제공자
zeroshot providers
zeroshot providers set-default codex

# 에이전트 라이브러리
zeroshot agents list
zeroshot agents show <name>

# 유지보수
zeroshot clean
zeroshot purge

멀티 플랫폼 이슈 지원

Zeroshot은 GitHub, GitLab, Jira, Azure DevOps와 함께 작동합니다. 이슈 URL 또는 키를 붙여넣기만 하면 됩니다. git 저장소에서 작업할 때 zeroshot은 git 원격 URL에서 이슈 제공자를 자동으로 감지합니다. 구성이 필요 없습니다!

# GitHub
zeroshot run 123
zeroshot run https://github.com/org/repo/issues/123

# GitLab (클라우드 및 자체 호스팅)
zeroshot run https://gitlab.com/org/repo/-/issues/456
zeroshot run https://gitlab.mycompany.com/org/repo/-/issues/789

# Jira
zeroshot run PROJ-789
zeroshot run https://company.atlassian.net/browse/PROJ-789

# Azure DevOps
zeroshot run https://dev.azure.com/org/project/_workitems/edit/999

필요 사항: 사용하는 플랫폼에 대한 CLI 도구(gh, glab, jira 또는 az). 설정 및 자체 호스팅 인스턴스는 issue-providers README를 참조하세요.

--pr 모드 중요 사항: 대상 저장소 디렉토리에서 zeroshot을 실행하세요. PR은 현재 디렉토리의 git 원격에 생성됩니다. 다른 저장소에서 실행하면 zeroshot이 경고하고 "Closes #X" 참조를 건너뜁니다(PR은 계속 생성되지만 이슈를 자동으로 닫지 않습니다).

아키텍처

Zeroshot은 스마트 기본값을 가진 메시지 기반 조정 계층입니다.

• 컨덕터는 작업을 복잡성과 유형별로 분류합니다.
• 워크플로우 템플릿이 에이전트와 검증자를 선택합니다.
• 에이전트는 결과를 SQLite 원장에 게시합니다.
• 검증자는 특정 결과와 함께 승인 또는 거부합니다.
• 거부는 수정을 위해 작업자에게 다시 라우팅됩니다.

                                ┌─────────────────┐
                                │      TASK       │
                                └────────┬────────┘
                                         │
                                         ▼
                ┌────────────────────────────────────────────┐
                │                 CONDUCTOR                  │
                │     Complexity × TaskType → Workflow       │
                └────────────────────────┬───────────────────┘
                                         │
           ┌─────────────────────────────┼─────────────────────────────┐
           │                             │                             │
           ▼                             ▼                             ▼
     ┌───────────┐                ┌───────────┐                ┌───────────┐
     │  TRIVIAL  │                │  SIMPLE   │                │ STANDARD+ │