AIエージェントが壊さない開発環境：Cloudflare D1 ローカル自律化と「状態管理」の物理学

著者: ClaudeMix Team | 2026.02.28

はじめに

wrangler login やAPIトークンに頼るローカル開発環境は、Cloudflareとの接続が切れた瞬間にAIエージェントも人間も作業が止まります。D1のローカルモードを「外部状態への依存をゼロにした成果物」として設計し直すことで、再現性・決定性・CI親和性を同時に手に入れられます。

「認証地獄」という言葉は、実は正確ではありません

開発環境の構築でCloudflareへのログインを求められ、APIトークンに悩み、作業が止まる。
これを多くの人は「認証の問題」と呼びますが、本質はそこにはありません。

本当の問題は、「外部状態への依存」です。

「クラウドにログインしている」という、コードベースの外側にある不安定な状態に、開発環境の成否が委ねられている。
この構造こそが、開発の再現性を殺し、AIエージェントの自律稼働を阻害する真犯人です。

この記事をお勧めしない人

開発環境は「なんとなく動けばいい」と考えている人。
「環境構築」をエンジニアリングの対象ではなく、単なる作業だと思っている人。
AIにコードを書かせるだけで、その足場となる「状態」を管理する責任を放棄したい人。

外部依存が招く「決定性の欠如」

ログイン状態やネットワーク接続といった「外部要因」に依存する環境は、本質的に非決定的です。「昨日動いたのに今日は動かない」「AさんのPCでは動くがBさんでは動かない」といった問題は、この非決定性に起因します。

特に、前提条件の安定性を無邪気に信じるAIエージェントにとって、この非決定性は致命的です。

環境は「依存物」ではなく「成果物」である

この問題を解決する唯一の方法は、思想を転換することです。環境を「設定するもの（依存物）」から、「コードから生成されるもの（成果物）」へと再定義します。

この記事で提示するのは、以下の3つの制約条件を満たすことで、D1ローカル環境を「成果物」として扱うための設計思想です。

再現性 (Reproducibility)
決定性 (Determinism)
CI親和性 (CI-Friendliness)

これは単なるD1の解説ではなく、「AIエージェントが壊さない開発環境」をどう設計するかという、これからの時代のエンジニアリングの核心です。

このブログもそうでした

本プロジェクト「ClaudeMix」でも、初期は「Cloudflareのローカルモードをなんとなく使う」段階に留まっていました。
しかし、AIとの協調開発を進める中で、「AIはコードを書くが、状態は保証できない」という壁に直面しました。
この記事で、人間が担うべき「状態管理」の物理モデルと、それを実装に落とし込むための具体的な思考プロセスを共有します。

開発の進捗

Before: Wranglerのログイン状態という「外部状態」に依存し、環境構築の再現性が低かった。
Current: ローカル環境を「決定論的空間」と定義し、外部依存を完全に排除した自律型セットアップを確立。
Next: この思想を他のインフラ（R2, KV）にも適用し、完全なオフライン・デタッチド開発環境を実現する。

具体的なタスク

Before: 「認証エラー」を解決するために、トークン発行やログイン試行を繰り返していた（対症療法）。
Current: 問題を「ファイル状態管理」として再定義し、SQLiteの実体ファイルを制御するスクリプトを実装（根本治療）。
Next: AIエージェントが環境破損を検知した際、自律的にこのスクリプトを実行して復旧するフローを構築する。

物理モデル：なぜ .wrangler を消すのか

D1のローカル開発において、多くの人が見落としている物理的な事実があります。
それは、「D1ローカルはただのSQLiteファイルである」という点です。

状態不整合のメカニズム

Wranglerは .wrangler ディレクトリ内にSQLiteのファイルを作成し、そこにスキーマやデータを永続化します。
しかし、マイグレーションの失敗や、ブランチの切り替えによって、このファイルとコード（SQL）の間に乖離が生じます。

