実行リソースと cleanup 対象の管理
Level 1 では、状態ファイルや台帳は不要なことが多い。 branch / worktree を分け、起動、test、E2E、PR、cleanup を作業ごとに直列で進めるところから始める。
最初の 2 並列では、状態ファイルや lock を先に作らず、terminal、dashboard、作業メモで local の対応関係を追えればよい。
PR 本文には、レビューアに意味のある変更内容と検証結果だけを書く。 local URL、worktree path、cleanup 状態は、レビューに必要な場合を除いて PR 本文に含めない。
最初に記録するもの
Level 2〜3 へ進む時も、最初から global な状態管理を作る必要はない。 まずは、作業ごとに次を確認できればよい。
| 項目 | 見る理由 |
|---|---|
| 作業名 / branch / worktree | どの差分を見ているかを確認する |
| URL / port | 手動確認や E2E の接続先を取り違えない |
| DB / schema | 状態を書き換える検証が他作業へ影響しないか確認する |
| cache / queue | prefix や queue 名が混ざっていないか確認する |
| artifact | どの作業の検証結果かを後から説明できるようにする |
| cleanup 対象 | 消してよい process / container / volume を取り違えない |
この表は、作業メモ、dashboard、terminal 一覧、ツールの workspace metadata のどれで管理してもよい。 必要になるまで専用の JSON 状態ファイルを作らなくてよい。
完全分離と共有リソース内分離
完全分離できる場合は、worktree ごとに process、Docker Compose project、DB container、cache、queue、artifact 置き場まで分ける。 他の worktree の状態を知る必要が少なく、cleanup の範囲も判断しやすい。
一方で、ローカルでは完全分離が重くなることがある。 並列数が増えるほど、CPU、memory、disk、起動時間、seed 時間、cleanup コストが増えるため、同じ DB server や cache を共有し、その中で database 名、schema 名、cache prefix、queue 名を作業ごとに分けることがある。 これは実用的な妥協だが、完全分離ではない。
| 方式 | 例 | 長所 | 注意点 |
|---|---|---|---|
| 人間が直列に使う | 差分作成は並列、起動・検証は作業ごとに直列 | 最小導入に向く。既存プロジェクトに入れやすい | 検証は並列にならない。人間の確認待ちは残る |
| 完全分離 | worktree ごとに Compose project、DB container、cache container、artifact dir を分ける | 分かりやすい。他の作業を知る必要が少ない。cleanup しやすい | 並列数が増えると CPU、memory、disk、起動時間が重い |
| 共有リソース内で名前を分ける | 同じ DB server 内で schema を分ける。同じ Redis で prefix を分ける | 軽い。起動が速い。ローカル PC への負荷を抑えやすい | 完全分離ではない。prefix 漏れや cleanup 誤爆が起きうる。本番や CI と構成がずれる可能性がある |
共有リソース内の分離は local 開発のための仕組みとして扱う。 DB server 全体の設定、connection limit、global lock、cache memory、queue worker、共通 cleanup script などは共有される場合がある。 最終的には CI や本番に近い環境で検証する。
古い検証結果を使わない
branch の HEAD、base branch、URL、DB / schema、feature flag、E2E 接続先が変わったら、以前の検証結果をそのまま使わない。 状態ファイルを作るかどうかに関係なく、検証結果がどの branch / URL / DB に対応していたかを説明できる必要がある。
次のいずれかが変わったら、対象作業の検証をやり直す。
- branch の HEAD が変わった。
- base branch を取り込んだ。
- URL、DB、cache、queue、env、feature flag が変わった。
- E2E の接続先が、確認したい作業の URL と一致しない。
よくある失敗
| 失敗 | 原因 | 止め方 |
|---|---|---|
| 別作業の URL を E2E した | 固定 URL を使った | terminal、dashboard、作業メモで対象 URL を確認する |
| 古い検証結果を信用した | branch、base、URL、DB / schema が変わった | どの branch / URL / DB の結果か説明できなければ再実行する |
| cleanup で他作業を壊した | 所有者と実リソースの対応を確認しなかった | 削除してよい process / container / volume を作業ごとに確認する |
| 状態メモだけ正しい | 実環境が落ちている、または別 URL を見ている | メモと実際の process、URL、DB を照合する |