Paperclip으로 AI 개발팀 구축하기: 설치부터 Codex 에이전트가 PR 만드는 실제 사용법

Paperclip으로 AI 개발팀 구축하기: 설치부터 Codex 에이전트가 PR 만드는 실제 사용법

AI 코딩 에이전트를 한두 번 사용하는 것과 여러 에이전트를 팀처럼 운영하는 것은 전혀 다른 문제다.

Codex나 Claude Code를 직접 실행할 때는 보통 이런 식이다.

프로젝트 열기
→ 작업 지시
→ 코드 수정
→ 결과 확인

에이전트가 하나뿐이라면 이것으로 충분하다.

하지만 여러 에이전트에게 일을 나누기 시작하면 관리해야 할 것이 많아진다.

누가 어떤 일을 맡고 있는가
어떤 Agent가 누구에게 보고하는가
작업이 지금 어디까지 진행됐는가
얼마나 많은 비용을 사용했는가
어떤 작업은 사람이 승인해야 하는가
Agent가 실패했을 때 어디서 확인하는가

여기서 Paperclip이 등장한다.

Paperclip은 새로운 AI 모델이 아니다.

Codex나 Claude를 대신하는 코딩 에이전트도 아니다.

Paperclip은 그 위에서 여러 에이전트를 관리하는 Agent Orchestration Layer다.

구조를 단순화하면 이렇다.

Paperclip

CEO Agent
├── CTO Agent
│   ├── iOS Developer Agent
│   └── Backend Developer Agent
│
├── QA Agent
└── Documentation Agent

각 Agent는 실제로는 Codex, Claude Code, Gemini CLI, Cursor 같은 AI Runtime을 사용한다.

Paperclip은 이들에게 역할, 조직도, Task, Budget, Approval, 실행 주기를 붙여준다.

이번 글에서는 로컬 Mac 기준으로 Paperclip을 설치하고, Codex 기반 개발 Agent를 구성한 뒤 실제 GitHub Repository 작업을 맡겨 PR까지 생성하는 흐름을 만들어본다.

---

1. Paperclip은 정확히 무엇을 하는가

Paperclip을 이해할 때 가장 중요한 것은 다음 구분이다.

Codex / Claude Code / Cursor
→ 실제 작업을 수행하는 Agent Runtime

Paperclip
→ Agent들을 조직하고 관리하는 Control Plane

예를 들어 Codex Agent가 실제로 하는 일은 이런 것이다.

Swift 파일 읽기
코드 수정
테스트 실행
git commit
git push
PR 생성

Paperclip은 그 위에서 다음을 담당한다.

Agent 생성

역할 지정

보고 관계 설정

Task 배정

작업 상태 관리

승인 관리

Budget 관리

실행 기록

Agent별 비용 확인

즉 Paperclip을 직접 코딩 도구라고 생각하면 조금 이상해진다.

차라리 다음에 가깝다.

AI Agent용

Jira
+ 조직도
+ Budget Manager
+ Scheduler
+ Audit Log
+ Runtime Launcher

Paperclip 공식 문서에서는 이를 AI Company를 운영하는 시스템으로 설명한다.

---

2. Paperclip의 기본 구조

Paperclip에서는 대부분의 것이 Company 안에 존재한다.

Company
├── Goal
├── Agents
├── Projects
├── Tasks
├── Approvals
└── Budget

Company는 하나의 독립적인 Agent 조직이다.

예를 들어 개발 조직을 하나 만든다면 다음과 같이 구성할 수 있다.

Company

Meta App Development

회사 Goal은 다음처럼 설정한다.

iOS 앱의 기능 개발과 유지보수를 자동화하고,
모든 코드 변경은 테스트와 PR 리뷰를 거쳐 main에 반영한다.

그 아래 Agent를 구성한다.

CEO
│
├── CTO
│   ├── iOS Developer
│   └── Backend Developer
│
└── QA Engineer

각 Agent에는 별도의 AI Runtime을 붙일 수 있다.

CEO
→ Claude

CTO
→ Claude

iOS Developer
→ Codex

Backend Developer
→ Codex

QA
→ Gemini CLI

반드시 이렇게 섞을 필요는 없다.

전부 Codex로 구성할 수도 있고 전부 Claude Code로 구성할 수도 있다.

---

3. 먼저 Node.js를 준비한다

현재 Paperclip은 Node.js 20 이상을 요구한다.

확인한다.

node --version

예를 들어 다음처럼 나오면 된다.

v22.18.0

Node가 없다면 Node.js LTS 버전을 설치한다.