これが「DBは存在するがテーブルがない」「カラムが見つからない」という幽霊のようなエラーの正体です。

クラウドは共有資源だが、ローカルは決定論的空間だ

クラウド上のDBは、永続化されるべき「共有資源」であり、時間、他者の変更、権限、ネットワークといった不確定要素が混入する「可変世界」です。
対して、ローカル環境のDBは、コードからいつでも再生成可能な「使い捨てのインスタンス」であり、「決定論的空間」でなければなりません。

なぜローカルは決定論的たりえるのか。それは入力が有限だからです。

コード (Code): migrations/*.sql という静的なファイル群
コマンド (Command): npm run setup:db という単一のエントリポイント
順序 (Order): ファイル名に基づく決定論的な適用順序

これらの有限な入力だけで状態が一意に決まるため、ローカル環境はクラウドの模倣（ミニチュア）ではなく、「コードから導き出される唯一の真実」として扱えるのです。

実装：決定性を担保する `setup-db.sh`

この思想をコードに落とし込んだのが、以下のセットアップスクリプトです。
手順の自動化ではなく、「状態の強制」を目的としています。

1. 破壊による初期化

まず、不確定な状態（.wrangler）を物理的に削除します。これにより、過去の遺恨を断ち切り、ゼロからのスタートを保証します。

# 過去の状態（不確定要素）を物理削除
rm -rf .wrangler

2. 外部遮断の徹底

次に、--local フラグを強制することで、インターネットや認証という「外部状態」への依存を物理的に遮断します。

# 外部通信を遮断し、ローカル完結を強制
npx wrangler d1 execute DB --local --file="$file"

3. 順序の保証

マイグレーションファイルをファイル名の順序通りに適用することで、いつ、誰が実行しても同じ結果になる「再現性」を担保します。

# 決定論的な順序でスキーマを適用
for file in migrations/*.sql; do
  echo "Applying $file..."
  npx wrangler d1 execute DB --local --file="$file"
done

AI時代の役割再定義：3者モデル

なぜここまで「自律性」にこだわるのか。それはAIコーディング時代において、人間の役割が変化しているからです。

AIの役割: 状態を破壊するエージェント。AIは前提条件の安定性を信じ、ロジックを生成しますが、その過程で容易に環境を「汚し」「壊し」ます。
人間の役割: 状態を定義する設計者。人間は「あるべき状態」をコード（マイグレーションSQL）やスクリプト（setup-db.sh）として定義します。
システムの役割: 状態を再生成する実行者。npm run setup:db というコマンドは、人間が定義した「あるべき状態」を、何度でも機械的に再生成するシステムです。

この3者モデルにおいて、人間はもはや「環境を手で管理する」作業から解放されます。人間の仕事は、AIが壊してもシステムが即座に復旧できる、堅牢な「状態の設計図」を描くことに集約されるのです。

npm run setup:db

このコマンドは、単なるDB作成スクリプトではありません。
それは、AIによる破壊を許容し、システムによる自動復旧を可能にする、自己修復可能な開発基盤のトリガーなのです。

結論：環境は成果物である

「認証地獄」から抜ける方法は、認証をうまくやることではなく、認証という外部依存そのものをローカル開発から排除することです。

環境を「設定するもの（依存物）」から、コードから生成される「成果物」へと昇華させる。
このパラダイムシフトこそが、AIエージェントと共に走る開発現場に求められる、最も重要な「インフラ整備」です。

この思想はD1に限りません。これは、ソフトウェア工学における永遠のテーマ、「可変な世界をいかにして決定論的な空間に押し込めるか」という問いに対する、我々なりの一つの回答なのです。

このD1の設計思想の背景にある「Environment as Law」という概念はAI並列時代の環境設計で体系的に解説しています。また、この.wranglerの状態管理の問題はWindows環境でのE2Eテスト間欠的失敗としても表面化しました。キャッシュのロックという形で、テストを壊していた事例です。