Paperclip：無料でAIをソフトウェア開発チームに変えるツール

ほとんどの開発者が、複数のAIエージェントを運用するときに、5番目のエージェントで同じ障害に突き当たります。ある端末ではClaude Codeがバックエンドのサービスを書き換え、別の端末ではCodexがテストスイートを作成し、Cursorがコンポーネントを修正し、ほかの3つのタブは忘れられたままです。誰が何をしているのか誰も分かりません。コストが跳ね上がります。作業が重複するエージェントが2体あります。明確な目的がないため、あるエージェントが6時間動いても成果が出ません。

Apidogを今すぐ試す

Paperclipはこの問題を解決します。Paperclipはオープンソースのコードオーケストレーション基盤で、バラバラのAIエージェントを、構造化された一つの会社に変えます。組織図、役割、タスク管理、予算の制限、監査ログです。Paperclipは3週間でGitHubの35,000以上のスターを獲得しており、コミュニティからの実需要があることを証明しています。

この記事では、最初のエージェント企業をセットアップし、組織化し、運用して、各端末を手動で逐一監視しなくてもAIエージェントが効率的に働けるようにする方法を案内します。

Paperclipとは何か（そして何ではないか）

インストールする前に、使う製品を理解してください。

Paperclipはオーケストレーション層です。エージェントを調整・追跡し、予算を管理し、目標の文脈を提供します。つまり、エージェントを構築することでも、AI提供元を置き換えることでも、チャットUIを追加することでもありません。

Paperclipチームの言葉：「Claude Codeが社員なら、Paperclipは会社だ」。

つまり:

• エージェントには役割があります（単なるプロンプトではありません）
• タスクにはオーナーがいます（端末を開いた人ではありません）
• 予算には固定の上限があります（感覚ではありません）
• すべてに監査証跡が残ります

PaperclipはClaude Code、OpenAI Codex、Cursor、Gemini CLI、そしてWebhookまたはheartbeatを受け取れる任意のエージェントで動作します。エージェントを用意し、Paperclipがオーケストレーションします。

Paperclipは次のものではありません:

• チャボットのUI
• n8n/Zapierのようなドラッグ＆ドロップのワークフロー用ツール
• エージェントを作るためのフレームワーク
• エージェントが1体だけのケースで有用

エージェントを1体だけ動かすなら、Paperclipは過剰です。3体以上を運用するなら、ここが欠けていたピースです。

Paperclipのインストール

要件: Node.js 20+、pnpm 9.15+。Paperclipには組み込みのPostgreSQLが付属しており、別途DBのセットアップは不要です。

クイックスタート:

npx paperclipai onboard --yes

上記のコマンドはCLIをダウンロードし、デフォルト設定でonboardingを実行し、ポート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が使われ、ログインは不要です。ユーザーは「Board」を使用します。アカウントを作成せずに、すぐにダッシュボードを利用できます。

ヘルスチェック:

paperclipai doctor

インストールの自動修復:

paperclipai doctor --repair

最初の会社のセットアップ

Paperclipでは「会社」は、エージェント、タスク、目標、予算のための最上位コンテナです。各メンバーが役割と明確な報告がある1つのAIエージェントであるプロジェクトだと考えてください。

ダッシュボードから新しい会社を作成し、ミッションステートメントを設定します。これはすべてのタスクのための文脈になります。エージェントはなぜやるのかを理解し、何をやるのかだけではありません。これは長時間の実行にとって重要です。

ミッション例:

「顧客の注文を管理するREST APIを構築し、維持する。速度よりも正確性を優先する。公開するすべてのエンドポイントを記録する。」

最初のエージェントを追加

各エージェントには、AIツールのセットと通信方式を定義するアダプタがあります。

サポートされているアダプタ一覧:

CLIでClaude Codeエージェントを追加:

paperclipai agent local-cli "Backend Engineer" --company-id <id-công-ty>

このコマンドはエージェントを起動し、スキルを~/.claude/skillsにセットアップし、API認証情報を作成します。エージェントは組織図に表示され、タスクを受け取ります。

Claudeエージェントの設定:

コストを節約するために役割ごとにモデルを分ける:

• CEO/オーケストレーション: Sonnet（高コストだが妥当）
• マネージャー: Haiku（安くて速い）
• プログラミング/ICの創造性: Sonnet（重要な品質）
• フォーミュラIC: Haiku（サンプルコード作成、テスト、マイグレート）

この分け方により、Sonnetをどこでも常に動かす場合と比べて、毎月の支出を40〜60%削減しつつ、品質は確実に維持できます。

エージェント組織の構造

小規模なソフトウェアプロジェクトの例としての構造：

CEO（Sonnet）
 ├── CTO（Haiku）
 │    ├── バックエンドエンジニア（Sonnet）
 │    ├── フロントエンドエンジニア（Sonnet）
 │    └── QAエンジニア（Haiku）
 └── 技術ドキュメント作成担当（Haiku）

CEOはミッションを目標に分解します。CTOは目標をエンジニアへ配布します。エンジニアが実行します。QAがテストします。Writerがドキュメントを書きます。

各エージェントには heartbeatの間隔（タスクを確認・実行・休止する頻度）があります。常時稼働ではありません：寝る→起きる→作業する→寝る。これによりコストを低く抑えられます。

推奨の間隔：

• プログラミング：600秒（10分）
• リクエスト対応：86,400秒（1日）＋リクエストによる起床
• 最小の安全：30秒（低すぎるとコスト超過＆スパムになりやすい）

Heartbeatはどのように動作するか

エージェントが起きるたびに、9ステップの手順を実行します：

1. GET /api/agents/me による認証
2. 承認待ちのコールバックを処理
3. GET /api/companies/{companyId}/issues からタスクを取得
4. 優先順位：いま作業中のタスクを先に、その後に新しいタスク；ブロックされているtaskはスキップ
5. タスクをチェックアウト：POST /api/issues/{issueId}/checkout（他のエージェントが既に取得していたらスキップ）
6. コンテキストとコメントを読む
7. 作業を実行する
8. コメントと新しい状態でタスクを更新する
9. 必要に応じてサブタスクを委任（parent & goal ID）

ステップ5が重複を防ぎます：2つのエージェントが同じタスクを受け取ることはできません。タスクがすでに取得されている場合、2番目のエージェントはスキップします。

Paperclipは、heartbeatごとに環境変数を通じてコンテキストを渡します：

PAPERCLIP_TASK_ID          # 今回の実行で起動したタスク
PAPERCLIP_WAKE_REASON      # 起床の理由（time, mention, assignment）
PAPERCLIP_AGENT_ID         # エージェントID
PAPERCLIP_API_URL          # PaperclipのAPIコールバックURL

エージェントはこれらの変数を使って、更新・サブタスク作成・承認依頼・委任を、すべて1つのheartbeatの中で行います。

タスクの作成 & 作業の追跡

Paperclipのタスク＝GitHub Issue＋プロジェクト管理です。

CLIからタスクを作成：

paperclipai issue create \
  --company-id <id> \
  --title "受注エンドポイントにページネーションを追加する" \
  --assignee-agent-id <id-backend>

タスクには以下のようなものがあります：

• 親タスク： 大きすぎるタスクを分割する
• 目標とのリンク： 会社の目標を把握できる
• コメント： コンテキストの提供、承認、更新
• @-mention： heartbeatを待たずに、即座にエージェントを起こす

オープン中のタスク一覧を表示：

paperclipai issue list

または、オーナー情報、状態、最後のheartbeatの時刻といった情報つきで、ダッシュボード上で直接確認できます。

効果的な予算管理

重要な機能：各エージェントには月次のトークン予算があります。80%に達するまでは重要なタスクだけを実行。100%に達すると一時停止します。

予算の設定： エージェント設定で構成します。提案：$20〜50/月/ロール。usage（利用量）、heartbeatあたりのコスト、ダッシュボードでの総支出を追跡します。

ダッシュボードは、効果のある／問題があるエージェントを見極めるのに役立ちます。heartbeatあたりのコストが増える場合、たいていはプロンプトが曖昧か、タスクの範囲が広すぎることが原因です。より厳密に割り当て直して、予算は増やしません。

もし管理しなければ、30秒のインターバル＋Extended Thinkingによって、間違った設定のエージェントが数時間で数百ドルを燃やす可能性があります。Paperclipはそれを自動的に防ぎます。