pnpm도 준비한다.

npm install -g corepack
corepack enable
corepack prepare pnpm@latest --activate

확인한다.

pnpm --version

---

4. Paperclip 설치

로컬에서 가장 간단한 설치 방법은 한 줄이다.

npx paperclipai onboard --yes

이 명령은 기본적으로 다음 작업을 처리한다.

Paperclip 다운로드

~/.paperclip 디렉터리 생성

설정 파일 생성

Embedded PostgreSQL 초기화

Paperclip Server 시작

정상적으로 실행되면 대략 다음과 같은 메시지가 나온다.

Created config

Initialised database

Server running at

http://localhost:3100

브라우저에서 다음 주소를 연다.

http://localhost:3100

Paperclip Dashboard가 나타난다.

Mac을 재시작한 이후 다시 실행할 때는 다음 명령을 사용할 수 있다.

npx paperclipai run

---

5. Paperclip을 sudo로 실행하지 않는 이유

설치할 때 주의할 부분이 하나 있다.

다음처럼 실행하면 안 된다.

sudo npx paperclipai onboard --yes

Paperclip 기본 설치는 Embedded PostgreSQL을 사용한다.

PostgreSQL은 관리자 계정으로 실행되는 것을 허용하지 않기 때문에 설치 과정에서 문제가 발생할 수 있다.

로컬에서는 일반 사용자 권한으로 실행한다.

npx paperclipai onboard --yes

---

6. 첫 번째 Company를 만든다

Paperclip을 처음 열면 Company를 만든다.

예를 들어 다음과 같이 구성한다.

Company Name

iOS Product Team

Goal은 조금 구체적으로 작성하는 것이 좋다.

나쁜 Goal은 이렇다.

앱을 잘 개발한다.

Agent가 무엇을 해야 할지 판단하기 어렵다.

조금 더 구체적으로 작성한다.

iOS 앱의 기능 개발과 버그 수정을 수행한다.

모든 코드 변경은 테스트를 실행하고,
feature branch에서 작업한 뒤
GitHub Pull Request를 통해 제출한다.

main branch 직접 수정은 금지한다.

Paperclip에서 Goal은 단순 설명이 아니다.

CEO Agent가 Strategy와 Task를 만드는 기준으로 사용한다.

---

7. 첫 번째 Agent는 CEO다

Paperclip에서 처음 만드는 Agent는 CEO 역할을 한다.

Agents 화면에서 New Agent를 선택한다.

예를 들어 이름을 다음처럼 정한다.

CEO

CEO는 다른 Agent와 조금 다르다.

일반 Agent
→ 상위 Manager 존재

CEO
→ Board에게 직접 보고

여기서 Board는 사람이다.

즉 사용자가 최종 관리자다.

구조는 다음과 같다.

사람

Board
│
CEO Agent
│
다른 Agent

---

8. Adapter가 Agent의 실제 엔진이다

Agent를 만들 때 중요한 설정이 Adapter다.

Adapter는 Paperclip과 실제 AI Runtime 사이의 연결 계층이다.

현재 주요 Adapter는 다음과 같다.

claude_local
codex_local
gemini_local
opencode_local
cursor
pi_local
hermes_local

예를 들어 Codex Agent를 만들면

Paperclip Agent
      │
      ▼
codex_local
      │
      ▼
Codex CLI

Claude Code Agent는

Paperclip Agent
      │
      ▼
claude_local
      │
      ▼
Claude Code

가 된다.

---

9. Codex 기반 개발 Agent 만들기

이번 예에서는 코딩을 담당할 Agent를 Codex로 구성한다.

먼저 Codex CLI가 Paperclip을 실행하는 같은 Mac에 설치되어 있어야 한다.

Agent 설정에서 Adapter를 선택한다.

Adapter

codex_local

이름은 예를 들어

iOS Developer

Role은

Senior iOS Developer

정도로 설정한다.

Agent instructions에는 업무 범위를 명확히 적는다.

You are a senior iOS developer.

Responsibilities:

- Implement assigned iOS issues.
- Follow existing project architecture.
- Use Swift 6 conventions.
- Do not modify unrelated files.
- Run relevant tests after implementation.
- Never claim tests passed unless they were actually executed.
- Never commit directly to main.
- Use a feature branch and submit a pull request.

이런 규칙은 Agent에게 단순히

iOS 개발자 역할을 해라.

라고 적는 것보다 훨씬 안정적이다.

---

10. codex_local에서 중요한 설정

