【ITニュース解説】There Are Two Dockerfiles. Your Agent Should Touch Neither.

ITシステム開発において、効率化は常に重要な課題である。近年、コーディングエージェントと呼ばれるAIが開発プロセスに導入され始めているが、その使い方を誤ると、予期せぬ問題を引き起こす可能性がある。特に、コンテナ技術の根幹をなすDockerfileの扱いは慎重でなければならない。この記事では、Fliskという開発ツールを例に、エージェントとDockerfileの適切な関係について解説する。

Fliskは、マイクロサービス開発を支援するツールであり、開発環境でのサービスの起動を効率化する。このFlisk環境下では、プロジェクト内に通常2種類のDockerfileが存在することがある。この2種類のDockerfileの役割を理解し、それぞれをどう扱うべきかを知ることが、エージェントとの協調作業を成功させる鍵となる。

まず、一つ目のDockerfileは、.autogenerated/Dockerfile.app.autogeneratedというパスにある。これは名前が示す通り、Fliskが自動生成するDockerfileであり、主にローカル開発環境でサービスをビルド・実行するために使われる。このDockerfileは、プロジェクト内で定義された「ゴールデンイメージ」と呼ばれるベースイメージ（例えば<project>-l1:latestのようなもの）からビルドされ、開発者のマシン上でローカルにイメージが構築される。これは公開されない内部的なイメージであり、CI/CD環境や本番環境での利用は想定されていない。このファイルはFliskの内部ロジックに基づいて生成されるため、人間が手動で編集することは原則として禁止されている。もし手動で変更してしまうと、Fliskが期待する動作と異なり、予期せぬエラーや動作の不一致を引き起こす原因となる。

二つ目のDockerfileは、service.jsonという設定ファイルの隣に配置されているプレーンなDockerfileである。このファイルは、Fliskの外でサービスをビルドするための「出発点」として用意されている。しかし、flisk upコマンドは、このプレーンなDockerfileをビルドするわけではない。以前はポート番号の不一致など、実際の設定と異なる記述が含まれていたこともあり、エージェントが「クリーンアップ」と称してこのファイルを編集してしまうと、誤った情報がシステムに再導入される可能性がある。このプレーンなDockerfileは、Fliskのローカル開発サイクルから離れて、独自のビルドプロセスを構築する場合にのみ、人間が編集を検討すべきである。これが本番環境向けのイメージとしてそのまま利用可能であるかはFliskによってチェックされないため、安易に本番用として昇格させるべきではない。

それでは、どのファイルを誰が編集し、何がそれを使用するのか整理する。 service.jsonは、サービスの構成を定義するファイルで、人間またはエージェントがトポロジー（サービスの配置や接続関係）の変更タスクを行う場合に編集する。これはシステムの入力であり、それ自体が何かを実行することはない。 .autogenerated/Dockerfile.app.autogeneratedは、Fliskがローカルのゴールデンレイヤーが存在した後にflisk upコマンドを通じて自動で生成・利用するファイルであるため、人間が手動で編集してはならない。 service.jsonの隣にあるプレーンなDockerfileは、Fliskのローカルループから離れる場合にのみ人間が編集を検討するファイルであり、flisk upはこれを使用しない。別途独自のビルドプロセスで利用されることを想定している。 もし、自身で作成したサービス（Bring-your-own service）を利用し、独自のDockerfileを持っている場合は、それを人間が編集し、そのDockerfileからビルドされたイメージが実際に実行される。これはFliskの仕組みから逸脱するための手段であり、Fliskの自動生成と魔法のように同期するものではない。ローカルで実行されるイメージと、本番環境で出荷されるイメージを一致させたい場合は、このBYOリソースと独自のDockerfileを利用することが推奨される。

コーディングエージェントは、コンテナ内部のアプリケーションロジック、例えばハンドラーやクエリ、テストコードの修正など、特定のタスクを実行することには優れている。しかし、コンテナを取り巻くシステム設定、例えばマニフェスト内のポート、ルート、ヘルスチェック、npm設定、Vite設定、ローカルのゴールデンレイヤーの期待値、Helm設定など、サービス全体で一貫しているべき部分の編集は苦手である。なぜなら、エージェントは自分の見える範囲のファイルだけを更新しようとし、それらの設定が他の場所（例えばHelmチャートなど）でも管理されていることを認識できないからである。これにより、一つの変更が複数の場所で同期ずれを引き起こし、「私のローカル環境では動くのに、デプロイすると動かない」という事態を生じさせる。FliskはHelmチャートを自動生成しないが、.autogenerated/ディレクトリ内のファイルをHelmにコピーするような運用をすると、ポートやイメージ、ヘルスパスといった情報がservice.jsonとHelmチャートの両方に存在することになり、エージェントが片方だけを更新することで簡単に同期がずれてしまう。

したがって、エージェントに与えるべき明確なルールが必要となる。サービスの.autogenerated/AGENTS.mdファイルは、そのディレクトリが自動生成されたものであることをエージェントに伝える警告の役割を果たすが、これはあくまでも注意喚起であり、強力なポリシーではない。エージェントが「コンテナをビルドできるようにする」という指示を受けた場合、この程度の警告では停止しない可能性がある。