実行時スキル：再トレーニングなしでエージェントに新しい手順を教える

強力な機能：スキルのインジェクション。エージェントが動作すると、Paperclipのアダプタが、スキルディレクトリ内のファイル SKILL.md へのシンボリックリンクを作成し、それを--add-dirで渡します。エージェントはスキルをコンテキストとして読み、手順に従います。

手順はMarkdownで教えるだけです—プロンプトを書き直す必要も、再デプロイする必要もありません！

スキルの例：

# スキル：データベースをマイグレーションする

マイグレーションを作成するとき：
1. 既存のマイグレーションファイルは絶対に変更しない
2. 説明的な名前を使う：YYYYMMDD_モトータ.sql
3. 上りSQLと下りSQLを含める
4. コミットする前にローカルで確認する
5. ビジネス上の理由を説明するコメントを追加する

スキルディレクトリに保存し、バックエンドのエージェントに割り当てます。以後のすべてのheartbeatは、この手順に従います。

エージェントが作ったAPIを検証するなら

エージェントのバックエンドがAPIを構築したら、素早くテストする必要があります。Apidogは自然な選択です：API設計、モックサーバー、そして自動テスト—オールインワンです。バックエンドのエージェントがエンドポイントを送ってくれたら、すぐに検証でき、Swagger、Postman、モック用のツール間での切り替えは不要です。

OpenAPI specからテストスイートを自動生成し、エージェントの出力で実行して、結果をタスクのコメントとして返すことができます。エージェントは受け取った後、次のheartbeatでエラーを修正します。コード→テスト→修正のループが完全に自動化されます。

ApidogはREST、GraphQL、gRPCをサポートし、無料で開始できます。

複数バージョンの管理

Paperclipは、環境変数PAPERCLIP_INSTANCE_IDまたはフラグ--instanceを通じて、複数の独立したインスタンスをサポートします。各インスタンスには独自のconfig、DB、ポート、workspaceがあります。

各gitブランチごとにdev用のworktreeを作成：

paperclipai worktree:make feature/orders-pagination

そのブランチ専用に、ポート、config、DBが分離されています。新しいコードを試すための実験用会社を、productionに影響を与えずに動かすことができます。完了したら、削除するだけで痕跡は残りません。

効果的なマルチエージェント構成モデル

Paperclipに慣れたあとで使える実践的なモデルの例：

• 目的の滝（Thác mục tiêu）： まず会社レベルの目的を書く。CEOのエージェントがそれをプロジェクトの目的に分解し、マネージャーがそれをタスクに落とし込みます。エージェントは目的の連鎖を理解でき、バラバラな指示を受けるよりも良い仕事ができます。
返却形式: {"translated": "翻訳されたHTML"}
• 承認ゲート： production/staging/決済に触れるすべての操作には、承認ゲートの設定が必要です。エージェントは一時停止し、通知を送信し、あなたが承認するまで待ってから再開します。コストのかかる事故を防ぎます。
• @メンションによるオンデマンド起動： heartbeat のインターバルを遅めに設定し、必要なときにメンションでエージェントを起こします。素早い応答と、継続的なトークンポーリングによる無駄を削減します。
• 分離されたワークスペース： 各エージェントには、workspaces/<agent-id>/ の下に個別のディレクトリを用意します。ワークスペースを共有しない方がよいです。衝突が起きやすいためです。分離はデフォルトです。ぜひ活用してください。

起動はわずか約15分から

オンボーディングの手順は15分未満：1つのインストールコマンド、サーバーの起動までです。最初のエージェントを追加し、タスクを作成するのに追加で5分だけかかります。

難しいのは、うまく機能する会社の構造を作ることです。明確なミッションを書き、各ロールに合ったモデルを選び、適切な予算上限を設定します。30分かけて丁寧にセットアップすれば、「とりあえず繋いで終わり」と比べて、エージェントの効果は際違いに高くなります。

もし、どんなプロジェクトでも2つ以上のAIエージェントを動かしているなら、午後の1コマを使ってセットアップしましょう。各エージェントをそれぞれ別のターミナルで動かすことと、図・予算・タスクの所有権・監査ログ…を備えた会社を作ることの違いは、単なるサイドプロジェクトと、監視なしで自走できるシステムの違いです。