codex_local Adapter는 Codex CLI를 Paperclip이 실행한다.

대표적으로 다음과 같은 설정을 가진다.

cwd

model

engine

instructionsFilePath

timeoutSec

workspaceStrategy

env

cwd는 Agent가 작업할 기본 디렉터리다.

예를 들어

/Users/me/Projects/MyApp

engine은 Codex 실행 방식을 선택한다.

현재 Paperclip은 기본값 auto에서 가능하면 ACP 방식을 사용하고, 조건이 맞지 않으면 기존 Codex CLI 방식으로 fallback한다.

처음에는 기본값으로 두는 것이 가장 단순하다.

engine

auto

모델도 특별한 이유가 없다면 Codex 기본값에 맡길 수 있다.

---

11. Codex 인증은 어떻게 처리할까

codex_local Agent는 Paperclip이 관리하는 Codex Home을 사용한다.

이미 Mac에서 Codex CLI에 로그인되어 있다면 Paperclip이 그 인증을 Agent 환경에 연결할 수 있다.

또는 Agent 환경에 별도의

OPENAI_API_KEY

를 설정할 수도 있다.

여러 Agent를 운영한다면 Agent별 인증과 비용을 분리하는 방식도 고려할 수 있다.

중요한 것은 API Key를 AGENTS.md나 Agent Prompt에 직접 적지 않는 것이다.

Secret은 Paperclip Secret 관리 기능을 사용한다.

---

12. Agent는 계속 실행되고 있는 것이 아니다

Paperclip Agent의 동작 방식에서 중요한 개념이 Heartbeat다.

Agent가 24시간 계속 실행되는 것은 아니다.

평소에는 idle 상태로 있다.

idle

작업이 발생하면 Heartbeat가 실행된다.

Task assigned
        ↓
Heartbeat
        ↓
Agent 실행
        ↓
작업 수행
        ↓
결과 기록
        ↓
Agent 종료
        ↓
idle

Heartbeat를 발생시키는 이벤트에는 여러 가지가 있다.

Task Assignment

Schedule

Mention

Manual Invoke

Agent는 필요한 순간에 깨어나 일을 하고 다시 종료된다.

이 방식은 비용을 제어하는 데도 중요하다.

---

13. CEO의 첫 Heartbeat

CEO Agent를 만들고 Heartbeat를 활성화하면 첫 작업이 시작된다.

CEO는 먼저 다음 정보를 읽는다.

Company Goal

자신의 역할

현재 Agent 조직

현재 Task 상태

처음에는 아무 Task도 없다.

그래서 CEO는 먼저 Strategy를 만든다.

예를 들어 Company Goal이

iOS 앱을 지속적으로 개발하고 PR 기반 개발 프로세스를 운영한다.

라면 CEO가 이런 전략을 제안할 수 있다.

1. 개발 Repository를 Project로 등록한다.

2. iOS Developer Agent를 배치한다.

3. QA Agent를 추가한다.

4. 기능 개발은 Developer에게 할당한다.

5. 모든 변경은 PR 기반으로 검토한다.

중요한 것은 이 전략이 바로 실행되지 않는다는 점이다.

먼저 Approval Queue로 들어간다.

---

14. 사람의 승인 없이 모든 것이 돌아가게 만들지 않는다

Paperclip의 좋은 점 중 하나는 Agent 조직에 Approval 흐름을 넣을 수 있다는 것이다.

CEO가 Strategy를 만들면

CEO

Strategy Proposal
        ↓
Approval
        ↓
Board

사람이 확인한다.

문제가 없다면 승인한다.

Approve

수정하고 싶다면

Request Revision

을 선택한다.

CEO Strategy가 승인되기 전에는 Agent들이 실제 Task를 진행하지 못하게 할 수 있다.

AI 조직에서 이 부분은 꽤 중요하다.

완전 자동화를 목표로 하더라도 중요한 의사 결정에는 사람 Gate를 남겨두는 것이 좋다.

---

15. 두 번째 Agent부터 조직도가 만들어진다

CEO 아래에 CTO를 만든다.

CEO
└── CTO

그 아래 개발 Agent를 만든다.

CEO
└── CTO
    └── iOS Developer

QA Agent도 추가한다.

CEO
└── CTO
    ├── iOS Developer
    └── QA Engineer

각 Agent는 정확히 하나의 Manager를 가진다.

Paperclip은 이 관계를 조직도로 관리한다.

이 구조가 중요한 이유는 Task Delegation 때문이다.

CEO

큰 목표
↓

CTO

개발 계획
↓

