同じ記事生成の手順なのに、デスクトップで動かしたときと CLI で動かしたときで、出来上がりが微妙に違うことに気づいた時期がありました。原因をたどると、品質ゲートの順番をある日デスクトップ側だけ直していて、CLI 側には古い順番が残っていました。どちらも「正しい手順」のつもりで動いていたのに、正しさの中身が食い違っていたのです。
Antigravity 2.0 でデスクトップアプリ・CLI・SDK と入口が増えたいま、この食い違いは放っておくと必ず広がります。面が増えるほど、同じ作業の指示を置く場所も増え、片方だけ直して片方を直し忘れる事故が起きやすくなります。ここでは、手順を面ごとに持たせず、1つの版管理されたファイルへ集約する設計を書きます。
手順が「散らばっている」状態を疑う
最初に見直すべきは、同じ作業の手順が複数の場所に書かれていないか、という点です。デスクトップの設定、CLI のスクリプト、SDK の呼び出しコードに、それぞれ似た手順が埋め込まれていたら、それはすでに散らばっています。
散らばった手順は、最初は同じ内容です。問題は時間です。運用していれば手順は必ず変わります。変えるたびに全部の場所を同じように直せる、という前提は、人がやる以上いつか崩れます。崩れた瞬間から、面ごとに違う作業が静かに走り始めます。
手順を1つのファイルに引き出す
解決の方向はシンプルです。手順そのものを各面から引きはがし、1つのファイルに書き、各面はそれを読むだけにします。指示文や品質ゲートの順番を「コード」と同じように1か所で管理する発想です。
# pipeline.yaml — 手順の唯一の正本
version: 7
steps:
- id: draft # 下書き生成
prompt_ref: prompts/draft.md
- id: gate-quality # 品質ゲート(順番もここで固定)
run: [article_gate, templating_gate, frontmatter_integrity]
- id: bilingual # 日英そろえる
require: { ja: true, en: true }
- id: publish
when: all_gates_passed
デスクトップも CLI も SDK も、自前で手順を持たず、この pipeline.yaml を読み込んで実行するだけにします。こうすると、手順を変えたいときに直す場所が1か所に決まります。順番を入れ替えたいなら steps を編集すればよく、その変更がすべての面に同時に効きます。
版番号と git で「いつの手順か」を固定する
ファイルに version を持たせ、git で履歴を残すのが二つ目の柱です。これがあると、夜間に走ったジョブがどの版の手順で動いたかを後から特定できます。
| 持たせる情報 | 役割 |
|---|
| version 番号 | 実行ログに記録し、どの手順で動いたか追える |
| git 履歴 | 壊れる前の正しい手順へ戻せる |
| 変更時の検証 | 不正な手順が本番へ流れるのを止める |
私は実行ログの先頭に必ず手順の版番号を書き込んでいます。生成物が変だと感じたとき、まず「どの版で動いたか」を見れば、原因が手順の変更にあるのか、それ以外にあるのかを切り分けられます。版番号がないと、この切り分けに毎回30分以上溶かしていました。
手順が静かにずれていく3つの経路
1か所に集約しても、油断するとまたずれます。私が経験した「ずれの再発経路」は3つあります。
第一に、その場修正です。デスクトップで作業中に手順を少し直し、それを正本のファイルへ戻し忘れる。直したつもりが、次に CLI で走らせると元のままです。私は、手順をその場で変えたら必ず正本へ反映する、を徹底し、デスクトップ側で直接書き換える経路自体を塞ぎました。
第二に、コピーの増殖です。新しい面を足すときに、既存の手順をコピーして持たせてしまう。コピーした瞬間は同じでも、以後は別々に育ちます。新しい面でも、コピーではなく正本を参照させるのが鉄則です。
第三に、面固有の例外です。「CLI のときだけこの一手間を足したい」という要求は必ず出ます。これを手順本体に書き込むと、正本が特定の面に依存して濁ります。私は例外を本体に混ぜず、面ごとの薄い設定として外側に出し、正本は面に依存しない形を保っています。
変更時に機械で検証する
手順をファイルにしておく最大の利点は、変更を機械で検証できることです。私は正本を変えたときに、形式の正しさと、各面が問題なく読めるかを自動で確かめています。
# validate-pipeline.sh — 正本の変更を本番へ流す前に検証
set -euo pipefail
python3 -c "import yaml,sys; yaml.safe_load(open('pipeline.yaml'))" || { echo "❌ YAML 構文エラー"; exit 1; }
agy pipeline lint pipeline.yaml # 未定義の step や prompt_ref の欠落を検出
agy pipeline dry-run pipeline.yaml --surface cli --surface sdk
echo "✅ 正本 v$(grep '^version:' pipeline.yaml | awk '{print $2}') 検証 OK"
--surface cli --surface sdk のように、複数の面で同じ手順が読めるかをまとめて確かめているのが要点です。ここで片方の面だけ失敗すれば、本番に出る前に食い違いを捕まえられます。検証を変更の手前に置くだけで、冒頭のような「面ごとに違う正しさ」が走り出すのを防げます。
どの面から寄せるか、順番を決める
すべての面を一度に正本へ寄せようとすると、移行そのものが大きな作業になり、かえって途中で頓挫します。私は次の順番で、少しずつ寄せることをお勧めします。
- いちばん頻繁に走る面から正本参照へ切り替える。効果がすぐ実感でき、最初の検証も兼ねられます
- 次に、止まると収益に直結する面を寄せる。私の場合は AdMob や App Store の配信に関わる手順がここに当たります
- 最後に、たまにしか使わない面を寄せる。ここは後回しでも被害が小さい落とし穴だからです
この順番には理由があります。頻度の高い面ほど、ずれたときの影響が早く広く出ます。先に押さえておけば、移行の途中で事故が起きても本番への被害を小さく抑えられます。逆に、たまにしか使わない面から手を付けると、労力の割に得られる安心が薄く、移行が続きません。
注意点として、寄せる途中は「正本参照の面」と「旧来の直書きの面」が混在します。この混在期間こそ食い違いが起きやすいので、私はどの面が移行済みかを一覧で管理し、未移行の面では重要な変更を避ける運用にしています。移行のさなかに大きく手順を変えると、旧来の面に反映が回避され、静かなずれを生むからです。少しずつ寄せるほど安全だと、私は実体験から考えています。
個人開発でここまでやる意味
正直なところ、手順が2つや3つの面に散っていても、しばらくは動きます。私自身、4サイトの自動投稿を始めた頃は各面に手順を直書きしていました。けれど面が増え、手順を変える頻度が上がると、直し忘れによる小さな食い違いが毎週のように出るようになりました。
1つのファイルに寄せてからは、修正の反映漏れがほぼ消えました。直す場所が1か所だからです。個人開発は人手が自分1人しかいないからこそ、「全部の場所を漏れなく直す」前提に頼らない設計が効きます。私は、手間を増やす設計ではなく、思い出さなくて済む設計を選ぶようにしています。
次の一歩
まず、いま動いている自動運用の手順が何か所に書かれているかを数えてみてください。2か所以上あれば、それは将来ずれる候補です。次に、その手順を1つのファイルに書き出し、いちばん使う面だけをそのファイル参照に切り替えてみてください。1か所を直せば全部に効く、という手触りが分かれば、残りの面も自然に寄せていけます。