ガイド — 巡回プロンプト 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 つ選ぶ)
- 1ルーチンを作り、巡回プロンプトを貼る
claude.ai/code/routines →「New routine」(Claude Code CLI なら /schedule でも可)。名前は「ball-keeper 巡回」、プロンプト欄に上の巡回プロンプトをそのまま貼る。リポジトリは不要(求められたら rimo/ball-keeper を選ぶ。使わない)。
- 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コネクタを確認する
フォーム下部の Connectors に Gmail / Slack / Rimo が入っていることを確認(連携済みのものは既定で全部入る。不要なものは外す)。
- 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> は対象ボールの番号に置き換える。
このプロンプトを貼り、続けて対象のテキストを貼るだけ。連携ツールが無い環境でも使える。
実行する側の Claude Code に貼る。提案 → 修正 → 実行の履歴が「自動実行への卒業」判定の元データになる。<ID> を対象ボールの番号に置き換えること。
普段作業しているリポジトリの CLAUDE.md(Codex なら AGENTS.md)に追記すると、セッション中に生まれた約束が自動でボールとして記録される。