paperclip-dev

Paperclip の開発

このスキルでは、ローカルの Paperclip インスタンスを開発、運用するための日常的なワークフローを扱います。origin が [email protected]:paperclipai/paperclip.git を参照する Paperclip リポジトリのチェックアウト内で作業していることを前提とします。

オープンソースの衛生管理： このリポジトリは一般公開されています。origin にプッシュするものはすべて公開可能なものとして扱ってください。秘密情報、API キー、トークン、非公開ログ、個人を特定できる情報（PII）、顧客データ、または非公開にしておくべきマシン固有の設定を、絶対にコミットまたはプッシュしないでください。Git の履歴も整理された状態に保ちましょう。使い捨てのブランチ、ノイズの多いチェックポイントコミット、上流に共有する必要のない推測に基づく作業をプッシュしないでください。

必須： CLI コマンドの実行、ビルド、テスト、またはワークツリーの管理を行う前に、Paperclip リポジトリ内の doc/DEVELOPING.md を必ず読んでください。これは、すべての paperclipai CLI コマンドとそのオプション、ビルド／テストのワークフロー、データベース操作、ワークツリー管理、診断に関する正式なリファレンスです。フラグやオプションを推測してはいけません。まずドキュメントを読んでください。

コマンドのクイックリファレンス

以下は、最も一般的なコマンドです。すべてのオプション表と詳細については、doc/DEVELOPING.md を参照してください。

タスク	コマンド
サーバーを起動（初回または通常時）	npx paperclipai run
ホットリロード付きの開発モード	pnpm dev
開発サーバーを停止	pnpm dev:stop
ビルド	pnpm build
型チェック	pnpm typecheck
テストを実行	pnpm test
マイグレーションを実行	pnpm db:migrate
Drizzle クライアントを再生成	pnpm db:generate
データベースをバックアップ	npx paperclipai db:backup
ヘルスチェック	npx paperclipai doctor --repair
環境変数を表示	npx paperclipai env
エージェントのハートビートをトリガー	npx paperclipai heartbeat run --agent-id <id>
エージェントのスキルをローカルにインストール	npx paperclipai agent local-cli <agent> --company-id <id>

master からの取得

git fetch origin && git pull origin master
pnpm install && pnpm build

スキーマに変更が入った場合は、pnpm db:generate && pnpm db:migrate も実行してください。

ワークツリー

Paperclip のワークツリーでは、Git ワークツリーと分離された Paperclip インスタンスを組み合わせています。それぞれに独自のデータベースとサーバーポートが割り当てられ、プライマリインスタンスの環境を基に初期設定されます。

必須： ワークツリーを作成または管理する前に、doc/DEVELOPING.md の「Worktree-local Instances」と「Worktree CLI Reference」のセクションを必ず読んでください。これらは、すべてのワークツリーコマンドとそのオプション、シードモード、環境変数に関する正式なリファレンスです。

ワークツリーを使用する場合

• 独自の Paperclip 環境が必要な機能ブランチを開始するとき
• プライマリインスタンスに影響を与えずに、エージェントの作業を並行して実行するとき
• マージ前に Paperclip の変更を分離環境でテストするとき

コマンドの概要

CLI には 2 つの階層があります（すべてのオプション表については doc/DEVELOPING.md を参照してください）。

コマンド	用途
worktree:make <name>	ワークツリーと分離インスタンスを一度に作成
worktree:list	ワークツリーとそれぞれの Paperclip の状態を一覧表示
worktree:merge-history	ワークツリー間の課題履歴をプレビュー／インポート
worktree:cleanup <name>	ワークツリー、ブランチ、インスタンスデータを削除
worktree init	既存のワークツリー内にインスタンスを初期設定
worktree env	ワークツリーインスタンス用のシェルのエクスポート設定を表示
worktree reseed	別のインスタンスからワークツリーの DB を更新
worktree repair	壊れた、または欠落したワークツリーのインスタンスメタデータを修復

典型的なワークフロー

# 1. Create a worktree for a feature
npx paperclipai worktree:make my-feature --start-point origin/main

# 2. Move into the worktree (path printed by worktree:make) and source the environment
cd <worktree-path>
eval "$(npx paperclipai worktree env)"

# 3. Start the isolated Paperclip server
npx paperclipai run

# 4. Do your work

# 5. When done, merge history back if needed
npx paperclipai worktree:merge-history --from paperclip-my-feature --to current --apply

# 6. Clean up
npx paperclipai worktree:cleanup my-feature

フォーク — ユーザーフォークへのプッシュを優先

ユーザーの個人フォーク paperclipai/paperclip が Git リモートとして設定されている場合は、メインリポジトリにブランチを作成するのではなく、機能ブランチをそのフォークにプッシュしてください。これにより、上流のブランチ一覧を整理された状態に保ち、標準的なオープンソースのコントリビューションフローに沿うことができます。

