zeroshot 소개
zeroshot은 Anthropic의 Claude Code를 위한 자율 엔지니어링 팀(Autonomous Engineering Teams)을 구성해주는 오픈소스 CLI 도구입니다. "2024년이 LLM의 해였고, 2025년이 에이전트의 해였다면, 2026년은 **에이전트 클러스터(Agent Clusters)**의 해가 될 것"이라는 비전 아래, 단일 AI 에이전트가 갖는 한계를 극복하기 위해 개발되었습니다.
AI 에이전트는 매우 유능하지만, 혼자서 모든 작업을 수행할 때 종종 문제가 발생합니다. 예를 들어, 실제로는 테스트를 실행하지 않았으면서 "테스트 통과"라고 보고하거나, 구현이 60%만 완료되었는데도 "완료"라고 선언하기도 합니다. 또한 긴 작업을 수행할 때 문맥(Context)을 잃거나 주의력이 흐트러져 코딩 가이드라인을 무시하고 안티 패턴(Anti-pattern)을 도입하는 경우도 있습니다.
zeroshot은 이러한 문제를 해결하기 위해 여러 개의 격리된 에이전트(Multiple Isolated Agents) 를 투입합니다. 코드를 작성하는 작업자 에이전트(Worker)와 이를 검증하는 검증자 에이전트(Validator)를 분리하여, 검증자 에이전트(Validator)가 실제 테스트를 수행하고 오류를 잡아냅니다. 또한 검증자가 승인할 때까지 '구현-검증-수정'의 과정을 반복(Fix-loop)함으로써, 사용자는 단순히 GitHub 이슈를 지정해두고 자리를 비운 뒤, 나중에 검증된 프로덕션 준비(Production-ready) 상태의 PR(Pull Request)을 받아볼 수 있습니다.
zeroshot은 단일 에이전트(Single Agent) 방식의 한계를 '에이전트 클러스터(Agent Cluster)' 방식으로 해결합니다:
| 특징 | Single Agent (기존 방식) | Agent Cluster (zeroshot) |
|---|---|---|
| 작업 방식 | 한 명의 에이전트가 계획, 코딩, 테스트를 모두 수행 | 역할이 분담된 여러 에이전트(작업자, 검증자, 계획자)가 협업 |
| 신뢰성 | "테스트 통과"라고 거짓 보고할 가능성 있음 | 검증자(Validator)가 별도로 존재하여 거짓 보고 불가능 |
| 주의력 | 작업이 길어지면 문맥(Context) 저하 및 주의력 분산 | 각 에이전트가 격리된 환경에서 자신의 역할에만 집중 |
| 결과물 | 초안 수준의 코드 (주로 사람이 다시 검토 필요) | 반복적인 검증(Iteration)을 거친 프로덕션 수준의 코드 |
| 복잡도 대응 | 복잡한 요구사항에서 안티 패턴 발생 쉬움 | 복잡도에 따라 검증자 수를 늘려(최대 5명 등) 철저히 검수 |
zeroshot의 주요 기능
지휘자(Conductor) 및 복잡도 기반 워크플로우
zeroshot은 모든 작업에 똑같은 리소스를 투입하지 않습니다. Conductor 시스템이 작업의 복잡도를 분석하여 적절한 팀(워크플로우)을 동적으로 구성합니다. 즉, 작업의 난이도에 따라 투입되는 에이전트의 수와 역할이 달라집니다.
| 작업 난이도 (Complexity) | 예시 | 팀 구성 (Agents) | 모델 등급 (Model Ceiling) | 검증 수준 |
|---|---|---|---|---|
| TRIVIAL (사소함) | 오타 수정 | 1 Agent | Haiku | 검증 없음 |
| SIMPLE (단순함) | 다크 모드 추가 | 2 Agents (Worker + 1 Validator) | Sonnet | 일반 검증 |
| STANDARD (표준) | 인증 리팩토링 | 4 Agents (Planner + Worker + 2 Validators) | Sonnet | 요구사항 및 코드 검증 |
| CRITICAL (중요) | 결제 흐름 구현 | 7 Agents (Planner + Worker + 5 Validators) | Opus (Planner) | 보안, QA, 적대적 테스팅 |
적대적 검증 및 반복 수정 (Adversarial Validation Loop)
단일 에이전트는 스스로 작성한 코드에 관대합니다. 하지만 zeroshot의 검증자(Validator)는 코드를 작성하지 않았기 때문에 객관적이고 적대적입니다.
실제 데모 사례에서, "낙관적 락(Optimistic Locking) 및 재시도 로직 구현" 요청 시, 단일 에이전트는 1회 만에 끝냈다고 주장하지만, zeroshot 클러스터는 5번의 반복(Iteration) 과정을 거쳤습니다. 이는 zeroshot의 검증자(Validator)들이 동시성 이슈(Race Condition), ABA 문제, 백오프 타이밍 등을 지적하며 거부(Reject)했기 때문입니다. 최종적으로 zeoshot 클러스터는 48개의 테스트 케이스와 91% 이상의 커버리지를 달성한 후에야 PR을 생성했습니다.
프레임워크 모드 (Custom Clusters)
zeroshot은 사용자가 자신만의 에이전트 토폴로지(Topology)를 정의하여 커스텀 워크플로우를 만들 수 있도록 지원합니다. 사용자는 필요에 따라 메시지 기반(message-driven)으로 동작하는 커스텀 워크플로우를 구성할 수 있습니다:
-
전문가 패널(Expert Panels): 병렬로 작업하는 전문가 에이전트들이 작업 후, 취합자가 결과물을 취합하여 최종 결정
-
단계별 관문(Staged Gates): 순차적인 검증자들이 각자 거부권(Veto Power) 행사하며 더 나은 코드를 작성할 때까지 반복
-
동적 스폰(Dynamic Spawning): 실행 도중, 필요에 따라 새로운 에이전트를 추가
Claude Code를 통한 설정 자동화
사용자는 복잡한 JSON 설정 파일을 직접 작성할 필요가 없습니다. Claude Code에게 자연어로 요청하여 클러스터 설정을 생성할 수 있습니다. 다음은 요청 예시입니다:
"보안이 중요한 기능을 위해 4명의 검증자(보안, 성능, 개인정보, 코드 리뷰)가 모두 승인해야 병합하는 설정을 만들어줘."
zeroshot 동작 개요
다음은 zeroshot에 작업이 입력되었을 때의 동작 개요를 그린 다이어그램입니다:
┌─────────────────┐
│ TASK │
└────────┬────────┘
│
▼
┌────────────────────────────────────────────┐
│ CONDUCTOR │
│ Complexity × TaskType → Workflow │
└────────────────────────┬───────────────────┘
│
┌─────────────────────────────┼─────────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ TRIVIAL │ │ SIMPLE │ │ STANDARD+ │
│ 1 agent │──────────▶ │ worker │ │ planner │
│ (haiku) │ COMPLETE │ + 1 valid.│ │ + worker │
│ no valid. │ └─────┬─────┘ │ + 3-5 val.│
└───────────┘ │ └─────┬─────┘
▼ │
┌─────────────┐ ▼
┌──▶│ WORKER │ ┌─────────────┐
│ └──────┬──────┘ │ PLANNER │
│ │ └──────┬──────┘
│ ▼ │
│ ┌─────────────────────┐ ▼
│ │ ✓ validator │ ┌─────────────┐
│ │ (generic check) │ ┌──▶│ WORKER │
│ └──────────┬──────────┘ │ └──────┬──────┘
│ REJECT │ ALL OK │ │
└──────────────┘ │ │ ▼
│ │ ┌──────────────────────┐
│ │ │ ✓ requirements │
│ │ │ ✓ code (STANDARD+) │
│ │ │ ✓ security (CRIT) │
│ │ │ ✓ tester (CRIT) │
│ │ │ ✓ adversarial │
│ │ │ (real execution) │
│ │ └──────────┬───────────┘
│ │ REJECT │ ALL OK
│ └──────────────┘ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ COMPLETE │
└─────────────────────────────────────────────────────────────────────────────┘
zeroshot 설치
zeroshot은 Node.js 환경에서 실행되며, Claude Code CLI와 GitHub CLI 연동이 필수입니다.
먼저, 다음과 같은 사전 환경이 구성되어 있어야 합니다:
- Node.js: v18 이상
- Claude Code CLI: 설치 및 로그인 필요 (
npm i -g @anthropic-ai/claude-code) - GitHub CLI: 설치 및 로그인 필요 (
gh auth login)
zeroshot 설치는 다음과 같이 npm 명령어로 가능합니다:
npm install -g @covibes/zeroshot
설치 후에는 Claude Code와 GitHub CLI 인증 과정을 거쳐 사용할 수 있습니다. 인증은 최초 1회만 수행합니다:
# Claude Code 인증
claude auth login
# GitHub 인증
gh auth login
zeroshot 기본 사용법
zeroshot이 해결해야 하는 GItHub 이슈 번호를 입력하거나, 터미널에서 직접 프롬프트를 입력하여 작업을 지시할 수 있습니다:
권장하는 방법은 GitHub 이슈 번호로 실행하는 것으로, 이미 작성된 GitHub 이슈가 있다면 번호만 입력하면 됩니다. 예를 들어, 다음과 같이 수행할 수 있습니다.
zeroshot 123
GitHub 이슈가 없더라도, 터미널에서 직접 프롬프트를 입력하여 바로 작업을 지시할 수 있습니다. 다음은 실행 예시입니다:
zeroshot "사용자 업데이트 시 버전 번호를 이용한 낙관적 락을 추가하고, 충돌 시 3회까지 지수 백오프(exponential backoff)로 재시도하는 기능을 구현해줘. ABA 문제도 해결해야 해."
그 외에도 비용 관리를 위해 사용할 최대 모델 등급을 설정할 수 있습니다. 예를 들어, 아래와 같이 최대 등급을 Sonnet으로 지정하면 Opus 모델 사용을 방지할 수 있습니다:
zeroshot settings set maxModel sonnet
라이선스
zeroshot 프로젝트는 MIT 라이선스로 공개 및 배포 되고 있습니다.
zeroshot 프로젝트 GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 