KG
목록으로 돌아가기
ETC

Paperclip 사용 후기

역할별 AI Agent로 구성해 Paperclip 사용 후기

2026년 9월 29일 8분 읽기1636 단어
AI
Agent
Paperclip
Codex
Gemini
Retrospective

Paperclip 사용 후기

Paperclip으로 Codex와 Gemini의 역할을 나눠 작은 AI 개발 조직을 구성해봤다. 작업 흐름은 훨씬 명확해졌지만, 시간과 사용량까지 줄어드는 도구는 아니었다.

최근 Paperclip이라는 오픈소스 프로젝트로 AI Agent 여러 개를 하나의 개발 조직처럼 구성해봤다.

평소에는 Codex 하나를 열어두고 요구사항을 전달한 뒤, 구현을 확인하고 누락을 다시 요청하는 식으로 작업했다. 이 방식도 작은 수정에는 충분히 빠르다. 다만 Backend와 Frontend가 함께 바뀌거나, 화면 설계와 회귀 검증까지 필요한 작업에서는 내가 직접 다음 작업을 계속 판단하고 연결해야 했다.

Paperclip은 조금 다른 방식으로 접근한다. AI 하나에게 모든 일을 맡기는 대신, 역할과 책임을 가진 Agent에 Task를 나누어 전달한다. 이번에는 개발 관련 업무 대부분을 Codex에 맡기고, UI/UX 판단이 필요한 Product Designer만 Gemini로 구성했다.

이번에 구성한 AI 개발팀

아래 그림은 실제로 만든 역할 구조다. Chief of Staff가 요청을 받아 분류하고, CTO가 기술적인 영향도를 판단한 뒤 필요한 구현 Agent에게 일을 나눈다. 구현이 끝나면 Reviewer/QA가 확인하고, 필요한 경우 Technical Writer가 문서를 갱신한다.

Paperclip으로 구성한 Codex·Gemini AI 개발팀 역할 구조

모든 Task에 이 조직 전체가 참여하는 것은 아니다. 작은 Backend 수정이라면 Backend Engineer와 Reviewer/QA만으로 충분하고, 화면 흐름을 새로 설계할 때만 Designer를 참여시키는 편이 효율적이었다.

Paperclip이란?

Paperclip은 여러 AI Agent를 회사 조직처럼 관리할 수 있게 하는 도구다. 단순히 여러 모델을 동시에 실행하는 것보다, 누가 요청을 분석하고 누가 설계하며 누가 구현과 검증을 맡을지 정한 뒤 Agent 사이에서 Task를 전달하는 흐름에 가깝다.

예를 들어 관리자 화면의 하드코딩된 상품 분류 Select를 DB 기반으로 바꿔 달라는 요청을 받았다고 하자.

일반적인 AI 코딩 도구에서는 보통 아래처럼 한 Agent가 분석부터 구현까지 진행한다.

User
  -> AI
  -> 코드 분석
  -> 구현

Paperclip에서는 역할을 나눈 흐름을 만들 수 있다.

User
  -> Chief of Staff: 요청 분석과 Task 분류
  -> CTO: 변경 범위와 기술 방향 판단
  -> Backend / Frontend: 구현
  -> Reviewer / QA: 요구사항·회귀 검증
  -> Technical Writer: 필요한 문서 갱신

이 흐름의 핵심은 Agent 수가 아니라 책임의 분리다. 작은 변경에 모든 Agent를 붙이면 오히려 느리고 비싸다. 반대로 여러 영역이 동시에 바뀌는 기능은 분석, 구현, 검증이 분리되어 있어 누락을 줄이기 쉬웠다.

설치와 실행

Paperclip은 npx로 실행할 수 있었다.

npx paperclipai onboard --yes
npx paperclipai run

전역 npm 패키지를 설치하는 방식이 아니라 npx가 패키지를 실행하는 형태다. 초기 설정이 끝나면 로컬에서 Paperclip 서버가 실행되고, 브라우저 UI에서 Company, Project, Agent, Task를 관리할 수 있다.

Codex API Key 없이 사용해본 방법

