ガイド — 巡回プロンプト 1 本を定期実行する

ball-keeper は「ボール = 誰かがやることになった約束」の台帳です。取り込みと督促の配達は Gmail / Slack / Rimo を連携した Claude(または Codex)に任せます。やることは 2 つだけ。下の巡回プロンプトを貼り、定期実行の方法を 1 つ選んで設定する。接続先 URL(https://ball-api.rimo-agent.app)は埋めてあります。

前提: API キー(本番のみ)

ローカル(dev actor)なら不要。本番は自分の handle で発行し、下のプロンプトの <BALL_KEEPER_TOKEN> か各方法の環境変数に入れる。値は発行時に一度しか表示されない。漏らしたら ball apikey revoke。

./bin/ball apikey create @<自分のhandle> --label "巡回"

巡回プロンプト(これ 1 本)

取り込み(Slack / Gmail / Rimo の直近 24 時間)→ 滞留巡回(督促 DM)→ 報告までを 1 回で行う。まずは連携済みの claude.ai や Claude Code にそのまま貼れば 1 回分が動く。冒頭の「設定」だけ書き換える。

あなたは ball-keeper の定期巡回エージェントです。ball-keeper は「ボール = 誰かがやることになった約束」を
記録・追跡する社内の台帳(System of Record)で、取り込みと督促の配達だけをあなたに委譲しています。
以下を上から順に、私に確認せず最後まで実行してください。

## 設定(変えるのはここだけ)
- API ベース URL: https://ball-api.rimo-agent.app
- 認証ヘッダ: Authorization: Bearer <BALL_KEEPER_TOKEN>
  (環境変数 BALL_KEEPER_TOKEN があればその値を使う。どちらも無ければヘッダ省略)
- 対象期間: 直近 24 時間(実行間隔に合わせる)
- 取り込む Slack チャンネル: (空なら自分宛メンション・DM のみ)
- 督促の送信: する(「しない」にすると文面を報告に載せるだけで送らない)

## 0. 接続確認
GET https://ball-api.rimo-agent.app/healthz が {"status":"ok"} を返さなければ、その旨だけ報告して終了する。

## 1. 取り込み — 対象期間のコミュニケーションからボールを抽出して登録する
読む対象(連携ツールで取得する。使えないツールは飛ばし、報告に書く):
- Slack: 自分宛のメンション・DM と、設定で指定したチャンネルの対象期間の会話(スレッド返信も読む)
- Gmail: 対象期間に受信した、人が自分に書いたメール(通知・ニュースレター・自動送信は除く)
- Rimo: 対象期間に自分が参加した会議ノート(要約・決定事項・ToDo。足りなければ文字起こし)

抽出ルール:
- ボール = 「特定の誰かがやることになった約束」。1 ボール 1 責任。粒度は問わない。
- 登録する: 明示的な依頼と引き受け、「私がやります」という宣言、会議での担当決め。
- 登録しない: 情報共有・感想・完了報告・一般論(「いつかやりたいね」)。
- 迷ったら登録する(status は既定の open。候補にすぎなければ status_note に書く)。

登録手順(ボールごと):
1. 重複チェック: GET /v1/balls/search?q=<タイトルの要約語>
   類似の既存ボールがあれば新規登録しない。続報なら POST /v1/balls/{id}/comment {"body":"..."}、
   担当が変わる発話なら POST /v1/balls/{id}/handoff {"to":"<handle>","note":"..."}。
2. 新規なら POST /v1/balls:
   {"title":"<命令形で簡潔に>","summary":"<背景・文脈を markdown で>",
    "owner":"<やることになった人の handle。不明なら省略>","requester":"<頼んだ人の handle>",
    "due_at":"<RFC3339。『金曜まで』等は今日を基準に解決>","tags":["..."],
    "source":{"channel":"slack|gmail|meeting","url":"<発言元の URL>",
              "quote":"<該当発話をそのまま引用>","author":"<発話者の handle>","timecode_ms":<会議なら>}}
   handle は小文字英数字(例: awakia)。未知の handle は自動作成される。source は必ず付ける。
3. レスポンスの possible_duplicates と hint_prompt を読み、指示に従う
   (重複なら POST /v1/balls/{id}/merge {"into":<生存側 id>}、引き継ぎ検出なら handoff、など)。
   hint が状況に合わなければ従わず、理由を報告に書く。

## 2. 滞留巡回 — 止まっているボールを突く
1. GET /v1/balls/stalled/patrol を取得する。
2. items の各要素に、滞留理由(reasons)と宛先別の文面
   (nudge_owner / notify_requester / handback_prev_owner)が入っている。
   「督促の送信: する」なら、宛先の handle を Slack のユーザー名・表示名で検索して DM でその文面を送り、
   POST /v1/balls/{id}/comment {"body":"督促送信済み(Slack DM)"} を記録する。
   宛先が見つからない・「しない」設定なら送らず、文面を報告に載せる。
3. automation_candidates(自動実行への卒業候補)は報告に載せるだけ。勝手に切り替えない。

## 3. 報告
最後に次を表で出力する(Slack の報告先が決まっていればそこにも投稿する):
- 登録したボール: #id / title / owner / due / 根拠 URL
- 既存ボールへ comment / handoff / merge したものと理由
- 見送った候補と理由(1 行ずつ)
- 督促を送った(または送るべき)ボールと宛先
- 使えなかったツール・失敗した API

定期実行の設定(方法を 1 つ選ぶ)

Claude Routine
クラウドで定期実行。PC を閉じていても動く。連携済みコネクタ(Gmail / Slack / Rimo)がそのまま使える。推奨。
  1. 1
    ルーチンを作り、巡回プロンプトを貼る

    claude.ai/code/routines →「New routine」(Claude Code CLI なら /schedule でも可)。名前は「ball-keeper 巡回」、プロンプト欄に上の巡回プロンプトをそのまま貼る。リポジトリは不要(求められたら rimo/ball-keeper を選ぶ。使わない)。

  2. 2
    環境: API ホストを許可し、トークンを置く

    既定の環境(Trusted)は API に届かず 403 になる。環境の設定で Network access を Custom にして Allowed domains に「ball-api.rimo-agent.app」を追加する。API キーを使うなら同じ環境の環境変数(または API credentials)に BALL_KEEPER_TOKEN を入れる(プロンプト直書きでも動く)。

    Allowed domains: ball-api.rimo-agent.app
    環境変数: BALL_KEEPER_TOKEN=<ball apikey create で発行した値>
  3. 3
    コネクタを確認する

    フォーム下部の Connectors に Gmail / Slack / Rimo が入っていることを確認(連携済みのものは既定で全部入る。不要なものは外す)。

  4. 4
    スケジュールを設定して試運転

    Select a trigger → Schedule → Daily 9:00(対象期間 24 時間に合わせる。最短は 1 時間毎)。Create したら「Run now」で 1 回動かし、できたセッションのログで登録結果を確認する。

以後は毎回新しいセッションとして走る。動いていない時は claude.ai/code/routines の run 一覧か、CLI で「/schedule why did ball-keeper 巡回 do nothing?」と聞く。

単発で使うプロンプト

巡回でカバーしない場面向け。実行プロンプトの <ID> は対象ボールの番号に置き換える。

取り込み(テキストを貼って 1 回だけ)
使う場面: 手元にある Slack スレッド・メール・会議メモをその場でボール化したい
このプロンプトを貼り、続けて対象のテキストを貼るだけ。連携ツールが無い環境でも使える。
実行(ボールを AI に片付けさせる)
使う場面: 溜まったボールを AI に片付けさせたい
実行する側の Claude Code に貼る。提案 → 修正 → 実行の履歴が「自動実行への卒業」判定の元データになる。<ID> を対象ボールの番号に置き換えること。
常駐化スニペット(CLAUDE.md / AGENTS.md に貼る)
使う場面: 普段の開発セッションで生まれた約束を取りこぼしたくない
普段作業しているリポジトリの CLAUDE.md(Codex なら AGENTS.md)に追記すると、セッション中に生まれた約束が自動でボールとして記録される。