AI 에이전트 소프트웨어 팀으로 변환: 무료 Paperclip 도구

다수의 AI 에이전트를 실행하는 대부분의 개발자는 다섯 번째 에이전트쯤에서 동일한 문제에 직면합니다. 한 터미널에서는 Claude Code가 백엔드 서비스를 재작성하고 있고, 다른 터미널에서는 Codex가 테스트를 생성하며, Cursor는 컴포넌트를 편집하고 있고, 확인하는 것을 잊어버린 세 개의 탭이 더 있을 수 있습니다. 아무도 다른 에이전트가 무엇을 하는지 모릅니다. 비용은 치솟고, 두 에이전트가 같은 작업을 중복해서 수행합니다. 한 에이전트는 명확한 목표를 받지 못해 여섯 시간 동안 실행되고도 쓸모 있는 결과물을 전혀 내놓지 못합니다.

Paperclip은 이 문제를 해결합니다. 이것은 흩어져 있는 AI 에이전트를 조직도, 할당된 역할, 작업 관리, 예산 제한 및 감사 로그를 갖춘 구조화된 회사로 변환하는 오픈소스 오케스트레이션 플랫폼입니다. 출시 3주 만에 GitHub 스타 35,000개 이상을 달성했는데, 이는 얼마나 많은 개발자들이 같은 좌절감을 느끼고 있었는지 보여줍니다.

버튼

이 글에서는 Paperclip을 설정하고, 첫 번째 에이전트 회사를 구성하며, 모든 터미널을 일일이 확인하지 않아도 작업이 실제로 완료되도록 실행하는 방법을 안내합니다.

Paperclip은 무엇이며 (무엇이 아닌가)

무언가를 설치하기 전에, 무엇을 얻게 될지 이해하십시오.

Paperclip은 오케스트레이션 레이어입니다. 에이전트를 조정하고, 작업을 추적하며, 예산을 통제하고, 회사의 목표에 대한 맥락을 제공합니다. 에이전트를 구축하거나, AI 제공업체를 대체하거나, 채팅 인터페이스를 추가하지 않습니다.

Paperclip 팀이 사용하는 사고 모델: "Claude Code가 직원이라면, Paperclip은 회사입니다."

이는 다음을 의미합니다:

에이전트에는 단순히 프롬프트가 아닌 역할이 있습니다.
작업에는 단순히 열린 터미널이 아닌 소유자가 있습니다.
예산에는 단순히 분위기가 아닌 명확한 한도가 있습니다.
모든 것은 감사 추적(audit trail)에 기록됩니다.

Paperclip은 Claude Code, OpenAI Codex, Cursor, Gemini CLI 및 웹훅 또는 하트비트 신호를 받을 수 있는 모든 에이전트와 작동합니다. 에이전트는 사용자가 가져오고, Paperclip이 회사를 운영합니다.

명시적으로 다음은 아닙니다:

챗봇 UI
n8n 또는 Zapier와 같은 드래그 앤 드롭 워크플로 빌더
에이전트 작성용 프레임워크
단일 에이전트 사용 사례에 유용함

AI 에이전트 한 개를 가끔 실행하는 경우 Paperclip은 과도합니다. 진행 중인 작업에 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은 모든 것을 ~/.paperclip/instances/default/ 아래에 저장합니다:

~/.paperclip/instances/default/
  config.json          — 서버 및 스토리지 설정
  db/                  — 내장 PostgreSQL 데이터 파일
  secrets/master.key   — 암호화 키 (자동 생성)
  logs/                — 서버 로그
  data/storage/        — 파일 첨부
  workspaces/<agent>/  — 에이전트별 작업 디렉토리

로컬 모드는 기본적으로 local_trusted 인증을 사용하며, 이는 로그인을 건너뛰고 가상의 "Board" 사용자를 사용합니다. 계정 생성 없이 즉시 대시보드를 사용할 수 있습니다.

접속한 후, 다음 건강 검사를 실행하십시오:

paperclipai doctor

뭔가 잘못 구성되어 있다면, --repair가 대부분의 문제를 자동으로 수정합니다:

paperclipai doctor --repair

첫 회사 설정

Paperclip에서 "회사"는 에이전트, 작업, 목표 및 예산을 위한 최상위 컨테이너입니다. 모든 프로젝트 멤버가 역할과 보고 체계를 가진 AI 에이전트라는 점을 제외하고는 프로젝트라고 생각할 수 있습니다.

대시보드에서 새로운 회사를 생성하고 미션 선언문을 부여하십시오. 이것은 단순한 장식이 아닙니다. 에이전트가 받는 모든 작업은 회사 미션으로 거슬러 올라가므로, 에이전트는 무엇을 해야 할지뿐만 아니라 왜 이 작업을 하는지에 대한 맥락을 가집니다. 이는 장기적인 에이전트 실행에서 의사 결정에 중요합니다.

간단한 미션 예시: "고객 주문 관리를 위한 REST API를 구축하고 유지보수합니다. 속도보다 정확성을 우선시합니다. 모든 공개 엔드포인트를 문서화합니다."

이 한 문장이 에이전트가 내리는 모든 결정에 대한 필터를 제공합니다.

첫 에이전트 추가

Paperclip의 각 에이전트에는 어떤 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 에이전트 구성 (UI 또는 에이전트별 구성에서 설정):

필드	설명
`model`	사용할 Claude 모델 (예: `claude-sonnet-4-6`)
`cwd`	에이전트의 작업 디렉토리 (누락 시 자동 생성)
`promptTemplate`	`{{variable}}` 대체가 포함된 시스템 프롬프트
`maxTurnsPerRun`	하트비트당 최대 에이전트 턴 수 (기본값: 300)
`timeoutSec`	하드 실행 제한 (0 = 타임아웃 없음)

역할별 모델 할당을 시작하기 전에 고려해 볼 가치가 있습니다. 모든 에이전트에 Opus를 실행하면 비용이 빠르게 비싸집니다. 실용적인 분할은 다음과 같습니다:

CEO / 오케스트레이션 에이전트: Sonnet (전략적 추론, 비용 가치 있음)
관리자 에이전트: Haiku (라우팅 및 위임, 저렴하고 빠름)
창의적 / 코딩 IC: Sonnet (여기서는 출력 품질이 중요함)
정형화된 IC: Haiku (보일러플레이트 생성, 테스트 스캐폴딩, 마이그레이션)

이 할당은 모든 곳에 Sonnet을 실행하는 것에 비해 월별 에이전트 지출을 40-60% 절감할 수 있으며, 일상적인 작업의 품질 저하는 크게 발생하지 않습니다.

에이전트 조직 구조화

다음은 소규모 소프트웨어 프로젝트를 위한 작동 가능한 구조입니다:

CEO (소네트)
 ├── CTO (하이쿠)
 │    ├── 백엔드 엔지니어 (소네트)
 │    ├── 프론트엔드 엔지니어 (소네트)
 │    └── QA 엔지니어 (하이쿠)
 └── 기술 문서 작성자 (하이쿠)

CEO 에이전트는 미션을 가지고 이를 목표로 나눕니다. CTO는 엔지니어링 에이전트에게 목표를 전달합니다. 엔지니어는 작업을 수행하고, QA는 검증합니다. 문서 작성자는 문서를 만듭니다.

각 에이전트에는 하트비트 간격이 있습니다. 이는 에이전트가 깨어나 할당된 작업을 확인하고, 작업을 수행한 후 종료되는 빈도입니다. 에이전트는 지속적으로 실행되지 않습니다. 깨어나고, 실행하고, 잠듭니다. 이것이 비용이 치솟는 것을 방지합니다.

권장 간격:

코딩 에이전트: 600초 (10분)
주문형 에이전트: 86,400초 (하루에 한 번), 주문형 깨우기 활성화 시
최소 안전 간격: 30초 (이보다 낮으면 비용 초과 및 스팸 발생 위험)

하트비트 작동 방식

하트비트 모델을 이해하는 것은 에이전트로부터 신뢰할 수 있는 작업을 얻는 데 중요합니다.