Developer

구현

모든 Agent가 사용자에게 직접 달려드는 구조를 피할 수 있다.

---

16. 처음부터 Agent를 많이 만들지 않는다

처음 Paperclip을 사용할 때 가장 흔히 하고 싶은 구성은 이런 것이다.

CEO

CTO

Product Manager

iOS Developer

Backend Developer

Frontend Developer

QA

Designer

Security Engineer

DevOps

Documentation Agent

보기에는 멋있다.

하지만 실제 운영에서는 Agent가 늘어날수록 다음도 늘어난다.

API 비용

Task 전달

Context

잘못된 Delegation

중복 작업

리뷰 과정

처음에는 세 명 정도로 충분하다.

CEO

Developer

Reviewer

개발 프로젝트라면 이것으로 시작하는 것이 좋다.

---

17. 실제 개발 프로젝트를 연결한다

Agent 조직을 만들었다면 이제 실제 Git Repository를 연결한다.

Paperclip에서는 Project와 Workspace를 사용한다.

예를 들어

Project

My iOS App

Workspace는 실제 Repository다.

cwd

/Users/me/Projects/MyApp

Repository URL은

https://github.com/company/my-ios-app.git

Base branch는

main

으로 설정한다.

구조는 다음과 같다.

Paperclip Project

My iOS App
     │
     └── Workspace
          ├── cwd
          ├── repoUrl
          └── repoRef: main

---

18. Agent별 Workspace보다 Project Workspace가 낫다

Repository 정보를 각 Agent마다 따로 설정할 수도 있을 것 같지만 Paperclip에서는 Project Workspace를 중심으로 관리하는 것이 좋다.

Project

MyApp
│
├── Developer Agent
├── Reviewer Agent
└── QA Agent

이 Agent들은 같은 Project Context를 공유한다.

Repository 위치를 Agent 설정마다 반복해서 넣을 필요가 없다.

---

19. Issue마다 별도의 Git Worktree를 만든다

여러 Agent가 같은 Repository를 동시에 수정하면 충돌이 발생할 수 있다.

그래서 Paperclip은 Issue별 isolated workspace를 구성할 수 있다.

Repository

main
│
├── PAP-101-feature
│
├── PAP-102-bugfix
│
└── PAP-103-test

각 Issue마다 Git Worktree가 생성된다.

예를 들어

MyApp/

.paperclip-worktrees/

├── PAP-101-workspace
├── PAP-102-workspace
└── PAP-103-workspace

Developer Agent A가 PAP-101을 수정하는 동안

Developer Agent B는 PAP-102를 수정할 수 있다.

서로 같은 working directory를 건드리지 않는다.

멀티 Agent 개발에서는 이 설정이 특히 중요하다.

---

20. 프로젝트에서 Isolated Workspace를 켠다

Project Workspace에서 실행 전략을

git_worktree

로 설정한다.

개념적으로는 다음과 같다.

{
  "executionWorkspacePolicy": {
    "enabled": true,
    "allowIssueOverride": true,
    "workspaceStrategy": {
      "type": "git_worktree",
      "baseRef": "main"
    }
  }
}

이렇게 하면 각 Task가 별도 branch와 worktree에서 실행된다.

Issue
→ Checkout
→ Worktree 생성
→ Branch 생성
→ Agent 실행

하나의 기본 checkout에서 Agent들이 동시에 수정하게 만드는 것보다 훨씬 안전하다.

---

21. Repository에 AGENTS.md를 둔다

Paperclip이 Task를 관리한다고 해서 코드 작업 규칙까지 자동으로 생기는 것은 아니다.

Repository에는 여전히 AGENTS.md가 유용하다.

예를 들어 iOS 프로젝트라면 다음처럼 작성한다.

# Development Rules

## Architecture

- 기존 MVVM 구조를 유지한다.
- View에서 API Client를 직접 호출하지 않는다.
- 공통 네트워크 코드는 Network 모듈을 사용한다.

## Scope

- Issue와 관련 없는 파일은 수정하지 않는다.
- 신규 외부 라이브러리는 승인 없이 추가하지 않는다.
- 프로젝트 설정 변경은 최소화한다.

## Validation

- 변경과 관련된 테스트를 실행한다.
- 실행하지 않은 테스트를 통과했다고 보고하지 않는다.
- 실패한 테스트가 있으면 원인을 Task에 기록한다.

## Git

- main에 직접 commit하지 않는다.
- 현재 Paperclip Issue branch를 사용한다.
- 작업 완료 후 commit한다.
- branch를 push한다.
- Pull Request를 생성한다.

