AIエージェントをソフトウェアチームに変える無料ツール「Paperclip」

複数のAIエージェントを実行しているほとんどの開発者は、エージェントが5台目あたりで同じ壁にぶつかります。あるターミナルではClaude Codeがバックエンドサービスを書き換え、別のターミナルではCodexがテストを生成し、Cursorがコンポーネントを編集し、他にもチェックするのを忘れたタブが3つあります。誰もが他の誰が何をしているのか分かりません。コストは増大し、2つのエージェントが同じ作業を重複して行います。1つは6時間実行されたものの、誰も明確な目標を与えなかったため、何も有用なものを生み出しませんでした。 Paperclipはこれを解決します。これは、散らばったAIエージェントを、組織図、割り当てられた役割、タスク管理、予算制限、監査ログが完備された構造化された会社に変えるオープンソースのオーケストレーションプラットフォームです。公開から3週間足らずで35,000以上のGitHubスターを獲得しました。これは、どれだけの開発者が同じ不満を抱えていたかを示しています。 ボタン この記事では、Paperclipのセットアップ、最初のエージェント会社の構築、そして、あなたがすべてのターミナルを監視することなく実際に作業を進める方法を説明します。

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

何かをインストールする前に、何が得られるのかを理解してください。 Paperclipは**オーケストレーションレイヤー**です。エージェントを調整し、その作業を追跡し、予算を管理し、会社の目標に関するコンテキストを与えます。エージェントを構築したり、AIプロバイダーを置き換えたり、チャットインターフェースを追加したりするものではありません。

Paperclipチームが使用するメンタルモデルは、「Claude Codeが従業員なら、Paperclipは会社である」というものです。 つまり、次のようになります。 *   エージェントにはプロンプトだけでなく**役割**がある *   タスクには開かれたターミナルだけでなく**所有者**がいる *   予算には雰囲気だけでなく**厳格な制限**がある *   すべてが**監査証跡**に記録される PaperclipはClaude Code、OpenAI Codex、Cursor、Gemini CLI、そしてWebhookまたはハートビート信号を受信できるあらゆるエージェントと連携します。エージェントはあなたが用意します。Paperclipが会社を運営します。 明示的に次のものではありません。 *   チャットボットUI *   n8nやZapierのようなドラッグ＆ドロップのワークフロービルダー *   エージェントを作成するためのフレームワーク *   単一エージェントのユースケースに有用なもの たまに1つのAIエージェントを実行するだけなら、Paperclipは過剰です。継続的な作業で3つ以上のエージェントを実行しているなら、Paperclipは欠けているピースです。

Paperclipのインストール

Node.js 20+、pnpm 9.15+が必要です。Paperclipには組み込みのPostgreSQLデータベースが付属しているため、外部ストレージを設定する必要はありません。 **最速の開始方法:** ```bash npx paperclipai onboard --yes ``` これにより、CLIがダウンロードされ、適切なデフォルト設定でオンボーディングが実行され、サーバーがポート3100で起動します。`http://127.0.0.1:3100`を開くとダッシュボードが表示されます。 **貢献したり、コードを掘り下げたりしたい場合:** ```bash git clone https://github.com/paperclipai/paperclip.git cd paperclip pnpm install pnpm dev ``` **Dockerがお好みの場合:** ```bash 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//  — エージェントごとの作業ディレクトリ ``` ローカルモードでは、デフォルトで`local_trusted`認証を使用します。これによりログインがスキップされ、合成的な「Board」ユーザーが使用されます。すぐにダッシュボードを使い始めることができ、アカウント作成は不要です。 ログイン後、ヘルスチェックを実行してください。 ```bash paperclipai doctor ``` 何か設定が間違っている場合は、`--repair`でほとんどの問題が自動的に修正されます。 ```bash paperclipai doctor --repair ```

