メインコンテンツへスキップ
見出し画像

Coding Agentの再実行事故を防ぐ3層設計|main・認証・外部状態を分ける

    AI・データ・開発の関連書籍をもう少し探したい方は、Book Media Techでテーマ別に比較できます。

    Book Media TechでAI・データ・開発の本を探す

    AI・データ・開発の本を探す|Book Media Tech
    AI・データ・開発の本を探す|Book Media Tech

    ※この記事にはAmazonアソシエイトリンクが含まれます。

    Coding Agentに「続きを進めて」と頼む。

    一見、単純な指示です。ところが実務では、この「続き」がいちばん危ない。

    • 新しいworktreeは、どのcommitから作られたのか
    • 保存済みのログイン状態は、どこにあるのか
    • 前回のAPI呼び出しは失敗したのか、それとも成功後に応答だけ途切れたのか

    この3つを混ぜたまま再実行すると、古いコードで作業したり、別accountを触ったり、同じ下書きや公開処理を重ねたりします。

    今回、複数のnoteアカウントを連続公開する仕組みを実際に直して分かったのは、Coding Agentの自動化で本当に怖いのはAPIそのものではない、ということでした。

    怖いのは、結果が分からないまま、同じ操作をもう一度走らせることです。

    先に結論:安全な自動化は3つの状態を分ける

    私がいま採用しているのは、次の3層です。

    1. コード状態:最新mainを開始点の正本にする
    2. ローカル認証状態:保存済みprofileを共有し、Gitへ入れない
    3. 外部副作用状態:GET-firstで現状を確認し、再実行可否を決める

    大事なのは、「すべてを同期する」ことではありません。

    層ごとに正本が違うと認め、毎回それぞれを確認することです。

    画像
    コード状態、ローカル認証、外部状態の正本と確認動作を示す3層モデル

    この3層を分けると、「どこまで自動で進めてよいか」「どこで止まるべきか」をCoding Agentへ明確に渡せます。

    Layer 1:最新mainは「開始点」の正本

    新しい記事や機能を作るなら、作業branchは最新のmainから切る。

    これは基本です。ただし、意外と「自動でそうなる」と思い込まれています。

    実際には、現在開いているbranchから新しいbranchを作れば、そのbranchの古さや未反映変更も引き継ぎます。worktreeを使っていても、作成元を明示しなければ安全は保証されません。

    開始時に必要なのは、次の3点です。

    1. originの最新状態を取得する
    2. origin/mainのcommitを開始点として固定する
    3. そのcommitから専用branchとclean worktreeを作る

    ここでの正本は「手元のmain」ではなく、確認済みのorigin/mainです。

    手元のmainは別作業で止まっているかもしれません。だから、fetchしたうえで、作業開始時のbase commitを記録します。

    なお、Gitのworktreeはrepositoryの参照を共有しますが、HEADやindexなどはworktreeごとに分かれます。つまり、複数作業を並行しやすくなる一方で、「いまどのbranchを見ているか」は各worktreeで確認しなければなりません。

    Layer 2:認証はcopyせず、shared rootから解決する

    次に詰まったのが、保存済みログイン状態でした。

    コードは最新mainからclean worktreeへ持ってこられます。しかし、Cookieやstorage stateを含むローカルprofileは、通常Gitで管理しません。新しいworktreeに、無視された.local配下のfileが自動で現れるわけでもありません。

    ここでやってはいけないのが、認証profileを作業worktreeごとにcopyすることです。

    • copyが古くなる
    • accountの取り違えが起きる
    • 誤ってGitへ追加する面が増える
    • どれが正本か分からなくなる

    今回の修正では、linked worktreeの.git情報からrepositoryのshared rootを解決し、primary worktree側の保存済み設定とprofileを参照するようにしました。

    ポイントは、相対pathの基準です。

    悪い例:現在の作業directoryを基準にprofileを探す
    良い例:設定fileが属するshared rootを基準にprofileを解決する

    これなら、コードはbranchごとに分離しつつ、認証情報は1つのローカル正本へ集約できます。

    もちろん、認証profileはGitへcommitしません。記事やIssueへCookie、token、PC固有pathを書かないことも必須です。

    Layer 3:外部操作は必ずGET-firstで再開する

    最も重要なのが、外部サービスの状態です。

    たとえば「下書きを作る」APIを呼び出した直後に通信が切れたとします。

    画面にはtimeoutと出ている。でも、server側では下書きが作られているかもしれない。

    このとき、同じPOSTをすぐ再実行すると、下書きが2つできます。公開処理なら、さらに慎重であるべきです。

    そこで再開手順を、次の順に固定します。

    GET current state
      ↓
    期待する対象が存在する?
      ├─ Yes:account・title・本文・画像・公開状態を照合
      │        └─ 一致するなら次のstateへ進む
      └─ No :「存在しない」と確認できた場合だけ作成する

    これがGET-firstです。

    単に「最初にGETする」のではありません。mutationの結果が不明なら、次のmutationを禁止し、外部状態の確認へ戻すという運用規則です。

    今回の公開実装では、処理をおおむね次のstateで管理しました。

    planned
    → draft_saved
    → authorized
    → publishing
    → published
    → verified

    そして、公開前には次を照合します。

    • 対象accountが期待どおりか
    • note IDとdraft IDが確定しているか
    • titleと本文が固定済みか
    • 本文hashが承認後に変わっていないか
    • 予定した本文画像とタイトル画像が存在するか
    • すでに公開済みではないか

    すでに公開済みなら、公開を再クリックしません。公開ページの検証へ進みます。

    この「状態を先に読む」設計が、API-first運用を安全にしています。

    「mainから始める」を本当に自動化するには

    ここで、よくある誤解を1つ。

    運用ルールに「最新mainからbranchを作る」と書いただけでは、自動化されていません。

    本当に保証するなら、作業開始のstarterやguardが必要です。

    最低限、次を機械的に確認します。

    - fetch後のorigin/mainを取得したか
    - 新branchのmerge-baseが開始時のorigin/mainか
    - 作業worktreeがcleanか
    - 既存の同名branch / worktreeと衝突していないか
    - 保存済みaccount profileを解決できるか

    どれかが崩れていたら、記事を書き始める前に止める。

    文章生成を速くするより、入口で誤った状態を弾くほうが、後戻りを大きく減らします。

    今回入れたworktree修正は、保存済みprofileを正しく見つけるためのものです。「今後すべての作業が自動的にmainから始まる」ことまでは保証していません。

    だから次の改善は、main起点を実行時に検査するstarter / guardです。

    実装するときの最小チェックリスト

    Coding Agentへ外部操作を任せるなら、私は次の9項目を最低ラインにします。

    コード状態

    • [ ] 最新origin/mainのcommitを取得した
    • [ ] 専用branch / worktreeのbaseを記録した
    • [ ] 他の作業中変更を持ち込んでいない

    ローカル認証状態

    • [ ] accountとprofileの対応が設定で固定されている
    • [ ] linked worktreeからshared rootを解決できる
    • [ ] Cookie・token・PC固有pathをGitやIssueへ出していない

    外部副作用状態

    • [ ] mutation前に対象をGETした
    • [ ] 結果不明時はblind retryせず、照合stateへ戻る
    • [ ] 完了条件を「APIが200」ではなく、read-back / public verifyで判定する

    3層のどれか1つでも曖昧なら、自律実行を広げる前に止めたほうがいいです。

    個人の実装から、チームの運用規定へ

    ここまでの話は、個人のscriptにも使えます。

    ただし、複数人・複数Agentで回すなら、「誰がどの状態を変更できるか」「結果不明時に誰が再開を判断するか」まで文書にする必要があります。

    権限Level、禁止操作、監査ログ、停止機構をチームの規定へ落としたい人は、次の雛形を使ってください。

    ▶ そのまま使える「AIエージェント運用規定」雛形

    この記事の3層設計を、組織の承認フローへ広げるための次の一歩になります。

    GET-first / STOP / RecoveryをCoding Agent全体の運用へ広げる

    この記事のGET-firstや再実行安全性だけでなく、仕事を渡すWork Contract、Context & Source of Truth、Task Decomposition、Validation / STOP / Completion、Review / Recoveryまで一つの運用として整理した実務Kitがあります。

    → Coding Agent Best Practices Kit(2,980円)を見る

    「失敗しない自動化」ではなく、失敗や中断が起きても安全に止まり、Evidenceを確認して再開できる運用を作りたい人向けです。

    この考え方を実務へ落とすための一冊

    自動化を単発のscriptではなく、「変更を安全に届け続けるprocess」として学びたい人には、Christie Wilson著『入門 継続的デリバリー』が参考になります。

    AIエージェント専用の本ではありません。しかし、変更・test・releaseを小さく確認しながら進める考え方は、Coding Agentの再実行設計にも直結します。

    ▶ Amazonで『入門 継続的デリバリー』を見る

    まとめ

    Coding Agentの自動化で重要なのは、「何でも自動でやる」ことではありません。

    再開時に、何を正本として読み直すかを決めておくことです。

    • コードは最新main
    • 認証はローカルの共有profile
    • 外部操作はGET-firstで取得した現在状態

    この3つを分け、結果不明なら止まる。

    それだけで、自動化は「一度動くdemo」から「失敗後も安全に続けられる運用」へ変わります。

    #AI #生成AI #AIエージェント #CodingAgent #Codex #Git #GitWorktree #DevOps #自動化 #AI駆動開発

     
     
    生成AIを「知っている」から「実務で成果を出す武器」へ。AI駆動開発・Claude Code・AIエージェントを中心に、丸投げしない設計と現場で使える判断軸を解説。 As an Amazon Associate, I earn from qualifying purchases.

    あなたへのおすすめ