フォーク先のリモートを検出する

プッシュまたは PR を作成する前に、リモートを一覧表示し、paperclipai 以外の GitHub フォークを指しているものがないか確認します。

git remote -v

URL が github.com:<user>/paperclip（または github.com/<user>/paperclip.git）を指しているリモートは、ユーザーのフォークとして扱います。よく使われる名前は fork、<username>、myfork です。paperclipai/paperclip を指している origin または upstream という名前のリモートは正式な上流リモートです。フォークが存在する場合は、そこへ機能ブランチをプッシュしないでください。

フォークへのプッシュ

# Push the current branch to the user's fork and set upstream
git push -u <fork-remote> HEAD

次に、フォークのブランチから PR を作成します。

gh pr create --repo paperclipai/paperclip --head <fork-owner>:<branch-name> ...

フォークを追跡するブランチから実行すると、通常 gh pr create はヘッドの参照を自動的に判別します。判別できない場合は、明示的な --head <owner>:<branch> 形式を使用するのが確実です。

フォークが存在しない場合

git remote -v に paperclipai/paperclip のリモートしか表示されない場合（ユーザーのフォークがない場合）は、従来どおり origin にブランチをプッシュします。ユーザーに代わってフォークを作成してはいけません。まず確認してください。

フォークを最新の状態に保つ

paperclipai/paperclip を指す正式なリモートは、ユーザーのリポジトリの設定によって origin または upstream という名前の場合があります。「フォーク先のリモートを検出する」手順と同じ方法で検出し、そのリモートからフェッチし、そのリモートへプッシュして、どちらの命名規則でも同期できるようにします。

UPSTREAM_REMOTE=$(git remote -v | awk '/paperclipai\/paperclip.*\(fetch\)/{print $1; exit}')
git fetch "$UPSTREAM_REMOTE"
git push <fork-remote> "${UPSTREAM_REMOTE}/master:master"

プルリクエスト

必須の事前確認： プルリクエストを作成する前に、以下に記載の正式なソースファイルを必ず読んでください。これらのファイルを読み、PR の本文が必須セクションをすべて満たしていることを確認するまで、gh pr create を実行してはいけません。

手順 1 — 正式なファイルを読む

PR を作成する前に、次の 3 つのファイルをすべて読む必要があります。

1. .github/PULL_REQUEST_TEMPLATE.md — 必須の PR 本文の構成
2. CONTRIBUTING.md — 貢献に関する規約、PR の要件、思考プロセスの例
3. .github/workflows/pr.yml — マージを許可する CI チェック

手順 2 — このチェックリストに照らして PR 本文を検証する

テンプレートを読んだ後、--body に次のセクションがすべて含まれていることを確認します（名前は完全に一致している必要があります）。

• ## Thinking Path — 引用形式、5～8 個の推論ステップ
• ## What Changed — 具体的な変更点の箇条書き
• ## Verification — レビュアーが動作を確認する方法
• ## Risks — 起こり得る問題
• ## Model Used — プロバイダー、モデル ID、バージョン、機能
• ## Checklist — テンプレートからコピーし、項目にチェックを入れる

セクションが 1 つでも欠けている、または空の場合は、PR を提出してはいけません。戻って記入してください。

手順 3 — PR を作成する

手順 1 と 2 を完了してから、gh pr create を実行します。--body の構成にはテンプレートの内容を使用し、自由形式の概要を書いてはいけません。

厳守事項 — 回避しないでください

CLI の失敗を独自の方法で回避しようとしたエージェントが、実際に重大な損害を引き起こしたため、これらのルールが定められています。必ずそのまま従ってください。

1. ワークツリーとデータベースを操作するインターフェースは CLI のみです。 ワークツリーおよびデータベースに関するすべての操作は、必ず npx paperclipai / pnpm paperclipai コマンド経由で行ってください。次の操作は禁止されています。

   • pg_dump、pg_restore、psql、createdb、dropdb、その他の生の postgres コマンドを実行する
   • ワークツリーサーバーが別のインスタンスのデータベースを参照するよう、DATABASE_URL を手動で設定する
   • .paperclip/、.paperclip-worktrees/、db/ ディレクトリに対して rm -rf を実行する
   • 組み込み postgres のデータディレクトリを直接操作する
   • PID を指定して postgres プロセスを終了する

2. CLI コマンドが失敗したら、停止して報告してください。 回避策を試してはいけません。worktree:make、worktree reseed、worktree init、worktree:cleanup、その他の paperclipai コマンドが失敗した場合は、次の手順に従ってください。

   • タスクのコメントに、正確なエラーメッセージを記載する
   • タスクのステータスを blocked にする
   • npx paperclipai doctor --repair の実行、またはワークツリーを最初から作り直すことを提案する
   • CLI が行う処理を手動で再現しようとしない