最初の会社のセットアップ Paperclipでは、「会社」はエージェント、タスク、目標、予算のトップレベルコンテナです。プロジェクトと考えることができますが、すべてのプロジェクトメンバーは役割と報告ラインを持つAIエージェントです。 ダッシュボードから新しい会社を作成し、ミッションステートメントを与えてください。これは飾りではありません。エージェントが受け取るすべてのタスクは会社ミッションに遡及するため、エージェントは「何をすべきか」だけでなく「なぜその作業をするのか」というコンテキストを持ちます。これは、より長いエージェント的実行での意思決定にとって重要です。 簡単なミッションの例：「顧客注文管理のためのREST APIを構築および維持する。速度よりも正確性を優先する。すべての公開エンドポイントを文書化する。」 この1つのステートメントが、エージェントが下すすべての決定に対するフィルターを与えます。

最初のエージェントの追加 Paperclipの各エージェントには、使用するAIツールと通信方法を定義する**アダプター**があります。 標準でサポートされているアダプター：

CLI経由でClaude Codeエージェントを追加するには： ```bash paperclipai agent local-cli "Backend Engineer" --company-id ``` これにより、エージェントがブートストラップされ、そのスキルが`~/.claude/skills`にインストールされ、APIクレデンシャルが生成されます。エージェントは会社の組織図に存在し、タスクの割り当てを受けられるようになります。 **Claudeエージェントの設定**（UIまたはエージェントごとの設定で設定）：

**役割ごとのモデル割り当て**は、開始する前に検討する価値があります。すべてのエージェントでOpusを実行すると、すぐに費用が高くなります。実用的な分割は次のとおりです。 *   **CEO / オーケストレーションエージェント:** Sonnet（戦略的推論、費用対効果が高い） *   **マネージャーエージェント:** Haiku（ルーティングと委任、安価で高速） *   **クリエイティブ / コーディングIC:** Sonnet（ここでは出力品質が重要） *   **定型的なIC:** Haiku（ボイラープレート生成、テストの足場、移行） この割り当てにより、Sonnetをすべてに適用する場合と比較して、ルーチンタスクでの意味のある品質低下なしに、月間のエージェント費用を40〜60%削減できます。

エージェント組織の構築 小規模なソフトウェアプロジェクト向けの機能する構造は次のとおりです。 ``` CEO (Sonnet) ├── CTO (Haiku) │    ├── バックエンドエンジニア (Sonnet) │    ├── フロントエンドエンジニア (Sonnet) │    └── QAエンジニア (Haiku) └── テクニカルライター (Haiku) ``` CEOエージェントはミッションを保持し、それを目標に分解します。CTOは目標をエンジニアリングエージェントにルーティングします。エンジニアは作業を行います。QAは検証します。ライターは文書化します。 各エージェントには**ハートビート間隔**があり、これはエージェントが目を覚まし、割り当てられたタスクをチェックし、作業を行い、終了する頻度です。エージェントは継続的に実行されません。目を覚まし、実行し、休止します。これがコスト増大を防ぎます。 推奨される間隔： *   コーディングエージェント：600秒（10分） *   オンデマンドエージェント：86,400秒（1日1回）でウェイクオンデマンドを有効にする *   最小安全間隔：30秒（これより短いとコスト超過やスパムのリスクがあります）