Paperclip은 Agent에게 Task를 준다.

AGENTS.md는 Agent가 Repository 안에서 어떻게 행동할지를 정한다.

둘은 역할이 다르다.

---

22. GitHub CLI를 설치한다

Agent가 Pull Request까지 생성하게 하려면 GitHub CLI가 있으면 편하다.

Mac에서는

brew install gh

로그인 확인은

gh auth status

로 한다.

로컬 테스트 단계에서는 기존 gh auth login 인증을 사용할 수도 있다.

하지만 여러 Agent나 서버 환경에서는 Agent별 Token 또는 GitHub App 방식이 더 적합하다.

---

23. GitHub 인증은 Agent에게 최소 권한만 준다

개발 Agent가 필요한 GitHub 권한은 보통 다음 정도다.

Repository Contents

Read + Write

Pull Requests

Read + Write

Metadata

Read

Repository 하나만 사용하는 Agent라면 Fine-grained PAT의 Repository 범위를 해당 Repository 하나로 제한하는 것이 좋다.

큰 조직이라면 GitHub App 방식이 더 적합하다.

GitHub App을 사용하면 Agent가 특정 사람 계정에 의존하지 않고 독립된 Bot Identity로 PR을 만들 수 있다.

---

24. Agent에게 PR Workflow를 명확하게 지시한다

Developer Agent의 규칙에 다음 내용을 넣는다.

## PR Workflow

Never commit directly to main.

For every assigned issue:

1. Work only inside the Paperclip-provided worktree.
2. Make the smallest necessary change.
3. Run relevant tests.
4. Commit the changes.
5. Push the current branch.
6. Create a Pull Request.

Use:

gh pr create --fill --base main

After the PR is created:

- add the PR URL to the Paperclip issue
- report the tests that were executed
- move the task to in_review

If CI fails:

- do not merge
- fix the failure on the same branch
- push another commit
- update the issue

이제 Agent의 완료 기준이 명확해진다.

코드 작성

≠ 완료

PR 생성 + 검증

= 작업 제출

---

25. 이제 실제 Task를 만든다

예를 들어 앱에 다음 문제가 있다고 하자.

로그인 실패 시 서버 오류 메시지가
그대로 Alert에 노출된다.

Paperclip에서 Issue를 만든다.

Title:

로그인 실패 메시지를 사용자용 문구로 변경

Description:

로그인 실패 시 서버에서 전달한 원문을 그대로 노출하지 않는다.

AuthErrorMapper에서 사용자용 메시지로 변환한다.

조건:

- 인증 실패와 네트워크 실패를 구분한다.
- NetworkClient는 수정하지 않는다.
- 관련 테스트를 추가한다.
- 기존 public API는 변경하지 않는다.

Project:

My iOS App

Assignee:

iOS Developer

Priority:

Medium

Task를 생성한다.

---

26. Paperclip에서 실제로 무슨 일이 일어날까

Task가 Developer Agent에게 할당된다.

다음 Heartbeat에서 Agent가 깨어난다.

Task Assigned

        ↓

Heartbeat

        ↓

Codex 실행

Paperclip은 해당 Issue를 Checkout한다.

Isolated Workspace를 사용하고 있다면 별도 Worktree가 생성된다.

PAP-142-workspace

Agent는 그 안에서 Repository를 확인한다.

AuthErrorMapper.swift

LoginViewModel.swift

LoginViewModelTests.swift

필요한 코드를 수정한다.

테스트를 실행한다.

예를 들어

xcodebuild test \
  -scheme MyApp \
  -only-testing:MyAppTests/LoginViewModelTests

성공하면 commit한다.

git add -A
git commit -m "fix(auth): sanitize login error messages"

branch를 push한다.

git push -u origin HEAD

PR을 생성한다.

gh pr create --fill --base main

---

27. Paperclip Issue에 결과가 남는다

Agent가 작업을 끝내고 사라지는 것이 아니다.

Paperclip Task Thread에 결과를 남긴다.

예를 들어 다음처럼 구성할 수 있다.

PR

https://github.com/company/my-ios-app/pull/314

변경 내용

- AuthErrorMapper의 서버 원문 노출 제거
- 인증 실패 메시지 추가
- 네트워크 실패 메시지 분리
- LoginViewModelTests 테스트 추가

검증

xcodebuild test
-scheme MyApp
-only-testing:MyAppTests/LoginViewModelTests

Result

Passed

이제 Issue 상태를

in_review

로 변경한다.