에이전트가 깨어날 때마다 다음 9단계 프로토콜을 따릅니다:

GET /api/agents/me를 통해 신원 확인
보류 중인 승인 콜백 처리
GET /api/companies/{companyId}/issues에서 할당된 작업 가져오기
우선순위 지정: 진행 중인 작업 먼저, 그 다음 할 일; 차단된 작업은 차단을 해제할 수 없는 한 건너뛰기
POST /api/issues/{issueId}/checkout을 통해 작업 체크아웃 (다른 에이전트가 이미 가져갔다면 응답은 409이며 이 에이전트는 다음으로 넘어감)
전체 작업 컨텍스트 및 댓글 스레드 읽기
작업 수행
댓글 및 상태 변경으로 작업 업데이트
필요한 경우 부모 및 목표 ID로 하위 작업 위임

5단계의 체크아웃 메커니즘은 중복 작업을 방지합니다. 두 에이전트가 같은 작업을 가져갈 수 없습니다. 한 에이전트가 작업을 수행 중이면 다른 에이전트는 자동으로 작업을 건너뜁니다.

Paperclip은 환경 변수를 통해 모든 에이전트 실행에 컨텍스트를 주입합니다:

PAPERCLIP_TASK_ID          # 이 실행을 트리거한 작업
PAPERCLIP_WAKE_REASON      # 에이전트가 깨어난 이유 (타이머, 언급, 할당)
PAPERCLIP_AGENT_ID         # 에이전트의 신원
PAPERCLIP_API_URL          # Paperclip API로 콜백할 URL

에이전트는 이를 사용하여 업데이트를 게시하고, 하위 작업을 생성하고, 승인을 요청하고, 위임할 수 있습니다. 이 모든 것이 단일 하트비트 내에서 이루어집니다.

작업 할당 및 추적

Paperclip의 작업은 GitHub 이슈와 프로젝트 관리 도구를 결합한 방식과 유사하게 작동합니다. UI 또는 CLI에서 하나를 생성하십시오:

paperclipai issue create \
  --company-id <id> \
  --title "주문 엔드포인트에 페이지네이션 추가" \
  --assignee-agent-id <backend-engineer-id>

작업은 다음을 가질 수 있습니다:

큰 작업을 하위 작업으로 나누기 위한 상위 작업
에이전트가 어떤 회사 목표에 기여하는지 알 수 있도록 하는 목표 링크
맥락, 승인 요청 및 상태 업데이트를 위한 댓글
주문형으로 특정 에이전트를 깨우기 위한 @-멘션 (다음 하트비트를 기다릴 필요 없음)

CLI에서 모든 열린 작업을 볼 수 있습니다:

paperclipai issue list

또는 대시보드에서 작업의 현재 소유자, 상태, 그리고 마지막으로 어떤 하트비트 실행이 해당 작업을 건드렸는지 확인할 수 있습니다.

실제로 작동하는 예산 통제

이것은 Paperclip의 가장 유용한 기능 중 하나이며, 다중 에이전트 설정에 익숙하지 않은 사람들이 가장 간과하는 기능입니다.

각 에이전트에는 월별 토큰 예산이 할당됩니다. 80%에 도달하면 에이전트는 자동으로 중요 작업만 수행하게 됩니다. 100%에 도달하면 완전히 일시 중지됩니다.

에이전트 구성에서 예산을 설정하십시오. 커뮤니티에서 제안하는 시작점은 에이전트 계층당 월 $20-50입니다. 에이전트당 소진율, 하트비트당 비용, 누적 월 지출을 모두 대시보드에서 추적할 수 있습니다.

비용 대시보드는 어떤 에이전트가 효율적이고 어떤 에이전트가 집중되지 않은 작업에 토큰을 소모하고 있는지 보여줍니다. 에이전트의 하트비트당 비용이 증가한다면, 일반적으로 프롬프트가 너무 모호하거나 작업 범위가 너무 넓다는 신호입니다. 예산을 늘리는 것이 아니라 할당을 더 명확하게 함으로써 이를 해결할 수 있습니다.