ハートビートの仕組み ハートビートモデルを理解することは、エージェントから信頼性の高い作業を得るための鍵です。 エージェントが目を覚ますたびに、9段階のプロトコルに従います。 1.  `GET /api/agents/me`を介して本人確認を行う 2.  保留中の承認コールバックを処理する 3.  `GET /api/companies/{companyId}/issues`から割り当てられたタスクを取得する 4.  優先順位付け：進行中のタスクを最初に、次にToDoタスク。ブロックされたタスクは、ブロック解除できる場合を除きスキップする。 5.  `POST /api/issues/{issueId}/checkout`を介してタスクをチェックアウトする（他のエージェントが既に取得している場合、応答は409となり、このエージェントは次のタスクに進む） 6.  タスクの完全なコンテキストとコメントスレッドを読む 7.  作業を行う 8.  コメントとステータスの変更でタスクを更新する 9.  必要に応じて、親IDと目標IDを使用してサブタスクを委任する ステップ5のチェックアウトメカニズムは、作業の重複を防ぐものです。2つのエージェントが同じタスクを拾うことはできません。1つが作業中であれば、もう1つは自動的にスキップします。 Paperclipは、環境変数を通じてすべてのエージェント実行にコンテキストを注入します。 ```bash PAPERCLIP_TASK_ID          # この実行をトリガーしたタスク PAPERCLIP_WAKE_REASON      # エージェントが目を覚ました理由（タイマー、メンション、割り当て） PAPERCLIP_AGENT_ID         # エージェントのID PAPERCLIP_API_URL          # PaperclipのAPIにコールバックするためのURL ``` エージェントはこれらを使用して、更新の投稿、サブタスクの作成、承認要求、委任をすべて1つのハートビート内で行うことができます。

タスクの割り当てと作業の追跡 Paperclipのタスクは、GitHubのIssueとプロジェクト管理ツールを組み合わせたようなものです。UIまたはCLIから作成します。 ```bash paperclipai issue create \ --company-id  \ --title "注文エンドポイントにページネーションを追加" \ --assignee-agent-id ``` タスクには次のものを持たせることができます。 *   大規模な作業をサブタスクに分解するための**親タスク** *   エージェントがこのタスクがどの会社の目標に役立つかを知るための**目標リンク** *   コンテキスト、承認要求、ステータス更新のための**コメント** *   特定の**エージェントをオンデマンドで起こす**ための@-メンション（次のハートビートを待つ必要なし） CLIからすべての未処理タスクを表示できます。 ```bash paperclipai issue list ``` またはダッシュボードで、タスクの現在の所有者、ステータス、最後に触れたハートビートの実行が表示されます。

実際に機能する予算管理 これはPaperclipの最も有用な機能の1つであり、マルチエージェント設定に不慣れな人には最も見過ごされがちです。 各エージェントには月間トークン予算が与えられます。80%に達すると、エージェントは自動的にクリティカルなタスクのみにシフトします。100%に達すると、完全に一時停止します。 エージェント設定で予算を設定します。コミュニティが推奨する開始点は、エージェント層ごとに月額20〜50ドルです。ダッシュボードから、エージェントごとの消費率、ハートビートごとのコスト、累積月間費用をすべて追跡できます。 コストダッシュボードは、どのエージェントが効率的で、どのエージェントが的を絞らない作業でトークンを消費しているかを示します。エージェントのハートビートごとのコストが上昇している場合、通常、プロンプトが曖昧すぎるか、タスクのスコープが広すぎる兆候です。予算を上げるのではなく、割り当てを厳しくすることで修正します。 予算管理がない場合、Extended Thinkingが有効で30秒間隔で実行される誤設定されたエージェントは、気づく前に何百ドルもの費用を使い果たす可能性があります。Paperclipはそれを自動的に防ぎます。

ランタイムスキル：再トレーニングなしでエージェントに新しいワークフローを教える Paperclipのより強力な機能の1つは**スキル注入**です。エージェントが実行されるとき、Paperclipのアダプターはエージェントの構成ディレクトリ内の`SKILL.md`ファイルへのシンボリックリンクを作成し、それらを`--add-dir`を介して渡します。エージェントはスキルファイルをそのコンテキストの一部として読み取り、ワークフローに従います。 これは、コミットメッセージの書き方、データベース移行の処理方法、APIドキュメントのフォーマット方法など、新しいプロセスをMarkdownファイルを記述することでエージェントに教えることができることを意味します。プロンプトの書き換えは不要です。再デプロイも不要です。 あなたはスキルを作成します： ```markdown # SKILL: データベース移行 移行を作成する際には： 1. 既存の移行ファイルを決して変更しない 2. 記述的な名前を使用する: YYYYMMDD_description.sql 3. upとdownの両方のSQLを含める 4. コミットする前にローカルでテストする 5. 変更のビジネス上の理由を説明するコメントを追加する ``` スキルをスキルディレクトリに保存し、バックエンドエージェントに割り当てると、将来のすべてのハートビートがそのプロセスに従います。

