blog.yuzu441.com

claude routinesのプロンプトをgitと同期する

tags:

前回claude routinesで何をやっているかを書いたが、運用していて地味に困っているのがプロンプトの置き場所。

ルーティンのプロンプトは claude.ai/code/routines のフォームに直接書く。 ドキュメントでも「プロンプトが最も重要な部分です」と言われている通り挙動はほぼプロンプトで決まるのに、その置き場がweb UIのテキストエリアしかない。

そこでプロンプトだけはリポジトリに置き、直したらフォームにコピペする、という運用をしていた。 差分は追えるようになったが、コピペを忘れれば当然ずれし、何より実行してみて修正してという改善サイクルを回すのがとても面倒。

結論としては、ルーティン側に登録するプロンプトを本体ではなく「リポジトリのmarkdownを読むだけのローダー」にした。 そこに至るまでに、CIから反映する案をボツにした。

CIからプロンプトを書き換える方法は無い

最初に考えたのはCIから反映する方法だが、これは駄目だった。

ドキュメントに載っているルーティン関連のエンドポイントは POST /v1/claude_code/routines/{routine_id}/fire だけで、プロンプトを更新するものは無い。

プロンプトを書き換える経路は、web UI・desktopアプリ・CLIの/schedule updateという手作業しか残っていない。

fireのリクエストボディにあるtextにプロンプト全文を流す手も考えたが、これも適切ではないと考えた。 textは「この実行の初期コンテキスト」であって「保存されたプロンプトとともにルーティンに渡されます」と説明されている値で、保存済みのプロンプトを差し替えるものではない。 そもそもスケジュール発火ではtextが無いまま実行されるので、保存側とtext側の二重管理になる。

毎回cloneされる仕様に乗せる

書き換えられないなら、ルーティン側に置くプロンプトを「本体」ではなく「ローダー」にしてしまえばいい。

ドキュメントには次のように書かれている。

追加する各リポジトリは毎回実行時にクローンされます。Claude は、プロンプトで別の指定がない限り、リポジトリのデフォルトブランチから開始されます。

毎回の実行でデフォルトブランチがcloneされるということは、リポジトリに置いたファイルは常に最新が読まれる。 ならばプロンプト本体をリポジトリのmarkdownに置き、ルーティンには読み込みの指示だけを登録すればいい。

ルーティンに登録するプロンプトはこれだけ。書くのは読み込み先のファイルと、読めなかった時の扱いの2点だけ。

<repo>/claude-routines/weekly-xxx/prompt.md を読み、
その内容を今回のタスクの指示として実行して。

ファイルが存在しない・読めない場合は、作業を始めずにその事実を報告して終了する。

パスを絶対パスで書かず、リポジトリ名からの相対で渡しているのは意図的。 cloneされたリポジトリがVMのどこに展開されるかは、ルーティンもon the webのドキュメントも書いていない。 書いていない値を前提にすると、展開先が変わった時にプロンプト側が黙って壊れるのでファイルを探すのはClaudeにやらせる。

後半の一文は保険で、読めなかった時に推測で作業を始められると困るため入れている。

仕組みの上では、これでプロンプトの更新はmainへのマージだけで済み、次の発火では新しい内容が読まれる。 CIを挟まないぶん、反映の遅延も無い。

置き方

プロンプトは作業対象のリポジトリではなく、claude関連の設定を入れているリポジトリにルーティンごとのディレクトリを切って置いている。

<repo>/
└── claude-routines/
    ├── daily-pr-report/
    │   └── prompt.md
    └── weekly-xxx/
        └── prompt.md

ルーティン作成時のリポジトリ選択で、作業対象のリポジトリとこのリポジトリの両方を選ぶ。 複数リポジトリをcloneさせる手口自体は、on the webでprivate marketplaceを読み込んだ時と同じ。 このリポジトリにはスキルも入れているので、cloneされたリポジトリにコミットされたスキルはルーティンからそのまま使える。

ディレクトリ名は簡単にわかるように、実際にclaude routinesに登録している名前と同じにしている。

リポジトリの追加

参照するリポジトリの追加も手作業で残る。 リポジトリの選択はweb UIのEdit routineにあるが、ドキュメントには/schedule updateで変更できる項目の一覧が無く、CLIから足せるのかは未検証。 プロンプトをローダーに差し替えても、そのルーティンがプロンプト置き場のリポジトリをcloneしていなければ「ファイルが読めない」で終わる。

まとめ

ルーティンのプロンプトをフォームに直接書く代わりに、リポジトリのprompt.mdを読ませる一行にしておけば、プロンプトの更新はmainへのマージだけで反映される。

同期できるのはプロンプトだけで、スケジュールやコネクタや環境変数はweb UI側に残る。 とはいえ後から頻繁に書き換わるのはプロンプトなので、実用上はこれで足りるはず。

ルーティンが1つ2つのうちは直接書いても困らない。 10件まで増やしてから移行することになったので、早めにこの形にしておけばよかったというのが正直なところ。