---

28. GitHub와 Paperclip은 역할이 다르다

이 구조에서는 리뷰 화면이 두 개 생긴다.

GitHub

코드 자체를 검토한다.

Diff

CI

Inline Comment

Approval

Merge

Paperclip

작업 전체 흐름을 관리한다.

Task

Agent

Goal

Status

Approval

Cost

Audit Log

둘은 중복이 아니다.

예를 들어 GitHub에서는

이 코드가 맞는가?

를 본다.

Paperclip에서는

왜 이 Task가 만들어졌는가?

누가 맡았는가?

어떤 Agent가 처리했는가?

현재 프로젝트 Goal과 연결되어 있는가?

를 본다.

---

29. Reviewer Agent를 추가할 수도 있다

조금 더 자동화하고 싶다면 Reviewer Agent를 추가한다.

CEO

└── CTO
    ├── iOS Developer
    └── iOS Reviewer

흐름은 이렇게 된다.

Task
→ Developer
→ PR 생성
→ in_review
→ Reviewer Agent
→ Review

Reviewer에게는 수정 권한을 최소화하는 것이 좋다.

Developer
→ 코드 수정

Reviewer
→ 검토

Human
→ 최종 Merge

처음부터 Reviewer가 문제를 찾고 직접 코드를 고치고 Merge까지 하게 만들면 책임 경계가 약해진다.

---

30. CEO에게 Agent를 마음대로 늘리게 하면 안 된다

Paperclip에서는 CEO Agent가 새로운 인력이 필요하다고 판단할 수 있다.

예를 들어

현재 프로젝트에는 테스트 담당자가 필요합니다.

QA Engineer Agent 채용을 제안합니다.

하지만 바로 생성하는 것이 아니라 Approval Flow를 거치게 할 수 있다.

CEO

Hire QA Agent
        ↓
Approval
        ↓
Board

사람이 확인한다.

Role

Adapter

Budget

Responsibilities

Reports To

필요하면 승인한다.

이 구조를 통해 AI 조직이 스스로 무한히 Agent를 생성하는 상황을 막을 수 있다.

---

31. Budget는 반드시 처음부터 설정한다

Agent 조직을 처음 만들면 비용을 과소평가하기 쉽다.

Agent 한 명이 작업 하나를 수행할 때도 여러 번 모델을 호출할 수 있다.

Task 읽기

Repository 조사

코드 작성

테스트 오류 분석

수정

PR 작성

Agent가 여러 명이면 비용은 더 커진다.

그래서 Agent별 Budget을 설정한다.

예를 들어

CEO

Monthly Budget
$20

iOS Developer

Monthly Budget
$50

Reviewer

Monthly Budget
$20

Paperclip은 Agent별 비용과 전체 Company 비용을 추적한다.

현재 문서상 Budget 사용량이 한도에 가까워지면 경고하고, 한도에 도달하면 Agent를 중단시킬 수 있다.

처음에는 낮게 시작하는 것이 좋다.

---

32. Heartbeat도 너무 자주 돌리지 않는다

모든 Agent를 몇 분마다 깨울 필요는 없다.

Developer Agent라면 다음 이벤트만으로도 충분하다.

Task Assignment

Mention

Manual Run

Marketing Agent처럼 정기 작업이 필요할 때만 Schedule을 사용한다.

매일 오전

트렌드 조사

개발 Agent가 5분마다

새 일 있나?

를 확인하게 만들 이유는 없다.

Heartbeat 횟수는 곧 비용과 연결된다.

---

33. Agent Status를 보는 방법

Paperclip Dashboard에서는 Agent의 상태를 확인할 수 있다.

대표적으로

idle

working

blocked

같은 상태를 통해 현재 Agent가 무엇을 하고 있는지 파악한다.

Agent 상세 화면에서는 Run 기록도 볼 수 있다.

Agent

iOS Developer

Runs

Run #103
Run #104
Run #105

한 Run이 하나의 Heartbeat 실행 기록에 가깝다.

Agent가 이상하게 동작하면 Prompt만 다시 수정하기 전에 Run Transcript부터 보는 것이 좋다.

---

34. 작업이 안 될 때 가장 먼저 볼 곳

Agent에게 Task를 줬는데 아무 일도 하지 않는다면 다음 순서로 본다.

1. Heartbeat가 활성화되어 있는가

Agent가 idle 상태인 이유가 단순히 Heartbeat 비활성화일 수 있다.

2. Task가 실제 Agent에게 Assign 되었는가

담당자가 비어 있으면 아무도 가져가지 않는다.