エージェントによって構築されたAPIをテストする場合 エージェントがAPIを構築している場合、生成されたものを迅速にテストする方法が必要です。Apidogはここに自然にフィットします。API設計、モックサーバー、自動テストをすべて1か所で処理するため、バックエンドエージェントがエンドポイントを公開すると、Swagger、Postman、および別のモックツールを切り替えることなく、すぐにそれを検証できます。

OpenAPI仕様からテストスイートを自動生成し、エージェントの出力に対して実行し、結果をタスクコメントとしてフィードバックできます。エージェントは次のハートビートでそれを受け取り、失敗を修正します。コードからテスト、修正までの完全なループは、人間の介入なしに実行されます。 ApidogはREST、GraphQL、gRPCをサポートしており、無料で開始できます。

複数のインスタンスの管理 Paperclipは、`PAPERCLIP_INSTANCE_ID`環境変数または`--instance`フラグを介して、1台のマシン上で複数の隔離されたインスタンスをサポートします。各インスタンスは独自の構成、データベース、ポート、ワークスペースを持ちます。 ローカル開発の場合、worktreeコマンドはgitブランチごとに完全に隔離された開発インスタンスを作成します。 ```bash paperclipai worktree:make feature/orders-pagination ``` これにより、そのブランチにスコープされた個別のポート、設定、およびデータベースが提供されます。本番エージェント設定に触れることなく、フィーチャーコードに対してテスト会社を実行できます。完了したら、それを破棄するとなくなります。

機能するマルチエージェント設定 基本的な設定が実行されたら、うまく機能するいくつかのパターンを紹介します。 **目標カスケード:** 会社レベルで1つの高レベル目標を設定し、CEOエージェントにそれをプロジェクト目標に分解させ、各マネージャーエージェントにそれらをタスクに分解させます。エージェントは、孤立した指示を受け取るよりも、目的の連鎖を理解している方が良い仕事をします。 **承認ゲート:** 本番、ステージング環境、または課金に影響するエージェントのアクションには、承認ゲートを設定します。エージェントは一時停止し、通知を送信し、続行する前に承認を待ちます。これにより手動ステップが1つ追加されますが、コストがかかる前に問題を捕捉できます。 **@-メンションによるオンデマンド起動:** 高速なハートビート間隔（それに伴うトークンコスト）の代わりに、エージェントを遅い間隔に設定し、タスクコメントで@-メンションを使用して、必要なときにすぐに起動させます。重要な作業に対して高速な応答時間を得られ、継続的なポーリングの費用を支払う必要がありません。 **エージェントごとのワークスペース分離:** 各エージェントは、`workspaces//`の下に独自の作業ディレクトリを持ちます。これらをきれいに保ちましょう。ワークスペースを共有するエージェントは互いの作業を妨げます。分離は組み込まれています。それに逆らわないでください。

始めるまでにかかる時間は約15分 初めてのオンボーディングは15分以内に完了します。1つのコマンドでサーバーをインストールして起動します。最初のエージェントを追加し、タスクを作成するには、ダッシュボードでさらに5分かかります。 より難しいのは、会社をうまく構造化することです。明確なミッションを書き、各役割に適切なモデルを選択し、妥当な予算制限を設定することです。作業を割り当て始める前に30分間これに費やすと、すべてを迅速に設定して最善を尽くすよりも、エージェントははるかに良い結果を生み出すでしょう。 もしあなたがすでに進行中のプロジェクトで2つ以上のAIエージェントを実行しているなら、これは午後のセットアップに費やす価値があります。エージェントごとのターミナルタブと、予算管理、タスク所有権、監査ログを備えた構造化された会社との違いは、サイドプロジェクトと実際に監視なしで実行できるものの違いです。