다수의 AI 에이전트를 실행하는 대부분의 개발자는 다섯 번째 에이전트쯤에서 동일한 문제에 직면합니다. 한 터미널에서는 Claude Code가 백엔드 서비스를 재작성하고 있고, 다른 터미널에서는 Codex가 테스트를 생성하며, Cursor는 컴포넌트를 편집하고 있고, 확인하는 것을 잊어버린 세 개의 탭이 더 있을 수 있습니다. 아무도 다른 에이전트가 무엇을 하는지 모릅니다. 비용은 치솟고, 두 에이전트가 같은 작업을 중복해서 수행합니다. 한 에이전트는 명확한 목표를 받지 못해 여섯 시간 동안 실행되고도 쓸모 있는 결과물을 전혀 내놓지 못합니다.
Paperclip은 이 문제를 해결합니다. 이것은 흩어져 있는 AI 에이전트를 조직도, 할당된 역할, 작업 관리, 예산 제한 및 감사 로그를 갖춘 구조화된 회사로 변환하는 오픈소스 오케스트레이션 플랫폼입니다. 출시 3주 만에 GitHub 스타 35,000개 이상을 달성했는데, 이는 얼마나 많은 개발자들이 같은 좌절감을 느끼고 있었는지 보여줍니다.
이 글에서는 Paperclip을 설정하고, 첫 번째 에이전트 회사를 구성하며, 모든 터미널을 일일이 확인하지 않아도 작업이 실제로 완료되도록 실행하는 방법을 안내합니다.
Paperclip은 무엇이며 무엇이 아닌가
무언가를 설치하기 전에, 무엇을 얻게 될지 정확히 이해하세요.
Paperclip은 오케스트레이션 레이어입니다. 에이전트를 조정하고, 작업을 추적하며, 예산을 통제하고, 회사의 목표에 대한 맥락을 제공합니다. 에이전트를 구축하거나, AI 제공업체를 대체하거나, 채팅 인터페이스를 추가하지 않습니다.
Paperclip의 주요 기능은 다음과 같습니다:
- 에이전트에는 단순 프롬프트가 아닌 역할이 있습니다.
- 작업에는 열린 터미널이 아닌 소유자가 있습니다.
- 예산에는 단순 분위기가 아닌 명확한 한도가 있습니다.
- 모든 것은 감사 추적(audit trail)에 기록됩니다.
Paperclip은 Claude Code, OpenAI Codex, Cursor, Gemini CLI, 웹훅/하트비트 신호를 받을 수 있는 모든 에이전트와 함께 사용 가능합니다. 에이전트는 사용자가 가져오고, Paperclip이 회사를 운영합니다.
Paperclip이 아닌 것:
- 챗봇 UI
- n8n, Zapier 같은 드래그 앤 드롭 워크플로 빌더
- 에이전트 작성용 프레임워크
- 단일 에이전트 사용 사례
AI 에이전트 한 개만 가끔 실행한다면 과도합니다. 3개 이상의 에이전트를 동시 운영한다면 Paperclip이 바로 필요한 도구입니다.
Paperclip 설치
필수 조건: Node.js 20+, pnpm 9.15+
Paperclip은 내장 PostgreSQL 데이터베이스를 제공합니다. 외부 스토리지 설정 없이 바로 시작할 수 있습니다.
가장 빠른 시작:
npx paperclipai onboard --yes
이 명령은 CLI를 다운로드하고 온보딩을 실행하며, 3100번 포트에서 서버를 시작합니다.
http://127.0.0.1:3100에서 대시보드를 확인하세요.
소스 코드로 직접 실행하려면:
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev
Docker를 사용할 경우:
docker compose -f docker-compose.quickstart.yml up --build
디스크에 생성되는 파일 구조 예시:
~/.paperclip/instances/default/
config.json — 서버 및 스토리지 설정
db/ — 내장 PostgreSQL 데이터 파일
secrets/master.key — 암호화 키 (자동 생성)
logs/ — 서버 로그
data/storage/ — 파일 첨부
workspaces/<agent>/ — 에이전트별 작업 디렉토리
로컬 모드는 기본적으로 local_trusted 인증을 사용해 즉시 대시보드 접근이 가능합니다.
건강 검사:
paperclipai doctor
문제가 발견되면 자동 수리:
paperclipai doctor --repair
첫 회사 설정
Paperclip에서 "회사"는 에이전트, 작업, 목표, 예산을 위한 최상위 컨테이너입니다.
대시보드에서 새 회사를 만들고 미션 선언문을 입력하세요.
예시 미션:
"고객 주문 관리를 위한 REST API를 구축하고 유지보수합니다. 속도보다 정확성을 우선시합니다. 모든 공개 엔드포인트를 문서화합니다."
미션은 에이전트의 모든 결정에 대한 기준점이 됩니다.
첫 에이전트 추가
각 에이전트는 사용하는 AI 도구와 통신 방식을 정의하는 어댑터가 필요합니다.
기본 지원 어댑터:
| 에이전트 | 어댑터 유형 | 패키지 |
|---|---|---|
| Claude Code | claude_local |
@paperclipai/adapter-claude-local |
| OpenAI Codex | codex_local |
@paperclipai/adapter-codex-local |
| Gemini CLI | gemini_local |
@paperclipai/adapter-gemini-local |
| Cursor | cursor |
@paperclipai/adapter-cursor-local |
| HTTP 웹훅 | HTTP 어댑터 | 커스텀 엔드포인트 |
CLI로 Claude Code 에이전트 추가:
paperclipai agent local-cli "Backend Engineer" --company-id <your-company-id>
이 명령은 에이전트를 부트스트랩하고, ~/.claude/skills에 스킬 설치, API 자격증명 생성까지 자동화합니다.
Claude 에이전트 주요 설정 필드:
| 필드 | 설명 |
|---|---|
model |
사용할 Claude 모델 (예: claude-sonnet-4-6) |
cwd |
작업 디렉토리 (없으면 자동 생성) |
promptTemplate |
{{variable}} 치환 포함 시스템 프롬프트 |
maxTurnsPerRun |
하트비트당 최대 턴 수 (기본: 300) |
timeoutSec |
실행 제한 (0 = 제한 없음) |
역할별 모델 할당 실전 가이드:
- CEO/오케스트레이션: Sonnet (전략적 추론)
- 관리자: Haiku (라우팅/위임, 저렴함)
- 창의적/코딩 IC: Sonnet (출력 품질 중요)
- 정형화된 IC: Haiku (보일러플레이트/테스트 등)
모든 곳에 Sonnet을 쓰는 것보다 이 방식이 월 비용을 40~60% 절감합니다.
에이전트 조직 구조화
예시 조직도 (소프트웨어 프로젝트):
CEO (소네트)
├── CTO (하이쿠)
│ ├── 백엔드 엔지니어 (소네트)
│ ├── 프론트엔드 엔지니어 (소네트)
│ └── QA 엔지니어 (하이쿠)
└── 기술 문서 작성자 (하이쿠)
- CEO는 미션을 목표로 나누고 CTO에게 전달
- 엔지니어가 작업 수행, QA가 검증, 문서 담당자가 문서화
하트비트 간격 실전 권장값:
- 코딩 에이전트: 600초(10분)
- 주문형 에이전트: 86,400초(1일), 주문형 깨우기 시
- 최소 안전 간격: 30초(이하로 내리면 비용/스팸 위험)
에이전트는 지속적으로 실행되지 않고, 주기적으로 깨어나 작업을 확인/수행 후 종료합니다.
하트비트 작동 방식
에이전트가 신뢰성 있게 동작하려면 하트비트 프로토콜을 이해해야 합니다.
에이전트 하트비트 시퀀스 (9단계):
-
GET /api/agents/me로 신원 확인 - 보류 승인 콜백 처리
-
GET /api/companies/{companyId}/issues로 작업 목록 획득 - 우선순위 지정 (진행 중 > 할 일 > 차단 제외)
-
POST /api/issues/{issueId}/checkout으로 작업 체크아웃 (중복 방지) - 전체 작업 컨텍스트/댓글 읽기
- 작업 수행
- 댓글/상태 변경으로 작업 업데이트
- 필요 시 하위 작업 위임
실행 시 Paperclip이 주입하는 환경 변수:
PAPERCLIP_TASK_ID # 트리거된 작업 ID
PAPERCLIP_WAKE_REASON # 에이전트가 깨어난 이유 (타이머/멘션/할당)
PAPERCLIP_AGENT_ID # 에이전트 신원
PAPERCLIP_API_URL # Paperclip API 콜백 URL
에이전트는 이 정보로 작업 업데이트, 하위 작업 생성, 승인 요청, 위임 등을 진행합니다.
작업 할당 및 추적
작업 생성 및 할당은 GitHub 이슈+프로젝트 관리 시스템처럼 동작합니다.
CLI로 작업 생성:
paperclipai issue create \
--company-id <id> \
--title "주문 엔드포인트에 페이지네이션 추가" \
--assignee-agent-id <backend-engineer-id>
작업에는 상위 작업, 목표 링크, 댓글, @-멘션(주문형 실행) 등 다양한 필드를 포함할 수 있습니다.
모든 열린 작업 조회:
paperclipai issue list
또는 대시보드에서 작업 소유자/상태/마지막 하트비트 기록까지 확인할 수 있습니다.
실제로 작동하는 예산 통제
각 에이전트에 월별 토큰 예산을 할당하세요.
- 80% 도달 시: 에이전트는 중요 작업만 수행
- 100% 도달 시: 에이전트 자동 일시 중지
추천 시작 예산: 계층별 월 $20~50
대시보드에서 에이전트별 소진율, 하트비트당 비용, 누적 지출을 실시간 확인할 수 있습니다.
비용 이상징후(하트비트당 비용 급증)는 프롬프트/작업 범위 재점검 신호입니다. 예산만 늘리지 말고, 작업 구조를 명확하게 조정하세요.
예산 통제가 없으면 잘못된 에이전트가 순식간에 수백 달러를 소모할 수 있습니다. Paperclip은 이를 방지합니다.
런타임 스킬: 재훈련 없이 에이전트에게 새로운 워크플로 가르치기
Paperclip의 스킬 주입:
에이전트 실행 시 어댑터가 구성 디렉토리 내 SKILL.md에 심볼릭 링크를 생성, --add-dir로 전달합니다.
에이전트는 스킬 파일을 읽고, 새로운 워크플로(예: 커밋 메시지 작성법, 마이그레이션 규칙, API 문서 포맷 등)를 즉시 반영합니다.
스킬 예시:
# 스킬: 데이터베이스 마이그레이션
마이그레이션을 생성할 때:
1. 기존 마이그레이션 파일을 수정하지 마십시오.
2. 설명적인 이름을 사용하십시오: YYYYMMDD_description.sql
3. up 및 down SQL을 모두 포함하십시오.
4. 커밋하기 전에 로컬에서 테스트하십시오.
5. 변경 사항에 대한 비즈니스 이유를 설명하는 주석을 추가하십시오.
이 파일을 스킬 디렉토리에 추가하면 에이전트는 다음 하트비트부터 이를 따릅니다.
에이전트가 구축한 API를 테스트하는 경우
에이전트가 API를 만들 때, 바로 테스트할 수 있어야 합니다.
Apidog은 API 설계, 목(mock) 서버, 자동화 테스트를 통합 제공합니다.
백엔드 에이전트가 엔드포인트를 출시하면 Swagger, Postman, 별도 목(mock) 도구 없이 즉시 유효성 검사를 진행할 수 있습니다.
OpenAPI 스펙 기반 테스트 스위트를 자동 생성 및 실행, 결과는 작업 댓글로 피드백 됩니다.
에이전트는 다음 하트비트에서 실패를 수정, 코드-테스트-수정 루프가 사람 개입 없이 돌아갑니다.
Apidog은 REST, GraphQL, gRPC까지 지원하며 무료로 시작할 수 있습니다.
다중 인스턴스 관리
Paperclip은 PAPERCLIP_INSTANCE_ID 환경 변수 또는 --instance 플래그로 한 머신에서 여러 격리 인스턴스를 지원합니다.
각 인스턴스는 독립 구성/DB/포트/작업공간을 가집니다.
로컬 개발 시 worktree 활용:
paperclipai worktree:make feature/orders-pagination
브랜치별로 완전히 격리된 개발 인스턴스를 만들 수 있어, 프로덕션 환경에 영향을 주지 않고 실험 가능합니다.
작동하는 다중 에이전트 설정 실전 패턴
기본 세팅 후 바로 활용할 수 있는 베스트 프랙티스:
- 목표 계단식: 회사 목표 → CEO가 프로젝트 목표 분할 → 각 관리자 에이전트가 개별 작업 분할. 목적의 연쇄가 있으면 에이전트의 작업 품질이 높아집니다.
- 승인 게이트: 프로덕션/스테이징/빌링 영향 작업에는 승인 게이트 설정. 에이전트가 작업을 일시 중지하고 사용자 승인 후 계속하도록 만드세요.
- @-멘션 주문형 깨우기: 하트비트 간격을 느리게 설정하고, @-멘션으로 필요시 즉시 깨워 비용을 줄이면서 빠른 반응을 얻으세요.
-
에이전트별 작업공간 분리: 각 에이전트는
workspaces/<agent-id>/디렉토리를 사용. 작업공간을 공유하지 마세요.
시작하는 데 약 15분 소요
Paperclip 온보딩은 15분 미만, 서버 설치/시작, 에이전트 추가, 작업 생성까지 5분 이내에 완료할 수 있습니다.
핵심은 회사 구조/미션 작성, 역할별 모델 선정, 예산 제한 설정입니다.
30분 정도 투자해 구조를 잡으면, 서둘러 연결한 것보다 훨씬 생산적인 에이전트 환경을 만들 수 있습니다.
두 개 이상의 AI 에이전트를 이미 실행 중이라면, Paperclip은 오후 한 번 투자로 얻을 수 있는 최적의 솔루션입니다.
에이전트당 터미널 탭/예산 통제/작업 소유권/감사 로그가 있는 구조화된 회사와, 그렇지 않은 사이의 차이는 사이드 프로젝트와 실전 자동화의 차이입니다.
Top comments (0)