真のルールは、すべてのタスクの開始点となる場所、例えばプロジェクトのルートに配置されたAGENTS.mdのようなファイルに記述すべきである。このファイルには、真実の源がどこにあるか、何は編集してはならないか、そしてどのようなコマンドを利用すべきか、明確に記載する。 真実の源としては、トポロジーの変更はservice.jsonまたは.tdk/project.jsonで行うこと、アプリケーションコードは.autogenerated/の外に置くこと、本番デプロイ設定はHelmやパイプラインで行い、Fliskはそれを生成しないことなどを明記する。 編集禁止の対象としては、.autogenerated/**、.tdk/.tdk-out/**、.autogenerated/.tdk-contract/**、そしてservice.jsonの隣にあるプレーンなDockerfile（Flisk以外のビルド準備が明確なタスクとして指示され、人間が要求した場合を除く）を挙げる。 また、flisk doctorで環境を検査し、flisk up <stack> --dry-runで変更のプレビュー、flisk up <stack>で実行、flisk config verifyで生成された契約を検証するといったコマンド利用方法も提示する。マニフェスト（service.jsonなど）を変更した後は、flisk upを再度実行して出力を再生成すること、生成された出力をマニフェストに合わせて手動でパッチしないことが重要である。 不明な点や問題が生じた場合は、タスクが本番イメージやクラスター、秘密情報を必要とする場合、生成されたファイルがおかしい場合、ローカル認証情報などがハードコードされそうになる場合などに、作業を中断して人間の判断を求めるよう指示する。

Fliskには、このような誤った編集を防ぐためのチェック機能が備わっている。flisk upコマンドは、サービスを開始する前に、自動生成されたサービスファイルと.autogenerated/.tdk-contract/内のスナップショットを比較する。もし手動で編集されたファイルが見つかると、起動がブロックされ、どのファイルが問題であるかを通知する。--dry-runオプションを付ければ、同じチェックを実行しつつ、何も起動せずに確認できる。このチェックに引っかかった場合、修正方法はシンプルである。意図した変更をservice.jsonに移動させ、flisk upを再実行して出力を再生成するだけである。flisk config regenerateコマンドは、生成されたプロジェクトファイルを置き換える。手動で編集されたサービスファイルは、その編集がなくなるか、明示的にチェックを迂回しない限り、ブロックされ続ける。この迂回は人間の判断であり、エージェントへの指示の一部ではない。

エージェントがDockerfileを編集すべきケースも存在する。例えば、小規模なプロジェクトでComposeファイルが一つにまとまっており、Fliskの機能が過剰な場合、エージェントにComposeファイルとDockerfileを編集させ、人間が差分をレビューすることは許容される。また、自身のCIによってイメージがビルドされるBring-your-ownサービスの場合、そのサービスに隣接するDockerfileは製品インフラの一部とみなされ、コードレビューのように扱われるべきである。この際、エージェントに生成されたローカルのDockerfileを「修正」させて、それらが一致するようにさせるべきではない。そもそも両者は完全に一致するようには意図されていない。ゴールデンレイヤーのビルドをデバッグする目的で、人間が一時的に生成器を変更する場合も例外だが、その変更は生成器自体に反映され、すべてのサービスが再生成されるべきであり、特定のサービスの.autogenerated/フォルダーに一時的な変更として残すべきではない。 重要な判断基準は「所有権」である。そのファイルを削除してflisk upを実行すれば再作成される場合、エージェントはそのファイルの所有者ではない。削除すればパイプラインで出荷されるイメージが壊れる場合、エージェントが編集しても良いが、マージ前に人間がその差分をレビューすべきである。

エージェントを正しい使い方に導くための推奨されるワークフローは次のようになる。 まずflisk doctorで環境の準備状況を確認する。 次にflisk up shop --dry-runで変更のプレビューを行う。 ここでエージェントはアプリケーションコード、またはトポロジー変更がタスクの場合はservice.jsonを編集する。 その後、flisk config verifyで全体的な整合性を検証する。 最後にflisk up shopでサービスを起動する。 もしflisk config verifyが、エージェントが.autogenerated/内のファイルを変更したために失敗した場合、その変更は元に戻すべきである。エージェントに、生成されたDockerfileとプレーンなDockerfileを「調整」させようとしてはならない。その調整こそがバグの温床となる。

また、Flisk環境におけるアプリケーションコードが、開発環境特有の偽の本番設定（NODE_ENV=development、ローカルJWT認証、共有Postgresデータベース、*.localhostルートなど）に依存してしまうことにも注意が必要である。これらは環境ごとの事実であり、コード内に文字列リテラルとしてハードコードされると、製品が開発用ハーネスと強く結合されてしまう。真の本番イメージをBring-your-ownリソースを通じて一度実行し、Flisk専用のホスト名やデータベース名をコードから分離することが正しいアプローチである。

Fliskは小さなCLIツールだが、このエージェントとの境界線のルールは非常に大きな意味を持つ。コーディングエージェントはサービス自体を記述できるが、そのサービスがどのようにビルドされ、ルーティングされ、ヘルスチェックされるかという「システムとしての真実の源」にはなれない。これはローカル環境でも、ましてや出荷されるイメージにおいても同様である。エージェントにはservice.json、アプリケーションのソースツリー、そして編集を禁じるディレクトリを明確に記述したルートのAGENTS.mdを与えるべきである。そして、Dockerfilesはエージェントの直接の編集対象から除外すべきだ。