이번 테스트에서는 OpenAI API Key를 사용하지 않았다. 이미 Codex CLI를 ChatGPT 계정으로 로그인해 사용 중이었기 때문에, Paperclip의 Codex Adapter가 그 인증을 사용하도록 구성했다. 별도 API 종량제가 아니라 ChatGPT Plus에 포함된 Codex 사용량으로 테스트한 셈이다.

실제로 동작할 Agent는 Adapter를 Codex 또는 Gemini로 명시적으로 지정하는 편이 좋았다. 자동 생성 과정에서 일부 Agent가 Process Adapter로 만들어졌고, 이 경우 아래 오류가 발생했다.

Process adapter missing command

Agent별로 사용할 모델 Adapter를 다시 지정하자 해결됐다. 처음 설정할 때는 Agent를 많이 만드는 것보다, 각 Agent가 실제로 실행 가능한 Adapter와 프로젝트 폴더를 바라보는지부터 확인하는 편이 낫다.

역할은 이렇게 나눴다

Chief of Staff

사용자 요청을 가장 먼저 받아 어떤 Agent가 필요한지 판단한다. 직접 코드를 작성하기보다는 요청을 작게 나누고 CTO나 구현 Agent에게 넘기는 역할이다.

예를 들어 Backend와 Frontend가 함께 바뀌는 요청이라면, 한 Agent에게 길게 맡기는 대신 CTO가 변경 범위를 먼저 정리하도록 전달했다.

CTO

CTO는 전체 기술 구조와 변경 영향도를 담당한다.

요구사항 분석
  -> 기존 코드 분석
  -> 변경 영향도 분석
  -> 기존 기능 재사용 여부 판단
  -> Backend / Frontend 업무 분배

이 역할은 단순 구현보다 판단 비중이 커서 다른 Agent보다 높은 Thinking Effort로 시작했다. 특히 기존 구조를 충분히 읽지 않은 상태에서 새로운 패턴을 도입하는 일을 막는 데 도움이 됐다.

Backend Engineer

API, Service, DB, Validation, Error Handling을 맡는다. 처음부터 새 구조를 만들기보다 기존 프로젝트의 Controller, Service, Repository, Mapper 패턴을 먼저 확인하고 재사용하도록 지시했다.

Frontend Engineer

기존 화면, JavaScript, CSS, 공통 UI 패턴을 분석한 뒤 실제 화면 변경을 담당한다. 공통 함수나 Component가 이미 있다면 그 경로를 우선 사용하도록 했다.

Product Designer

Product Designer에는 Gemini를 사용했다. 이 Agent는 코드 수정 자체보다 기존 화면 분석, 사용자 흐름, Layout, Loading·Empty·Error 상태, Validation, 반응형 UI처럼 UI/UX 판단이 필요한 Task에만 참여한다.

화면 디자인이 바뀌지 않는 단순 연동 작업이라면 Designer를 부르지 않았다. 역할이 있다고 항상 작업을 줘야 하는 것은 아니었다.

Reviewer / QA와 Technical Writer

Reviewer/QA는 코드 리뷰만 하는 역할이 아니다. 요구사항이 충족됐는지, 기존 동작이 깨지지 않았는지까지 확인하도록 했다. 검색과 Reset 동작, 누락된 화면, 중복 데이터, 기존 API와의 호환성 같은 항목을 검토한다.

Technical Writer는 구현 이후 API 문서, 화면 설계 문서, 변경 이력을 실제 코드 상태에 맞게 정리하는 역할이다. 문서 변경이 없는 작은 수정에는 굳이 참여시키지 않았다.

프로젝트를 연결하고 Baseline부터 만들었다

Agent를 만들었다고 바로 기능 개발을 시작하지는 않았다. 먼저 실제 개발 프로젝트를 Paperclip Project로 등록하고 Local Folder를 연결했다. 그리고 각 역할이 현재 코드를 이해하도록 아래 Baseline Task를 만들었다.

  • Architecture baseline
  • Backend conventions baseline
  • Frontend conventions baseline
  • UI/UX baseline
  • Quality gates baseline
  • Documentation standards baseline

CTO는 디렉터리와 Layer 구조, 설정, 공통 모듈, 테스트 구조를 살폈다. Backend Engineer는 기존 구현 패턴을, Frontend Engineer는 UI와 JavaScript 구조를, Designer는 현재 UI/UX 패턴을 분석하게 했다.