3. Approval에서 막혀 있는가

CEO Strategy가 승인되지 않았다면 Task 실행이 진행되지 않을 수 있다.

4. Adapter 환경 검사가 성공하는가

Codex CLI가 설치되지 않았거나 인증이 없으면 Agent가 실행되지 않는다.

5. GitHub Token이 있는가

코드는 수정했는데 Push만 실패한다면 GitHub 인증 문제일 가능성이 높다.

6. gh CLI가 설치돼 있는가

gh --version

을 확인한다.

---

35. Codex Agent가 아무 출력 없이 멈추는 경우

Paperclip의 codex_local에는 출력 정체를 감지하는 Monitor가 있다.

Agent가 일정 시간 아무 출력도 만들지 않으면 멈춘 것으로 판단할 수 있다.

장시간 테스트처럼 정상적으로 긴 침묵이 발생하는 작업에서는 Timeout 설정을 조정할 필요가 있다.

하지만 무작정 Timeout을 끄는 것은 좋지 않다.

먼저 왜 Agent가 멈췄는지 확인한다.

Build가 멈췄는가

Test가 대기 중인가

Permission Prompt가 떴는가

네트워크 호출이 멈췄는가

Timeout은 마지막에 조정한다.

---

36. dangerouslyBypassApprovalsAndSandbox는 쉽게 켜지 않는다

Codex Adapter에는 강한 권한으로 자동 실행하기 위한 옵션이 있다.

이런 옵션은 편리해 보인다.

특히 완전 자동 Agent를 만들 때 켜고 싶어진다.

하지만 개발 Repository에서는 신중해야 한다.

Agent가 실행할 수 있는 명령에는 다음도 포함될 수 있다.

rm

git reset

git push

Package 변경

Build Script 변경

배포 명령

처음에는 Sandbox와 Approval을 유지한다.

Agent 동작이 충분히 검증된 작업만 점진적으로 자동화한다.

---

37. Paperclip의 좋은 운영 구조

개발 조직이라면 처음에는 다음 정도가 현실적이다.

Board
│
CEO
│
CTO
├── Developer
└── Reviewer

역할도 단순하게 한다.

CEO

Goal 관리

큰 Task 분해

우선순위 관리

Agent 증원 제안

CTO

기술 Task 정리

Architecture 판단

Developer 작업 검토

Developer

Repository 수정

테스트 실행

Commit

PR 생성

Reviewer

Diff 검토

Architecture 확인

테스트 누락 확인

사람은

Strategy 승인

고위험 변경 승인

최종 PR Merge

를 담당한다.

---

38. 처음에는 이것까지 자동화하지 않는 것이 좋다

Paperclip을 처음 설치하면 모든 과정을 자동화하고 싶어진다.

하지만 다음 작업은 사람 Gate를 유지하는 것이 좋다.

main Merge

Production Deploy

Database Migration

Signing 설정 변경

Secret 변경

새 Package 도입

Agent 신규 채용

Budget 크게 증가

낮은 위험의 반복 작업부터 자동화한다.

문서 수정

테스트 추가

작은 Bug Fix

리팩토링

PR 생성

코드 리뷰 초안

---

39. Local에서 시작하고 필요하면 서버로 옮긴다

처음에는 Mac에서 실행하는 것이 가장 쉽다.

Mac

Paperclip
Codex CLI
Git
GitHub CLI
Repository

구조가 안정되면 VPS나 내부 Server로 이동할 수 있다.

Paperclip은 Server Deployment도 지원한다.

Internet

Nginx
↓
Paperclip
↓
Agent Runtime
↓
Git Repository

서버로 옮길 때는 반드시 인증과 HTTPS를 사용해야 한다.

Paperclip 자체 Port 3100을 인터넷에 직접 노출시키는 방식은 피하는 것이 좋다.

---

40. 실제 사용 흐름을 한 번에 정리하면

처음 구축할 때는 다음 순서로 진행하면 된다.

1. Node.js 설치

2. Paperclip 설치

npx paperclipai onboard --yes

3. localhost:3100 접속

4. Company 생성

5. Company Goal 작성

6. CEO Agent 생성

7. Codex 또는 Claude Adapter 연결

8. CEO Heartbeat 실행

9. CEO Strategy 승인

10. Developer Agent 생성

11. Project 생성

12. Git Repository Workspace 연결

13. git_worktree 실행 전략 활성화

14. Repository에 AGENTS.md 작성

15. GitHub 인증 설정

16. Task 생성