예산 통제가 없으면, 30초 간격으로 Extended Thinking이 활성화된 채 실행되는 잘못 구성된 에이전트가 눈치채기도 전에 수백 달러를 소모할 수 있습니다. Paperclip은 이러한 일이 자동으로 발생하는 것을 방지합니다.

런타임 스킬: 재훈련 없이 에이전트에게 새로운 워크플로 가르치기

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 플래그를 통해 한 머신에서 여러 개의 격리된 인스턴스를 지원합니다. 각 인스턴스는 고유한 구성, 데이터베이스, 포트 및 작업 공간을 가집니다.

로컬 개발을 위해 worktree 명령은 Git 브랜치별로 완전히 격리된 개발 인스턴스를 생성합니다:

paperclipai worktree:make feature/orders-pagination

이것은 해당 브랜치에 한정된 별도의 포트, 구성 및 데이터베이스를 제공합니다. 프로덕션 에이전트 설정을 건드리지 않고 기능 코드에 대해 테스트 회사를 실행할 수 있습니다. 작업이 끝나면 해체하면 사라집니다.

작동하는 다중 에이전트 설정

기본 사항이 실행되면 잘 작동하는 몇 가지 패턴:

목표 계단식: 회사 수준에서 하나의 상위 목표를 작성한 다음, CEO 에이전트가 이를 프로젝트 목표로 나누고, 각 관리자 에이전트가 다시 이를 작업으로 나누도록 합니다. 에이전트는 고립된 지시를 받는 것보다 목적의 연쇄를 이해할 때 더 나은 작업을 수행합니다.
승인 게이트: 프로덕션, 스테이징 환경 또는 빌링에 영향을 미치는 모든 에이전트 작업에 대해 승인 게이트를 구성하십시오. 에이전트는 일시 중지되고, 사용자에게 알림을 보내고, 계속하기 전에 승인을 기다립니다. 이는 하나의 수동 단계를 추가하지만 비용이 많이 들기 전에 문제를 잡아냅니다.
@-멘션을 통한 주문형 깨우기: 빠른 하트비트 간격(및 그에 따른 토큰 비용) 대신, 에이전트를 느린 간격으로 설정하고 작업 댓글에서 @-멘션을 사용하여 필요할 때 즉시 깨우십시오. 지속적인 폴링에 대한 비용을 지불하지 않고도 중요한 작업에 대한 빠른 응답 시간을 얻을 수 있습니다.
에이전트별 개별 작업 공간: 각 에이전트는 workspaces/<agent-id>/ 아래에 고유한 작업 디렉토리를 가집니다. 이들을 깨끗하게 유지하십시오. 작업 공간을 공유하는 에이전트는 서로의 작업을 침해합니다. 격리는 기본적으로 내장되어 있습니다. 이를 거스르지 마십시오.

시작하는 데 약 15분 소요

처음 온보딩하는 데 15분 미만이 소요됩니다. 하나의 명령으로 서버를 설치하고 시작할 수 있습니다. 대시보드에서 첫 에이전트를 추가하고 작업을 생성하는 데 5분이 더 걸립니다.

더 어려운 부분은 회사를 잘 구성하는 것입니다: 명확한 미션을 작성하고, 각 역할에 적합한 모델을 선택하고, 합리적인 예산 제한을 설정하는 것입니다. 작업을 할당하기 전에 30분 동안 이 작업에 투자하면, 모든 것을 서둘러 연결하고 최선을 바라는 것보다 에이전트가 훨씬 더 나은 결과를 생산할 것입니다.

현재 진행 중인 프로젝트에서 두 개 이상의 AI 에이전트를 이미 실행하고 있다면, 이것은 오후 시간을 투자할 가치가 있습니다. 에이전트당 하나의 터미널 탭과 예산 통제, 작업 소유권, 감사 로그를 갖춘 구조화된 회사 사이의 차이는 사이드 프로젝트와 실제로 감독 없이 실행될 수 있는 것 사이의 차이입니다.