dev-loop のオートクルーズ(複数 Issue を不在のまま回す)
依存のある複数の Issue を、1 つの親セッションで起票 → 実装 → 関門 → マージまで回し、
利用者が席を外していても止まらずに進めるための使い方です。
dev-loop は「1 Issue = 1 周」のスキルなので、オートクルーズはその周を束ねる運用です。
回す Issue を親 Issue のチェックリストに書いておき、/dev-loop:cruise <親 Issue> で起動します。
規範はスキルのディレクトリにあります
このページは部品の場所と使う順番の案内です。各部品の決まり(いつ書くか・どこで止まるか・何を守らないか)は
スキル本文と
references/、
スクリプトの docstring を正とします。ここに書き写すと片方だけが古くなるので、要点しか書いていません。
部品をそろえて通しで回した実績は、まだありません
部品は #389 から分けた Issue で入りました (台帳・実装役の委譲文・積んだ周・マージ・不在の線・環境点検・直す線)。 ただし、入った部品だけで複数の Issue を最後まで回したことは、まだありません。
389 のもとになった運用は、部品が入る前に親セッションが手で組み立てたものです。
最初は依存の少ない 2〜3 件で試し、台帳と計画ファイルを見ながら進めてください。
部品の一覧
| 部品 | 置き場所(スキルの base ディレクトリから) | 役割 |
|---|---|---|
| 入口 | ../cruise/SKILL.md・../cruise/scripts/parent-issue.py |
親 Issue の一覧を読み、確かめてから台帳を作る。起動し直すと台帳から再開する |
| 台帳 | scripts/ledger.py・references/ledger.md |
Issue の依存と状態をファイルに持つ。再開の入口 |
| 実装役の委譲文 | prompts/implementer.md |
実装役(Agent)に渡す文面のテンプレート |
| 積んだ周(stacked) | references/stacked.md |
未マージの下の周の上で、上の周を先に始める |
| マージ | scripts/merge-pr.py |
CI 待ち → 関門の照合(check-gates.py。計画ファイルの関門の記録をリポジトリの履歴と突き合わせる。#1043。不在の周では、宣言した範囲と revert した範囲に触れる差分も止める。#1047) → squash → worktree の撤去 → Issue が閉じたかの確認。台帳でその PR の行が利用者の判断を待っていればマージしない(#631) |
| 不在の線 | references/absent-lines.md |
利用者がいないとき、止まる代わりに進んでよい範囲 |
| 環境点検 | scripts/check-unattended-env.py |
起動時に、周で使う操作の許可・止まりうる操作・親の起動場所を読むだけで点検する。席を外すなら自動継続・通知なども(席を外したあとの再開の --since-last だけは、前回の結果を台帳の隣に残す) |
| 直す線 | references/fix-line.md |
関門の指摘をどこまで周の中で直すか |
| まとめの周 | ../cruise/references/grouping.md・scripts/ledger.py(group) |
周の途中で足した、同じファイルを触る行を 1 周・1 PR にまとめる(#641) |
| 長期トークンの起動口 | scripts/launch-with-long-token.sh |
対話ログインの 8 時間の期限で止めないよう、キーチェーンの長期トークンで claude を起動する(cruise を長期トークンで起動する) |
| 子プロセスの周(任意) | ../cruise/scripts/child-cycle.py・../cruise/references/child-process.md |
周を claude -p の子プロセスで回す起動口と要約。親の /clear の道連れにならない。既定はサブエージェントのまま(#491) |
| 外側のループ(任意) | ../cruise/scripts/outer-loop.py・scripts/ledger.py(status・progress) |
cruise を claude -p で起動し直して回すループ。進められる周があり、起動のたびに周が進んでいるあいだだけ起こし直す(#791) |
| 周の片付け | ../cruise/scripts/cleanup-cycle.py |
周のマージの後に、その PR から決まる worktree(周の作業木と Verifier・/code-review の隔離木)とローカルブランチだけを消す。未コミットの変更がある木は残して台帳のメモに載せる。リモートのブランチ・PR には触らず、終えるときに本数と PR の状態ごとの内訳を数える(#823) |
| 順番待ちと並行の周 | ../cruise/scripts/run-serial.py・../cruise/references/parallel.md |
周の重い検査・アプリの起動を、同じリポジトリでは順番待ちにする(既定は 1 本ずつ)。単独で回す周と、版をマージの直前に上げ直す決まりも(#493・#531) |
スキルの base ディレクトリは、プラグインで入れていれば
~/.claude/plugins/cache/claude-code-setup/dev-loop/<版>/skills/dev-loop、
scripts/link-skills.sh で張っていれば ~/.claude/skills/dev-loop です。
キャッシュには古い版も残るので、<版> は下の「版を確かめる」で読み込まれている版にします。
スキルを起動すると、親セッションには base ディレクトリが渡されます。
0. 版を確かめる
部品がそろうのは dev-loop 1.55.0 からで、積んだ周のマージの歯止め(#426)が
入ったのは 1.56.0、起動のコマンド /dev-loop:cruise(#446)が
入ったのは 1.57.0、親 Issue の線(cruise: の行。#458)が入ったのは 1.58.0、周の途中で見つかった課題を台帳に足す線(#464)が入ったのは 1.59.0、同じファイルを触る足した行を 1 周にまとめる手順(#641)が入ったのは 1.67.0 です。
1.55.0 より前の版には、台帳も不在の線も入っていません。
claude plugin list --json # 読み込まれる版を確かめる
claude plugin update dev-loop@claude-code-setup # 古ければ上げる(そのあと再起動)
更新が届かない形と確かめ方は、プラグイン一覧の「更新のしかた」を正とします。
1. 対象リポジトリに宣言を書く(席を外す前)
不在のあいだに進めてよい範囲は、対象リポジトリの .claude/dev-loop.md に書きます。
PR を通る場所なので、許可の範囲が利用者の目を通ります。
不在の線: 仕様の穴 = 推奨で決めて起票
不在の線: 実機確認 = Refs でマージ
不在の線: マージ = 関門を通ればマージ
直す線: 既定
cruise の操作: gh workflow run infra-apply.yml
- 書かなければ、どの線も「止まる」です。 マージも宣言が無ければしません(PR を出して止まります)。 必要な線だけを書きます。
- 本番反映(デプロイ・migrate・本番の設定値)は広げられません。 main への push で自動デプロイする
リポジトリでは、マージ自体が本番反映に数えられるので、
マージの線も効きません。 マージが起こす反映が公開ドキュメントのサイトの再ビルドだけなら、マージの反映: ドキュメントのみの 1 行を書けます。 各周はマージの前にCLAUDE.md・deploy runbook・ワークフローの定義と、既定ブランチそのものが配布元になっていないか (利用者が main から取るプラグインのカタログなど)をこの宣言と照らし合わせ、宣言の外の反映(サイトの公開のほかのデプロイ・ パッケージの公開・利用者が取りに来る配布物の更新など)が無いときだけ、マージの線を効かせます。 周が自分の PR で足した宣言は、その周のマージには効きません。 マージがプラグインの中身も利用者に配る(main がプラグインのカタログの配布元で、git pullしてlink-skills.shで張る利用者もいる)リポジトリは、マージの反映: ドキュメントとプラグインの配布を書けます(このリポジトリはこれを置いています)。この値ではプラグインの中身の配布は宣言の中で、 照合はそれ以外について上と同じに見ます。加えてその周の差分が、カタログの版と説明のほか・プラグインの hooks や MCP サーバの定義・.claude/settings.json・ 利用者が clone のパスで hook などに登録させているスクリプトを変えていればマージしません。 配布は revert しても取った利用者の状態が戻らないので、マージの線は cruise ごとに確かめたもの(起動時か再開時の確認で配布を起こすと見せて確かめ、 台帳の線の出所に印配布を見せて確かめたを区切った形で書いてledger.py showの「配布の確認」がありになったものか、その周の利用者の直接の指示)でしか効きません——.claude/dev-loop.mdの不在の線: マージだけでは、配布を起こすマージはしません。マージの線が効かないリポジトリでは、--absentの起動時の確認にそう出ます。 並行の検査: Nは、周が同じリポジトリで同時に走らせる重い検査・アプリの起動の本数です(書かなければ 1——順番待ちで 1 本ずつ)。 検査が互いに干渉せず、ポート・データベースを奪い合わないと分かっているリポジトリだけ増やします。利用者が居る cruise にも効きます。空いているときの検査: Mも書くと、N 本が埋まっていても機械が空いているときだけ M 本まで走らせます(書かなければ負荷を見ません。#1057)。 書式はrun-serial.pyの docstring を正とします。cruise の操作:は、周で打つ操作のうち既定の点検(git push・gh pr create・gh pr merge・gh pr comment・gh issue create)に 無いものを 1 行 1 コマンドで書きます(本番反映の口など)。起動時の点検がその許可を見ます。利用者が居る cruise でも書いておきます。- 値の一覧と、それぞれの線で何が起きるかは
references/absent-lines.mdを、直す線はreferences/fix-line.mdを正とします。
2. 環境を点検する(起動時に 1 度)
python3 <スキルの base ディレクトリ>/scripts/check-unattended-env.py --cruise --ledger issue-<親> # 席を外すとき
python3 <スキルの base ディレクトリ>/scripts/check-unattended-env.py --cruise --present --ledger issue-<親> # 居るとき
python3 <スキルの base ディレクトリ>/scripts/check-unattended-env.py --cruise --ledger issue-<親> --since-last # 席を外したあとの再開
席を外したあとの再開では --since-last を付けます——前回の点検と同じ項目を 1 行(区分ごとの件数・前回の時刻・要対処と判定できないの項目の名前)に縮め、変わった項目だけを全文で出します。
前回の結果は台帳の隣の cruise-issue-<親>.env-check に残ります(#635)。
claude -p で起動した cruise では、通知の設定の 2 項目は「人が見る」の 1 行になります——人を呼ぶ経路は起動した側で用意します。
cruise は台帳を作ったあと、--absent に依らずこれを回して結果を見せます。 利用者が居ても、権限の拒否や確認で
周が止まり、操作を待つことになるためです(#466)。
- 許可ルール——既定の操作と
cruise の操作:で宣言した操作がallowに当たるか。 - 止まりうる操作——自動モードの分類器と worktree 隔離のガードは settings に現れないので、許可があっても止まりえます。 起動時に操作ごとに選びます: 許可を足す/その操作だけ自分で打つ(台帳に残り、周はその操作の手前で「操作待ち」になって 依存しない次の周へ進みます)/その周を cruise の外に出す。
- 親の起動場所——cruise の親は、メインの作業ツリーから worktree に入らずに起動するのが既定です。 worktree の中から起動すると、別の worktree・別のリポジトリへの操作がガードに拒まれます。
- 不在の間にどこまで進めるか(#490)——台帳の済んでいない周ごとに、
マージまで進む見込みか・PR で止まるか・始まらないか(依存先と、止まる元)・止まっているかと、その理由を出します。
理由は、
マージの線がこのリポジトリで効かない・PR が main と衝突している・同じプラグインの版を上げる PR が 2 本ある・ マージの前に利用者の判断が要る(台帳のnoteが利用者の判断待ち:で始まる)・利用者の操作待ち、などです。 見込みです——関門・CI・利用上限で止まる周は数えず、マージの線の照合(ワークフロー・CLAUDE.md・周の差分)は各周がマージの前に行います。 止まる周を片づけてから離れるかは利用者が決めます。 - 席を外すとき(
--presentなし)は、利用上限での自動継続・質問の待ち・通知・スリープも読みます。 - 認証——長期トークンで起動したか、対話ログイン(8 時間で切れる)かを出します。対話ログインなら、起動時に長期トークンで回すかを訊きます (cruise を長期トークンで起動する。長期トークンでは claude.ai のコネクタ・claude.ai から届くスキル・Remote Control・Claude in Chrome が使えません——2.1.316 で測り、エラーは出ず黙って無い形でした。通知は判定できていません)。
足りないものと直し方を出します。直すのは利用者です(スクリプトは書き換えません)。 点検と同じ場面で、再開タイマーを張るかも 1 度だけ訊きます(張れる範囲の限界と一緒に。下の「5. 再開する」。#472)。
通知は、設定が正しくても届かない形があります。iPhone をいまのセッションにつなぎ(/remote-control)、
端末を操作していない状態で試しに送って確かめます。手順は
リモートコントロールの設定手順(不在中の運用)と、
スキル本文の「待ち時間・定時処理は別スキル」を正とします。
利用上限で止まったことをその場で記録・通知したいなら、StopFailure の hook を user の settings に足します
(利用上限の停止をその場で記録する。登録は利用者が行います。
上限で実際に発火するかは確かめていません)。下の「利用上限で止まったとき」の自動継続の確認
(#456)を取りこぼさないためのものです。
3. 親 Issue に一覧を書いて起動する
回す Issue を、親 Issue(どの Issue でもよい)の本文にチェックリストで並べます。依存は (depends: …) で書きます。
[x]の行は済んだものとして扱い、台帳に入れません。それへの依存は満たされたと読みます。#番号で始まらないチェックボックス(受入基準など)は台帳に入れず、起動時の確認に「読み飛ばした行」として並びます。#の書き忘れはここで気づけます。- 依存の書き方を誤った行(
(depends: …)の外に「depends」「依存」や#番号がある、など)や、閉じていないコードフェンス・行頭から始まって閉じない HTML コメントがあると、台帳を作らずに止まります。 - コードフェンスと HTML コメント(
<!-- … -->)の中は読みません。引用(>)の中の行は「読み飛ばした行」に並びます。 - チェックリストの行が 1 本も無い Issue は親 Issue として扱いません(1 件だけなら
/dev-loop:dev-loop <番号>で回します)。
周の途中で訊く判断を、親 Issue に書いておく(線)
同じ親 Issue に cruise: の行を書くと、周ごとに訊かれる判断を起動時に 1 度だけ確かめて、各周へ渡せます(再開したときに確かめ直せば、その値に書き直します)。
- 起動時の確認に、書いた線と「書いていない」線が並びます。 書いていない
仕様の穴・実機確認・マージは台帳に残らず、--absentの周なら「1. 対象リポジトリに宣言を書く」の不在の線:の宣言、無ければ既定(止まる)になります。周の途中の課題とマージ前の判断は.claude/dev-loop.mdの宣言に落ちません——周の途中の課題は起動時に訊かれ、答えなければ外に出す、マージ前の判断は新規の--absentの起動でマージ = 関門を通ればマージが効くときだけ起動時に訊かれ、答えなければ(訊かれない起動でも)止まるです。直す線は下のとおり起動時に訊かれます。訊く条件は cruise のSKILL.mdの「2. 一覧を確かめてから台帳を作る」 を正とします。 確かめた線は台帳に残り、Issue の本文をあとで書き換えても、確かめ直すまでは台帳の値が使われます。 - 確かめた
仕様の穴と直す線は、利用者が居る周(--absentなし)でも効きます——仕様の穴 = 推奨で決めて起票なら、 訊かずに推奨で決めて確認の Issue を立てて進みます(直す線は周ごとに訊かなくなるだけです)。実機確認・マージ・マージ前の判断は--absentの周だけに効きます。.claude/dev-loop.mdの不在の線:の宣言も--absentの周だけに効きます。 - spec-loop から来た Issue(spec-loop の
scaffoldが作った Issue)には、仕様の穴 = 推奨で決めて起票は効きません——穴に当たると、正本の Q&A 表に差し戻して止まります。 それらの穴も推奨で決めて進めたいなら、cruise: 仕様の穴 = 推奨で決めて起票(spec-loop の Issue を含む)と書きます。 確認の Issue には、正本の Q&A 表に足す行(質問・選択肢・推奨)が書かれるので、戻ったら表に足してreq-loopに載せます(承認するときも、別の値を選ぶときも)。 Red テストと食い違う穴・既にした回答を変える穴・費用だけが変わる内部の判断・推奨を立てられない穴と、周の途中で見つかった課題(関門の指摘など)の穴は、この値でも止まります。 起動時の確認には、一覧のうち spec-loop から来た Issue と、この線が効くかが出ます(#470)。 直す線をどこにも書いていなければ、起動時に 1 度だけ訊かれます(周ごとには訊きません)。周の途中の課題 = 台帳に足して直すにすると、周の途中で見つかった課題も同じ cruise の中で直します(親 Issue の一覧の課題が済むまで。済んだら、まだ始めていない課題は回さずに渡されます。書いていなければ起動時に訊かれます。既定は外に出す)。 各周はマージの前に、関門の残課題・狭いパスの指摘・仕様の穴・範囲の外にした機能・利用者の判断が要る行を振り分け、 実物で失敗を示せて、受入基準を破る・利用者に見える誤り・その周が持ち込んだ後退のどれかに当たる行(実際の利用でまず起きない形を除く)だけを Issue にして台帳に足します (依存は元の周。台帳の「出所」の列に、どの周のどの関門の行かが残ります)。それ以外(テストの試料の穴・まれな書き方・文言・性能の推測)は PR コメントにだけ残ります。 この振り分けは外に出すの周でも同じで、起票の候補と要確認:の Issue も、当たる行だけに絞られます(#774)。 直し方が仕様や利用者の決定に決まっていない行(仕様の穴)は、仕様の穴 = 推奨で決めて起票なら推奨で決めて確認の Issue を立て、止めずに台帳に足します(#670)。 それでも利用者の判断が要る行(既にした決定と食い違う・推奨を立てられない・狭いパスの指摘など)は止めておき、居るときは周の合間にまとめて訊かれます。--absentなら訊かずに、終えるときに渡されます。 狭いパスの指摘も同じ線で振り分けられ、各周は指摘ごとに振り分けと理由を PR コメントに書きます。マージ = 関門を通ればマージの周で、狭いパスの指摘を理由にマージを止めるのは、 受入基準を破る・利用者に見える誤り・その周が持ち込んだ後退に当たる指摘(後退は振り分けに依らず止まります。例外は下のマージ前の判断 = 推奨で決めて起票の線の分だけです)・振り分けと理由が PR コメントに無い指摘と、周が「マージ前に人が判断」と報告したものだけです。 親はマージの前にその PR コメントを読み直し、記録だけ・捨てるの理由が上の 3 つに当たりうる・迷うなら止めます(CI が緑でない・満たしていない受入基準があるなど、ほかの止まる条件はそのままです)。試料の穴・テストの無い分岐・文言の曖昧さだけ(従うと誤った操作になる記述は除く)なら、指摘を PR コメントに残したままマージされます(#821)。振り分けの決まりはreferences/found-lines.mdを正とします。 直す行は触るファイルごとに 1 件の Issue(チェックリスト)で起票され、同じファイルを触る足した行は、次の周を選ぶ前に 1 周・1 PR にまとめられます (2〜5 件。訊かずにまとめ、居るときは報告に並びます。PR にFixesが並び、マージの後に閉じなかった元の Issue は PR を名指しして閉じます)。 いつ・何をまとめるかはreferences/grouping.mdを正とします。マージ前の判断 = 推奨で決めて起票にすると、--absentの cruise はマージの前の判断でも止まらずに進みます(#829。書いていなければ、新規の--absentの起動でマージ = 関門を通ればマージが効くときだけ起動時に訊かれ、訊かれない・答えないなら止まるで、今までどおり利用者の判断を待ちます)。 対象は、周が「マージ前に人が判断」と報告したものと、狭いパスの指摘のうち、ほかの周(台帳・親 Issue の一覧)の受入基準を破る・利用者に見える誤りに当たるもの(その周が持ち込んだ後退は下の段落の分だけ)と、 マージの前に証明する手段の無い受入基準(本番のデータ・デプロイの後・外部の環境で確かめるもの。実機確認の線でRefsにする実機の基準は除きます)です(その周自身の受入基準を破る指摘は、今までどおり止まります。#1037)。 証明する手段の無い基準は、推奨でマージしたあと、確かめる基準とマージの後の確かめ方を書いた要確認:の Issue に残り、元の Issue は閉じます。 周がそれぞれに推奨(マージする/直してからマージする/止める)と理由を PR コメントに書き、親が読み直して推奨どおりに進め、判断ごとに要確認:の Issue を 1 件立てます (終えるときに渡されます。推奨が「直してからマージする」なら、周が直して、直した部分だけを 1 回検証し直します)。 後退を示す指摘(前は動いていたものが新しい版で動かない)のうち、周が直して、後退を示したのと同じ入力が直す前に失敗し直した後に通ることを示し、直しが受入基準と食い違わず、直した部分だけの 1 回の検証し直しでも後退が残らず新しい後退も出なかったものと、 止まる側に倒れる変化(照合・関門・CI・自動化のスクリプトのように進むかを決める側が、前は通した形を新しい版では通さず止まる変化で、誤ってマージ・配布する向きには倒れないもの。製品の機能が動かなくなる後退は含みません)は、推奨で決めて進みます(#1101)。 直さずに推奨でマージすることがあるのは止まる側に倒れる変化だけで、ほかの後退は直さずには通しません。 それ以外の後退を示す指摘と、宣言の外の反映(利用者の hook のスクリプトの変更など、利用者の手元の動きを変えるもの)と、依存の表の止まる条件と、CI が緑でない周は、この線でも止まります—— マージしたら利用者の手元で壊れるか反映を起こすもので、確認の Issue では取り返せないからです。推奨が「止める」の判断・推奨の無い判断・満たしていない受入基準・自動の検証とコードレビューを通していない周など、ほかの止まる条件もそのままです。マージの線が効かない周では、この線も効きません。この線は台帳にだけ置き、.claude/dev-loop.mdには書けません。 書いていなければ、--absentの新規の起動でマージ = 関門を通ればマージが効くときに、起動時に 1 度だけ訊かれます(推奨で決めて起票(推奨)・止まる。答えなければ止まる。#919・#1037)。--absentでマージの線が効く起動では、離れる前にマージ後に確かめる基準の一覧(各 Issue の受入基準のうち、マージの前に証明する手段が無さそうなものと、その行き先)も見せます(見込みで、約束ではありません)。決まりはreferences/absent-lines.mdの「マージ前の判断 = 推奨で決めて起票」 を正とします。本番反映の行は無視されます(広げられません)。書けない値や同じ線の 2 行は、台帳を作らずに止まります。- 線の意味と、各周がどの順で読むか(台帳 →
.claude/dev-loop.md→ 既定)はreferences/absent-lines.mdの「cruise で確かめた線」 を正とします。 書式の決まりはparent-issue.pyの docstring を正とします。
メインの作業ツリーで Claude Code を起動し、親 Issue の番号で起動します。
- 取り出した一覧と依存(と読み飛ばした行・線)が表示されるので、確かめて答えます。 親 Issue の本文は誰でも書き換えられる入力として扱うので、
--absentを付けても、ここだけは起動の時点で訊かれます。確かめた後に本文が書き換えられていたら、台帳は作られません。 - 台帳が作られ、着手できる Issue から順に dev-loop の周として回ります。
台帳は
<メインの作業ツリー>/.claude/plans/cruise-issue-<親>.jsonに置かれます。 各周は通常の dev-loop と同じで、Verifier と/code-reviewを 2 パスで打ち切るのもオートクルーズでも同じです。 台帳は周を束ねる道具で、周を軽くする道具ではありません。 周の途中の割り目(dev-loop の手順 4・6 で「ここで割るか」を訊く場面)は、--absentを付けなくても訊きません—— 周は子(サブエージェントか、任意の子プロセス)が回し、利用者の/clearが割るのは親の文脈だからです(#461)。 --absentを付けると、途中の問い(直す線・起票の承認)を訊かずに進みます。 進めてよい範囲は確かめた線と「1. 対象リポジトリに宣言を書く」の宣言だけで決まり、--absentは範囲を広げません。 マージはマージの線を宣言していれば行い、無ければ PR を出したところで止まって、依存していない別の Issue へ進みます。
起動の手順の決まりは
cruise スキルの本文
を正とします。
周を並行に回すとき
- 各周の重い検査・アプリの起動は、同じリポジトリでは順番待ちになります(上の
並行の検査:。既定は 1 本ずつ)。待たされた周は、待っていることと、いま走っているものを出力に出します。 周の数ではなく検査を絞るのは、検査を起こすのが周の実装役だけでなく、検証とレビューの体でもあるからです。 - 負荷・所要時間を測る周と、わざと負荷を作る周は単独で回します。 親は台帳の
noteに単独: <理由>の項を書くので、再開した親にも分かります。 - 親は版を割り当てません。 各周は PR で版を上げ、マージの直前に PR が main より古ければ、main を取り込んで main より上に上げ直してからマージします。 利用者の判断を待つ PR があっても、同じプラグインを触る他の周を先にマージできます。 対象リポジトリの決まりがそう書いていれば(このリポジトリは書いている)、取り込みの後は手元で全部の歯止めを回し直さず、軽い検査だけ回して push し、PR 側の CI が全部通ったのを見てからマージします(#831)。
- 決まりは
references/parallel.mdを正とします。
4. 依存先がマージ待ちのうちに始める(積んだ周)
依存先の PR がまだマージされていなくても、上の周が使う部分(API・型など)が下の関門を通っていれば、 下のブランチの上に積んで先に始められます。
- 積むかどうかは人間が決めます。 不在のあいだに積んでよいかは、スキルは決めていません。 積ませたいなら、指示の中で「#14 は #13 の PR に積んで始めてよい」と明示してください。
- 下の周がマージされたら、上の周を既定ブランチの上に載せ替えてからマージします。
merge-pr.pyは載せ替えていない積んだ周の PR を止めますが、見分けられない形があります。 - 手順は
references/stacked.mdを正とします。
5. 再開する(タイマー・/clear・別セッション)
同じ引数で起動し直せば、台帳から再開します(台帳は作り直しません)。親 Issue に後から足した Issue は名指しされます——台帳に足すかは利用者が決めます(自動では足しません)。
周を重ねると親セッションの文脈が積み上がりますが、文脈が長くなったことは止める理由になりません(#583)。
Claude Code が文脈を要約(compact)したら、親は次の操作の前にスキル本文・台帳・進行中の周の実物を読み直してから続けます。
読み直すものと、親が止めてよい条件は cruise の SKILL.md §5 を正とします。
周と周の間で /clear して起動し直すのも同じ手です(自動の compact を切っているなら、こちらで割ってください)。
ただし /clear は利用者が打つ操作なので、割ると、打って起動し直すまで cruise は止まります。親は、続けられるのに周の合間で /clear を案内して止まることはせず、compact で続けます(割るかは利用者が決めます)
(#461。タイマーは同じセッションにプロンプトを注入するだけで、文脈は軽くなりません)。
台帳の中身は ledger.py show issue-<親> でも見られます。
- 終了コード 4(判定できなかった)なら再開しません。 台帳が読めないことを「全部済んだ」と読まないためです。
- 進行中の Issue は、台帳の値ではなく実物(
gh pr view・git worktree list)で確かめてから続けます。 各周の続きは、その周の計画ファイルの再開点から始めます。 - まとめの PR のマージの後、直せなかった行を台帳に戻す前に止まっていたら、
showが「落ちたのにまとめの中で merged のまま」の行を名指しします。 親は Issue と PR を実物で確かめてから、その行を戻します(#665)。 名指しされた行が残るあいだ、nextはその行に依存する行(先に戻した行・まとめの外の行)を着手できるものとして出しません(#711)。 - 着手できるものも進行中のものも無いのに「すべてマージ済みか取り下げ」と出ていなければ、どこかで止まっているか、実機確認を待っています。
止まった Issue の
noteに理由が書かれています。 実機確認の線でRefsでマージした周(Issue は開いたまま)は、台帳の状態がmerged_unverifiedになり、showの「利用者の確認待ち(実機確認)」に 確かめる受入基準(note)つきで出ます。依存する周は進みますが、cruise は「済んだ」と報告しません(#634)。
389 のもとになった運用では、30 分おきのタイマー(CronCreate)に台帳を読ませて再開していました。
タイマーを張るかどうかは利用者が決めます——新規の起動で、台帳を作ったあとに 1 度だけ訊きます(「30 分おきに張る(推奨)」か「張らない」。
#472)。張ると答えたら、親が同じ引数の起動をプロンプトにして張り、張った時刻・間隔・次の発火・失効・ジョブ ID を伝えて、
答えを台帳に残します(ledger.py timer)。
- タイマーはそのセッションの中にしか無く、セッションが終われば消えます(Claude Code 2.1.317 の道具の説明。既定のタイマーの場合)。 セッションが落ちたら、メインの作業ツリーで同じ引数で起動し直してください——利用者が居る再開では、タイマーが無ければもう一度訊きます (前に「張らない」と答えていれば訊きません)。
- 発火するのは親が応答していないときだけで、繰り返しは既定で 7 日で失効します(本体の既定値。設定で変わりうるので、張ったときに伝える値を正とします)。
- タイマーで入った親は、完了の通知が来ていない実装役・関門の体(タイマーを張った後に台帳が更新された進行中の周の体)を起こし直しません——動いている前提で台帳と worktree の実物だけを見て、 続けられる周が無ければ何もせずに戻ります。 ただし、その周の worktree が間隔の 2 回分(30 分おきなら 60 分)動いていなければ、その周の子に状態を訊き(訊いたことを台帳のメモに残します)、訊いてからさらに 2 回分たっても動かず返事も無ければ、 その周を止まった扱いにしてメモを残します(載せ替えはしません。#792—— 周の体が背景のコマンドの完了の通知を待ったまま止まり、親が気づかなかった。時間の値は推奨で決めたもので、確認の Issue #827 があります)。 タイマーを張っていなければ、このように止まった周は戻ってくるまでそのままです。
- 子が背景のコマンド(
check-all.pyなど)を起こしてターンを終えたとき、親はその終わりを見張ります——完了の通知が止まった子を起こさないことがあり(#1144。 約 9.6 時間止まった実例があり、通知で起きない条件は特定していません)、終わって 2 分たっても子が動かなければ、親が子に催促します。子は、待つなら報告に待っているもの (task の ID・出力ファイル・終わりの印)を書きます。 親が自分でタイマーを止めた後、同じ親の会話の中で周が動き出したときは、台帳の記録が「張った」なら、張り直します(訊きません)。打ち直した起動(同じ会話の中で打ち直しても、/clearの後・別のセッションも)は対象外で、上の「利用者が居る再開では、タイマーが無ければもう一度訊きます」と、下の「不在の再開でも訊かず、2 本目のタイマーも張りません」が決めます。 -
タイマーは同じ引数に印
--timerを付けて起動します(人は打ちません)。この印のある起動(タイマーの発火)では、居る cruise でも起動時の問いを出しません。/clearして自分で打ち直した再開では、これまでどおり訊きます。 不在の再開でも訊かず、2 本目のタイマーも張りません。 -
親は周の worktree に入りません(#484)。各周はサブエージェントが worktree の絶対パスで回し、親はメインの作業ツリーに留まります。 #484 では、周の worktree に入った親が
/clearしてもその worktree に隔離されたままになり、次の周を始められなくなりました。 - 会話の中で決めた、進めてよい範囲を広げる方針は、台帳に残りません。 線の項目(
仕様の穴など)に当たるなら、親 Issue のcruise:の行に書き、 起動し直したときに確かめてください(席を外したままの再開では、台帳の線は書き換わりません)。 「#N はマージしないで」「#M は回さないで」のような止める指示は、親がその場で台帳のその行に書くので、compact の後も残ります。 - 着手できる周が残っているのに親が次の周を始めないと決めたら、親はこの cruise を再開するタイマーを止め、
/clearしてメインの作業ツリーから起動し直すよう通知して止まります。タイマーは/clearできないので、放っておくと同じ判断を繰り返すだけになります (#484 では 23 回・約 11.5 時間、周が 0 本でした)。タイマーを使い続けるなら、起動し直すときに張り直してください。 - 周を
claude -pの子プロセスで回すこともできます(任意。#491)。 子は親から切り離して起きるので、親が/clearしても走り続け、起動の時点で入っている版を読み込みます。 再開した親は、走っている子の周に 2 体目を起こしません。既定はサブエージェントのままです——関門が子の中で回りきるかと、 利用上限で何が起きるかを、実際の周ではまだ確かめていません。回し方と確かめた範囲は../cruise/references/child-process.mdを正とします。 - 前の版の親が worktree の中に残っていたら、再開時の点検がそう言います。親は
ExitWorktree(keep)を 1 度だけ試しますが、 戻れた例は 1 件しか観測していません。戻れたかはcd <メインの作業ツリー> && git worktree listを打って確かめ、拒まれたら戻れなかったものとします (claude -wとEnterWorktree(name)で隔離したセッションではこの形が拒まれ、ExitWorktreeで戻った後は通ることを測ってあります。 #484 の形——EnterWorktree(path)で入って/clearした隔離——では測っていません。cdの無いgit worktree listは隔離中でも通るので確かめになりません。#504)。 戻れなければ、メインの作業ツリーで新しいセッションを開いて起動し直してください。
claude -p で外から回すとき
cruise を対話のセッションではなく、外側のループ(シェルのスクリプトなど)から claude -p "/dev-loop:cruise <親> --absent" で起動し直して回すときの注意です
(#633)。
-pは、ターンが閉じた後の背景のタスクを上限の時間しか待たず、過ぎると止めます。 spin-dd/tfs-stocks#2427 では、周の子を背景で起こして 「待ちます」と書いてターンを閉じた親の子が、10 分で関門の途中で止められ、次の起動が周をやり直しました。標準エラーにはBackground tasks still running 10m after the last turn (…); stopping them. Set CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0 to wait indefinitely.と出ます。 親は周の子を前景で呼ぶ決まりですが(スキル本文の「4. 周を回す」の 2)、並行に始めてよい周を 2 本以上回すときは背景で起こします。 外側のループはCLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0を置いて起動してください。 0 で止めずに待つことは、上の標準エラーの文言によるだけで、測っていません。- タイマー(
CronCreate)は要りません——起動し直すのは外側のループです。タイマーはそのセッションの中にしか無く(上の「5. 再開する」)、-pのプロセスが終わった後に発火するかは確かめていません。外側のループは--absentで起動し直すので、再開でタイマーを訊き直しません(#472)。 - 続けるかは
ledger.py statusの終了コードで決めます(#632)——0 なら進められる周がある、 3 なら人を待つ周だけ、5 なら親 Issue の一覧の行がすべて済んだ、4 なら判定できなかった(済んだとは答えていません)。文面(show)で決めないでください。 判定の順はledger.pyの docstring を正とします。 - 0 でも、1 回の起動で周が進まなければ止めます——マージの線が無く親がマージせずに止まった PR の行などは、
statusが 0 のまま残り、起動し直しても進みません。 進んだかは台帳のファイル(updatedを除いてもnoteの書き直しが残る)ではなくledger.py progressで比べます。claudeが 0 以外で終わったときも止めます(ログインの期限切れなどで、何も進めずにすぐ終わる起動を繰り返さないため)。 ループは手で書かずに、同梱のouter-loop.pyを使ってください——下の「外から繰り返し起動するとき」(#791)。
利用上限で止まったとき
autoContinueAtUsageLimit: true だけで続くとは、記録からは言えません。 下の表のとおり、待ちを張らなかった停止(理由は記録に残りません)と、
Claude Code が終わって消えた待ちがあります。一方で、張った待ちが予告の時刻まで放っておかれたのに自動継続しなかった例のうち、
理由が分かるのは取り消された 2 件だけで、残る 1 件は理由が分かりません——根拠は数件です。
不在で回すなら、タイマーを保険として張るかを考えてください(張るかは利用者が決めます)。
手元 1 台のトランスクリプト(2026-08-27〜10-23・main-chain)を scripts/count-usage-limit-resumes.py で数えた結果です(#454):
| 待ち | |
|---|---|
| 上限で止まった待ち | 68 |
うち自動継続の待ちを張った(continuing automatically at … の予告が出た) |
65 |
| 予告の時刻の 1 分後に自動継続した | 8 |
| 予告の時刻より前に、人間の入力かローカルコマンドが来た | 51 |
| 予告の時刻の後、自動継続より先に人間が来た | 3 |
| Claude Code が待ちの間に終わって取り消された | 2 |
| 何も来ずに記録が終わった | 1 |
うち待ちを張らなかった(3 件とも週の上限 seven_day) |
3 |
- 張った待ちで、人間が予告の時刻まで来なかったものは 14 件で、自動継続したのは 8 件です。 残りは人間が数十秒先に来た 3 件・取り消された 2 件・理由の分からない 1 件です
- 待ちを張らなかった停止があります——張らなかった 3 件は、どれも週の上限(
seven_day)でした。 ただし週の上限で止まった 4 件のうち 1 件は張っているので、週の上限なら張らない、とは言えません (張らなかった理由は記録に残りません) - Claude Code が終わると待ちは消えます(
Automatic continue cancelled · Claude Code exited during the wait) - どの層の設定から待ちを張ったのかは分かりません——設定の履歴は記録に残りません。
数えた日(2026-10-27)の手元の user の settings に
autoContinueAtUsageLimitはありませんでしたが、 それぞれの停止の時点の値は分かりません。数え方と、数えないものはスクリプトの docstring を正とします - 上限を狙って起こす手段が無いので、user の層に
trueを明示したうえで自動継続した例は、まだ取れていません(#454)
外から繰り返し起動するとき(外側のループ)
cruise を対話のセッションではなく、外側のループから claude -p "/dev-loop:cruise <親> --absent" で起動し直して回すなら、
ループを手で書かずに同梱の outer-loop.py を使ってください(#791)。
手で書いたループが前進を台帳のファイルのハッシュで見ると、親が note を書き直すだけの起動でも更新時刻(updated)が変わって「前進あり」になり、
「前進なしで止める」が効きません——spec-loop の自動運転では、止まったことを見落としたループが claude -p を約 1,900 回起こし直しました(#790)。
cd <メインの作業ツリー>
python3 <スキルの base ディレクトリ>/../cruise/scripts/outer-loop.py 50 --absent -- --permission-mode auto
- 起動の前に毎回
ledger.py status issue-<親>を見て、0(進められる周がある)のときだけ起こします。 3(人を待つ周だけ)・5(親 Issue の一覧の行がすべて済んだ)・ 4(判定できなかった)では起こさずに止まります。 - 1 回の起動で周が進んだかは
ledger.py progress issue-<親>(行ごとの番号・状態・PR・まとめ。更新時刻とnoteを含みません)を前後で比べます。 変わらない起動が続けて 2 回(--max-stalls)で止まります。 - 起動の総数の上限(
--max-launches。既定 20)と、claudeが 0 以外で終わったときも止まります。 - 費用の合計の上限(
--max-total-usd <ドル>。既定なし)を渡すと、親の起動ごとの費用(出力の最後のresultのtotal_cost_usd)と、このループの後に起きた子プロセスの周(child-cycle.py)の費用を足し、合計が上限以上になったら次を起こさずに止まります(#992)。 費用を取れなかった起動は 0 と数えず、上限を渡していれば止まります。上限は目安です——値は API の料金に換算した推定で、1 回の起動の途中では止めません。止まった行と通知には、上限を渡していなくても費用の合計と取れなかった数が出ます。起動ごとの出力は台帳の隣のcruise-issue-<親>-loop/に残ります(claudeの出力は端末には出ません)。 - 止まると理由を出力の最後の行に出し、macOS なら通知します(
osascript。通知が見えるかは macOS の通知の設定によります)。終了コードで理由を分けます。 - 起こす
claudeには、非対話の起動の決まり(権限に拒まれたら周を利用者の操作待ちにして次へ進む・進められる周が無いなら台帳を書き換えずに終える)を--append-system-promptで渡し、CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0を置きます(-pがターンの後の背景のタスクを 10 分で止めないように。#633)。 親がその決まりに実際に従うかは、本物のclaude -pで確かめていません。 - 許可モード・モデルなどは
--の後ろに足します(上の「2. 環境を点検する」で決めたもの)。claude以外のコマンドで起こすなら--claudeで名指しします。
止まる条件・終了コード・守らないものはスクリプトの docstring を正とします。
6. 戻ってきたら見るもの
- 台帳——
ledger.py show issue-<親>で、どれがマージ済みで、どれが止まっているか(noteに理由)。 - 利用者の操作待ち——台帳の「利用者の操作待ち」に、打ってほしいコマンドが周ごとに載っています。 打ったあとで同じ引数で起動し直すと、cruise が実物を確かめてからその周の続きを回します。
- 利用者の確認待ち(実機確認)——
Refsでマージした周が、確かめる受入基準つきで載っています。手元の実機で確かめたら元の Issue を閉じます。 台帳がmergedになるのは、次に cruise を起動したとき(閉じたのを実物で確かめてから)です。親 Issue の一覧の行なら、それまではledger.py statusも「済んだ」(5)と答えません。周の途中で足した行の確認待ちは、5 を答えるときも括弧の中に名指しされます——5 は確認待ちが残っていないことを意味しません。 - 各 PR のコメント——関門の残課題、名指しの未証明、訊かずに進めた箇所が書かれています。
マージの線でマージした PR も、戻ってから PR コメントで確かめる前提です。 Issue にしなかった指摘は「記録だけ(起票しない。#774)」の見出しに並びます——実際に問題が起きたら、そのときに起票します。 - 片付けで残した worktree——cruise は周をマージするたびに、その周の worktree とローカルブランチを消します。未コミットの変更がある木などは消さずに、
台帳のメモ(
片付けで残した:)と終える報告に載ります。消すか(変更を捨てるか)は利用者が決めます。 終える報告には、残っているリモートのブランチの本数と、その PR の状態(OPEN・MERGED・CLOSED・PR なし)ごとの内訳も載ります——リモートのブランチは消しません(#823)。 - cruise が終わるのは、親 Issue の一覧にある課題が済んだときです——周の途中で足した課題が残っていれば、回さずに一覧で渡されます。
- 終える前の main の歯止め——cruise は終える前に、続けてマージした結果の main の先端で全部の歯止め(このリポジトリなら
check-all.py)を 1 回流し、 本数・失敗の数・流した main の SHA を終える報告に書きます。PR ごとの CI がそれぞれ通っても、続けてマージした結果で初めて壊れることがあるからです。 落ちていれば、落ちた検査と出力の要点を書いた直しの Issue が立って渡されます(cruise の中では直しません。直すかは利用者が決めます。#831)。 - 題の先頭が
要確認:の Issue(ラベル要確認も付きます。ラベルが無いリポジトリでは題だけです)——仕様の穴の線で、 推奨で決めて進めた判断です。閉じずに残してあります。cruise から立てたものは台帳の「要確認」の列に番号が載り、 終えるときに開いているものが一覧で渡されます。- 1 件に判断は 1 つです。 本文の冒頭の 3 行(何が起きたか・選べること・何もしなければどうなるか)と、
その下の「重さ」(済んだことか、PR にあってまだマージしていないことか、まだしていないことか)を読めば、何を判断すればよいかが分かるように書いてあります
(書き方の決まりは dev-loop の
references/absent-lines.mdの「確認の Issue の書き方」)。 - 承認するなら、その Issue を閉じます。 閉じるのは利用者だけです——cruise(親・周・検証)は閉じません。
cruise が GitHub に書くコメント・PR の本文の先頭には印(
<!-- dev-loop: 子 #<番号> -->など。画面には出ません)が付き、 終えるときに、閉じの印(<!-- dev-loop-close: … -->)のあるコメントを添えて閉じられたものや PR のマージで閉じたものは「利用者の承認ではない」として一覧に残ります (決まりは dev-loop のskills/cruise/SKILL.mdの「GitHub に書くものの印」。#636)。 - 直すなら、本文の「別の値を選んだら」から実装の Issue を立てて親 Issue のチェックリストに足し、 確認の Issue はその番号を書いて閉じます。同じ引数で起動し直すと、足した Issue が名指しされます(台帳に足すかは利用者が決めます)。
- spec-loop から来た Issue の穴の確認の Issue は、承認するときも直すときも、閉じる前に本文の Q&A の行を正本の Q&A 表に足して
req-loopに載せます—— 閉じるだけでは仕様に穴が残ります。実装の Issue は立てず、要求側で作り直した Issue が受け持ちます(#470)。
- 1 件に判断は 1 つです。 本文の冒頭の 3 行(何が起きたか・選べること・何もしなければどうなるか)と、
その下の「重さ」(済んだことか、PR にあってまだマージしていないことか、まだしていないことか)を読めば、何を判断すればよいかが分かるように書いてあります
(書き方の決まりは dev-loop の
- 開いたままの元の Issue——
実機確認の線でRefsのままマージした Issue です。実機で確かめてから閉じます。 - 起動時の点検の到達で止まると出た周——PR が main と衝突している・同じプラグインの版を上げる PR が重なっている・
マージの前の判断待ち・
マージの線が効かない、など。台帳の状態はprのままで、上のどこにも出ないことがあるので、 cruise は終えるときに点検を回し直して理由ごと渡します(#490)。
関連
- プラグイン一覧 — dev-loop
- dev-loop の設計(ループ志向開発)
- リモートコントロールの設定手順(不在中の運用)
- #389 オートクルーズ(要件の出所と、部品への分け方)