Scheduling Jobs

このMacの定期実行は、無人で走り、失敗しても誰も見ていない。だから作るときに「止まったら気づける」「飛ばされても取り返せる」「秘密が漏れない」を型として組み込む。

既存設定との関係

• taskboard の tool: 引数・見回り・消し方は /taskboard スキルが真実源。本スキルはその上で、何を登録するか（仕組みの選択・手順書・プロンプト・状態ファイル）を決める
• 置き場所: 他のマシンでも成り立つスクリプトは ~/.claude/bin、このマシンでしか成り立たない実値（ID・チャンネル・パス）は git 管理外に置く（@context/claude-customization-guide.md「公開リポジトリに書く内容」）
• 後始末: 試運転で起動したプロセスは AGENTS.md「バックグラウンドプロセスの後始末」に従う

Step 1: 仕組みを選ぶ

条件（上から判定）	仕組み	手順
Mac が閉じていても動いてほしい / このMacのファイル・MCP に依存しない	クラウドの routine	/schedule スキル
今のセッションが開いている間だけ繰り返せばよい	セッション内ループ	/loop スキル
各回で読んで判断する（収集・分類・起票・要約・通知文の作成）	taskboard の定期起動	references/taskboard-routine.md
処理が決まっていて判断が要らない（掃除・同期・再認証・バックアップ）	launchd	references/launchd-job.md

判断の要る部分と決まった部分が混ざるなら、決まった部分をスクリプトに切り出し、taskboard の定期起動の手順書からそのスクリプトを呼ぶ。

完了基準: 仕組みを1つ選び、選んだ理由を上の表の行で言える。

Step 2: 中身を決めて、ユーザーに確認する

登録する前に次を表にして提示し、承認を得る。どれも「動き出してから気づくと取り返せない」項目なので、推測で埋めない。

• 頻度（cron 式か間隔）と、Mac がスリープ・停止していた回をどう扱うか
• 各回が書き込んでよい範囲（ファイル・外部サービス・taskboard）と、明示的に禁止すること
• 対象にするもの・しないもの（ディレクトリ・アカウント・チャンネル）。消す・ゴミ箱に入れる処理は、今その対象に何があるかを ls で見せ、初回の実行で消えるものを列挙する
• 失敗をどこに出すか（通知先・ログ）
• モデル・effort（taskboard の場合）。巡回が重いほど上げる。既定は opus / medium

完了基準: 上の5項目すべてにユーザーの回答か承認がある。

Step 3: 作る

選んだ仕組みの reference の手順で作る。ソース（Slack・GitHub・Jira・メール等）を巡回して taskboard に起票し、列を進め、通知する巡回は、templates/taskboard-patrol/ の雛形を写して始める（手順は references/taskboard-routine.md「雛形から作る」）。どちらにも共通する規則:

• 秘密情報（Webhook URL・トークン）は、ジョブのディレクトリに権限 600 のファイルで置き、プロンプト・手順書・plist・コマンドラインに書かない。プロンプトと手順書は会話ログに、コマンドラインはプロセス一覧に残る。通知の Webhook は curl の設定ファイル（url = "..." の1行）にし、curl -K <ファイル> で送る。このときコマンドラインに URL を並べない（並べると両方に送られる）
• ログはジョブの名前のディレクトリに書く（/tmp は再起動で消え、失敗の調べようがなくなる）
• 登録内容を ROUTINE.md（launchd は setup スクリプト）としてジョブのディレクトリに残す。登録の実体（taskboard の DB・plist）が消えても、別のマシンでも作り直せるようにする

完了基準: reference の「作るもの」が全部ある。grep で秘密情報の値がプロンプト・手順書・plist に無いことを確認した。

Step 4: 試運転する

予定の時刻を待たず、1回だけ手で起こして結果を見る。

• taskboard: schedule_run → 終わったら schedule_runs と session_history で結果、状態ファイルとログが更新されたかを見る
• launchd: launchctl kickstart -k gui/$(id -u)/<label> → launchctl print gui/$(id -u)/<label> の last exit code とログを見る

完了基準: 試運転の回が成功で終わり、ログに1回分の記録がある。失敗したら原因を直してもう1回起こす。

Step 5: やめる

• taskboard: schedule_update の enabled: false で止め、要らなければ schedule_delete（/taskboard の消し方に従い、1回目の応答で消えるものを確かめる）。常設タスクの扱いはユーザーに聞く
• launchd: launchctl bootout gui/$(id -u)/<label> で外し、plist をゴミ箱に移す（/usr/bin/trash）。launchctl print が「Could not find service」を返せば外れている
• スクリプト・手順書・状態ファイルを消すかどうかはユーザーに聞く（消さなければ報告に残した場所を書く）

完了基準: 登録が一覧（schedule_list / launchctl print）から消えている。

Gotchas

• Mac のふたを閉じたスリープ中も、macOS は短く起きる（DarkWake）。taskboard の定期起動はその間は起こさず、完全に起きてから過ぎた分の最新の1回を起こす（daemon が判定する）。launchd のジョブにはこの判定が無い。ネットワークの要る処理は、届かなかったら失敗として終わり、次の回でやり直す作りにする。どの仕組みでも回は遅れたり飛んだりするので、各回は「前回成功した時刻から今まで」を処理する作りにし、飛ばされた回を次の回で取り返す
• launchd から起動したプロセスは、Desktop・Documents・Downloads を読めない（macOS のプライバシー保護。ターミナルに付けた許可は引き継がれない）。読めないディレクトリに *(N) の glob を使うと、エラーにならず空として扱われ、何もしないまま成功したように見える
• set -e のスクリプトは、途中の1コマンドの失敗でそれ以降の処理を全部飛ばす。独立した処理は失敗しても次へ進ませ、最後に失敗があったかで終了コードを決める
• taskboard の定期起動は、止めていた間と規則を変える前の時刻をさかのぼって起こさない。launchd の StartInterval もスリープ中の回は起こさない（StartCalendarInterval は復帰時に1回だけ起こす）