covibes/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)에서 변경 수행
• 검증: 독립적인 검증자로 자동화된 검사 실행
• 반복: 검증될 때까지 반복하거나 실행 가능한 실패 반환
• 재개: 충돌 안전 상태를 유지하여 복구 가능

빠른 시작

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+ │
     └───────────┘                └───────────┘                └───────────┘