3. インスタンス間でデータベースを共有しないでください。 各ワークツリーインスタンスには、それぞれ独立したデータベースが割り当てられます。あるインスタンスから別のインスタンスのデータベースを参照するよう、DATABASE_URL を上書きしてはいけません。これは分離を損ない、本番データを破損させる可能性があります。

4. ワークツリーで開発サーバーを起動するには、まずセットアップが必要です。 正しい手順は次のとおりです。

   # If the worktree already exists but has no running instance:
   cd <worktree-path>
   eval "$(npx paperclipai worktree env)"
   pnpm install && pnpm build
   npx paperclipai run          # or pnpm dev
   
   # If the worktree needs a fresh database:
   npx paperclipai worktree reseed --seed-mode full
   
   # If the worktree is broken beyond repair:
   npx paperclipai worktree:cleanup <name>
   npx paperclipai worktree:make <name> --seed-mode full
   

   いずれかの手順が失敗した場合は、ルール 2 に従って停止し、報告してください。

5. シード処理は CLI で行います。 メインインスタンスからワークツリーのデータベースにシードするよう依頼された場合は、worktree reseed を使用するか、worktree:make --seed-mode full で作り直してください。オプションの一覧は doc/DEVELOPING.md で確認してください。データベースを手動でコピーしようとしてはいけません。

開発サーバーの常駐（手動テスト用）

現在のハートビートが終了した後も開発サーバーを稼働させておく必要がある場合（人間や QA エージェントがサーバーに接続して手動テストできるようにする場合など）、エージェントはサーバープロセスを必ずデタッチされたセッションで起動してください。ハートビートのシェルから直接起動したプロセスは、ハートビートの終了時に強制終了されます。

tmux を使用してサーバーを常駐させる

# 1. cd into the worktree (or main repo) and source the environment
cd <worktree-path>
eval "$(npx paperclipai worktree env)"   # skip if using the primary instance

# 2. Start the dev server in a named, detached tmux session
tmux new-session -d -s <session-name> 'pnpm dev'

# Example with a descriptive name:
tmux new-session -d -s auth-fix-3102 'pnpm dev'

セッションの管理

タスク	コマンド
セッションが稼働中か確認する	tmux has-session -t <session-name> 2>/dev/null && echo running
サーバーの出力を表示する	tmux capture-pane -t <session-name> -p
セッションを終了する	tmux kill-session -t <session-name>
すべての tmux セッションを一覧表示する	tmux list-sessions

サーバーに接続できることを確認する

起動後、成功を報告する前に、ポートがリッスン状態であることを確認してください。

# Wait briefly for startup, then verify
sleep 3
curl -sf http://127.0.0.1:<port>/api/health && echo "Server is up"
lsof -nP -iTCP:<port> -sTCP:LISTEN

重要なルール

1. 開発サーバーをハートビート終了後も稼働させる必要がある場合は、必ず tmux（または同等のもの）を使用してください。 エージェントのシェルから直接起動したサーバーは、直前まで正常に見えていたとしても、ハートビートの終了時に停止します。
2. セッションには内容が分かる名前を付けてください。 ワークツリー名とポートを含めてください（例：auth-fix-3102）。
3. URL を誰かに知らせる前に、サーバーがリッスン状態であることを確認してください。
4. nohup や単独の & は使用しないでください。 プロセスグループ全体が強制終了される可能性があるエージェントのシェルでは、これらの方法は信頼できません。
5. 作業が終わったら後片付けをしてください。 テストが完了したら、tmux セッションを終了してください。

よくある間違い

間違い	解決方法
サーバーが起動しない	npx paperclipai doctor --repair を実行して、問題を診断し自動修正します
worktree の環境変数を読み込み忘れる	worktree に移動した後、eval "$(npx paperclipai worktree env)" を実行します
pull 後に依存関係が古いままになっている	pull 後に pnpm install && pnpm build を実行します
pull 後にスキーマが古いままになっている	pnpm db:generate && pnpm db:migrate を実行します
対象の DB が稼働中に再シードする	先に対象サーバーを停止するか、--allow-live-target を使用します
マージされていないコミットがある状態でクリーンアップする	先にマージまたはプッシュするか、意図的に破棄する場合は --force を使用します
エージェントを誤ったインスタンスに対して実行する	PAPERCLIP_API_URL が正しいポートを指していることを確認します
CLI コマンドが失敗する	回避策を使ってはいけません。エラーを報告して作業を止めてください（上記の「厳守ルール」を参照）
エージェントが手動での Postgres 操作を試みる	絶対に行ってはいけません。すべての DB 操作は CLI 経由で行います（上記の「厳守ルール」を参照）
ハートビートの合間に開発サーバーが停止する	デタッチした tmux セッションで起動します。上記の「永続的な開発サーバー」を参照してください
フォークがあるのに paperclipai/paperclip に機能ブランチをプッシュする	代わりにユーザーのフォークのリモートにプッシュします。上記の「フォーク」を参照してください