여기서 가장 중요하게 넣은 지침은 하나였다.

새로운 규칙을 만들지 말고, 현재 코드에서 실제로 확인되는 패턴만 정리한다.

AI가 프로젝트를 읽고 자신의 선호대로 구조를 다시 설계하는 문제를 막기 위해서다. 처음에는 Local Folder를 연결하지 않은 채 Baseline 분석을 시켰는데, 빈 Workspace를 보고 API와 Service, Frontend가 없다는 결과를 만들었다. 프로젝트를 연결한 뒤 다시 실행하니 실제 소스에 맞는 분석이 나왔다.

가상의 기능으로 확인한 작업 흐름

다음처럼 상품 검색 화면에 상품 분류 Select가 있다고 가정해보자.

<select id="category">
    <option value="">전체</option>
    <option value="FOOD">식품</option>
    <option value="LIFE">생활</option>
    <option value="DIGITAL">디지털</option>
</select>

분류가 추가될 때마다 HTML을 수정해야 하므로, DB에서 목록을 조회해 Select를 자동으로 구성하도록 바꾸려 한다.

DB
  -> Backend API
  -> Frontend
  -> Select Option 생성

기존 프로젝트에 공통 Select 생성 함수가 있다면 새로 만들지 않고 재사용하는 것이 맞다.

common.addSelectOption(
    'category',
    '/api/category/list',
    {
        id: 'categoryName',
        value: 'categoryCode'
    }
);

이 Task를 Chief of Staff에게 할당하면 먼저 기존 조회 API와 공통 Select 함수가 있는지, Backend 신규 구현이 필요한지, 같은 하드코딩이 다른 화면에도 있는지, 기존 검색 파라미터와 호환되는지를 확인한다.

그 뒤 CTO가 실제 변경 범위를 판단하고 Backend와 Frontend Task를 나눈다. Backend Engineer는 목록 조회와 API를, Frontend Engineer는 하드코딩 제거와 연동을 맡는다. 화면 디자인 변경이 없다면 Gemini Designer는 참여하지 않는다. 이처럼 Task의 성격에 맞춰 필요한 Agent만 호출하는 것이 중요했다.

Plan과 승인 과정이 유용했던 이유

Paperclip에서 흥미로웠던 부분 중 하나는 Agent가 바로 코드를 고치기 전에 Plan을 올릴 수 있다는 점이었다.

기존 API 조사
  -> Service 확인
  -> DB Query 확인
  -> 기존 응답 형식 유지 여부 판단
  -> 필요한 파일만 수정

사용자가 이 계획을 확인하고 승인하면 실제 구현이 시작된다. 회사 코드를 다룰 때는 이 단계가 특히 유용했다. AI가 예상하지 못한 방향으로 대규모 변경을 시작하기 전에, 조사 범위와 수정 대상, 일부러 건드리지 않을 영역을 먼저 확인할 수 있기 때문이다.

Dashboard에서 보는 작업 상태

Paperclip은 Agent와 Task의 진행 상황을 Dashboard에서 한눈에 볼 수 있다. 누가 작업 중인지, 어떤 Task가 In Progress나 In Review 상태인지, 최근 어떤 결과가 완료됐는지 확인하기 좋았다.

Paperclip Dashboard에서 Agent와 Task 상태를 확인하는 화면

여러 Agent가 동시에 움직일 때는 채팅 기록만으로 흐름을 따라가기가 쉽지 않다. 이 화면에서 Todo, In Progress, In Review, Blocked, Done 같은 상태가 관리되기 때문에, 현재 병목이 구현인지 검토인지 파악하기가 수월했다.

직접 사용하며 겪은 시행착오

처음부터 매끄럽지는 않았다.

첫째, 앞에서 말한 Process Adapter 오류가 있었다. 자동 생성된 Agent가 실행할 명령을 갖고 있지 않아 실패했으므로, 실제 사용할 Adapter를 Codex나 Gemini로 다시 지정해야 했다.

둘째, Thinking Effort에 모델이 지원하지 않는 값을 전달해 오류가 났다. 결국 역할별로 지원되는 값을 명시했다. 처음에는 아래 정도로 시작했다.