17. Developer Agent에 Assign

18. Heartbeat 실행

19. Codex가 코드 수정

20. 테스트 실행

21. Commit

22. Push

23. GitHub PR 생성

24. Paperclip Issue를 in_review로 변경

25. Reviewer 또는 사람이 검토

26. Merge

27. Issue 완료

이 정도까지 연결되면 Paperclip을 단순히 구경한 것이 아니라 실제 개발 Agent 운영 환경을 만든 것이다.

---

41. Paperclip을 쓰면서 달라지는 점

기존에는 Codex를 이렇게 사용했다.

개발자
→ Codex
→ 작업 완료

Paperclip을 넣으면 구조가 바뀐다.

개발자

Board
│
CEO
│
CTO
│
Developer Agent
│
Codex
│
Git Repository

여기에 Task와 Budget, Approval, Run 기록이 붙는다.

Goal
↓
Task
↓
Agent
↓
Execution
↓
PR
↓
Review
↓
Done

Agent를 사용하는 것에서 Agent 조직을 운영하는 것으로 바뀌는 것이다.

---

42. 언제 Paperclip이 유용한가

다음과 같은 상황이라면 Paperclip을 써볼 만하다.

Codex Agent를 여러 개 운영하고 있다.

Claude와 Codex 역할을 분리하고 있다.

개발과 QA Agent를 나누고 싶다.

Agent가 어떤 Task를 하는지 한눈에 보고 싶다.

AI 사용 비용을 Agent별로 관리하고 싶다.

Agent가 중요한 결정을 하기 전에 승인받게 하고 싶다.

밤에 Agent에게 여러 Task를 맡기고 다음 날 결과를 확인하고 싶다.

반대로 Agent 하나를 가끔 사용하는 정도라면 Paperclip이 오히려 무거울 수 있다.

Developer
→ Codex

만으로 충분하다.

Paperclip의 장점은 Agent 자체의 능력이 좋아지는 데 있는 것이 아니다.

여러 Agent를 운영할 때 관리 복잡도를 낮추는 데 있다.

---

43. 개발자가 왜 Paperclip을 알아야 할까

AI 코딩 도구는 빠르게 Agent 형태로 변하고 있다.

예전에는

자동완성

이었다.

그다음은

채팅

이었다.

지금은

Agent

Repository 수정

Tool 실행

Test

PR

까지 간다.

Agent가 하나일 때는 IDE에서 직접 관리할 수 있다.

하지만 Agent가 늘어나면 기존 소프트웨어 조직에서 보던 문제가 그대로 나타난다.

업무 배분

역할 분리

승인

비용

상태

실패 관리

감사 로그

권한

Paperclip이 흥미로운 이유는 새로운 모델을 만들기 때문이 아니다.

이 문제를 AI 모델 문제가 아니라 조직 운영 문제로 보고 있기 때문이다.

---

44. 마무리

Paperclip은 Codex나 Claude Code를 대신하지 않는다.

오히려 그 위에 올라간다.

Paperclip
→ 조직과 업무 관리

Codex
→ 실제 코드 작업

GitHub
→ 코드 리뷰와 Merge

실제 개발 흐름은 이렇게 만들 수 있다.

Company Goal

→ CEO Strategy

→ Task 생성

→ Developer Agent

→ Codex

→ Isolated Git Worktree

→ Code 수정

→ Test

→ Commit

→ Pull Request

→ Review

→ Merge

여기서 중요한 것은 Agent 수를 늘리는 것이 아니다.

역할을 분리하고, 작업 범위를 명확하게 하고, 사람의 승인 지점을 남기고, 비용과 실행 결과를 추적할 수 있게 만드는 것이다.

처음에는

CEO
Developer
Reviewer

세 명 정도면 충분하다.

작은 Bug Fix 하나를 실제 Repository에 맡겨보고,

Task
→ Code
→ Test
→ PR

이 흐름이 안정적으로 돌아가는지 확인하는 것부터 시작하는 것이 좋다.

한 줄로 정리하면 이렇다.

Codex가 AI 개발자라면,
Paperclip은 그 개발자를 고용하고 일을 배정하고 비용과 결과를 관리하는 시스템이다.

AI Agent가 한 명을 넘어 팀 단위로 늘어나기 시작한다면, 앞으로 개발자가 고민해야 하는 것은 좋은 Prompt만이 아니다.

Agent를 어떤 조직 구조로 운영하고, 어떤 권한과 예산을 주고, 어떤 과정으로 실제 코드까지 안전하게 전달하게 만들 것인가다.