Chief of Staff -> Medium
CTO            -> High
Backend        -> Medium
Frontend       -> Medium
Reviewer       -> High

셋째, 앞서 언급했듯 Project Local Folder 없이 Baseline을 실행하면 Agent는 빈 Workspace만 분석한다. Agent 설정 전보다 프로젝트 연결 상태를 먼저 확인해야 했던 이유다.

장점이 그대로 단점이 되기도 한다

가장 좋았던 점은 작업이 체계적으로 관리된다는 감각이었다. Codex 하나만 사용할 때는 내가 요구사항 설명, 구현 확인, 누락 확인, 재수정 요청, 테스트 요청을 반복했다. Paperclip에서는 Chief of Staff의 요청 분석, CTO의 기술 판단, 구현 Agent의 개발, Reviewer의 검증이라는 흐름으로 책임이 나뉜다.

특히 한 Agent가 놓친 부분을 다른 역할이 다시 보는 구조가 괜찮았다. Backend는 구현 관점으로, Frontend는 화면 동작 관점으로, Reviewer는 전체 요구사항 관점으로 본다. 요구사항을 처음에 구체적으로 전달했을 때 단일 Agent에 한 번 요청하는 방식보다 결과물이 안정적으로 느껴진 이유다.

하지만 이 장점은 속도와 사용량이라는 비용을 동반한다. 단일 Codex라면 코드 분석과 구현으로 끝날 작업도 Paperclip에서는 Chief of Staff, CTO, Backend, Frontend, Reviewer가 각자 Context를 확인한다. Plan 작성, Task 전달, 결과 검토도 반복된다.

이번 테스트에서는 비교적 단순한 기능과 Baseline 구성만으로도 ChatGPT Plus의 5시간 Codex 사용 한도 기준 약 40%를 사용했다. API 종량제 대신 구독 사용량으로 실행한 환경의 개인적인 측정이지만, 같은 프로젝트를 여러 Agent가 독립적으로 읽는 만큼 단일 Agent보다 사용량이 커질 수밖에 없다는 점은 분명했다.

작업 크기에 따라 조직을 줄이는 편이 낫다

처음에는 만들어둔 Agent를 모두 사용하고 싶었다. 몇 번 실행해보니 작은 Task에 전체 조직을 동원하는 것은 과했다. 현재는 아래 정도의 기준이 가장 현실적으로 느껴진다.

작업 규모 권장 구성
간단한 수정 단일 Agent
작은 Backend 수정 Backend Engineer + Reviewer/QA
일반 기능 개발 CTO + Backend/Frontend + Reviewer/QA
새 화면·UX 설계 Gemini Product Designer + Codex Frontend Engineer + Reviewer/QA
여러 영역이 바뀌는 큰 기능 Chief of Staff + CTO + 구현 Agent + Reviewer/QA + Writer

Paperclip을 쓴다고 Codex나 Gemini 자체가 더 똑똑해지는 것은 아니다. 대신 요구사항을 분석하고, 계획하고, 역할을 나누고, 구현과 리뷰를 거쳐 완료하는 개발 프로세스를 도구 안에 만들 수 있다.

마무리

Paperclip을 한 문장으로 표현하면 AI를 개발 도구 하나가 아니라 조직처럼 운영할 수 있게 해주는 도구라고 생각한다.

Codex는 Backend와 Frontend 개발을 맡고, Gemini는 UI/UX 판단을 맡으며, Reviewer가 결과를 검증하게 구성할 수 있다. 실제로 사용해보니 역할을 나누고 결과를 주고받는 흐름 덕분에 요구사항을 명확히 줬을 때 한 번에 더 안정적인 결과를 얻는 경우가 있었다.

반대로 모든 작업에 이 흐름이 맞는 것은 아니다. 처리 시간은 길어지고 사용량도 늘어난다. 그래서 중요한 것은 Agent를 많이 만드는 것이 아니라, 지금 Task에 정말 필요한 Agent가 누구인지 고르는 일이었다.

개발뿐 아니라 기획, 문서, 마케팅, 리서치처럼 여러 역할이 협업해야 하는 업무라면 Paperclip을 꽤 다양한 방식으로 확장해볼 수 있을 것 같다.