set-zeabur-conventions

Zeabur デプロイ規範

プロジェクトのデプロイ先を Zeabur に設定するとき、最も陥りやすい落とし穴は、開発者が docker-compose.yml を使ってサービス一式を起動することに慣れており、「compose が動く＝本番環境でも動く」と当然のように考えてしまうことです。Zeabur では、この前提は誤りです。このスキルの役割は、この制約をプロジェクトの AGENTS.md に記載し、今後このプロジェクトで作業するすべてのエージェント（将来の自分を含む）が、最初からルールを把握できるようにすることです。

Zeabur へのデプロイが明確に指定されている場合にのみ使用してください。 このスキルは、「プロジェクトを Zeabur にデプロイする」とユーザーが明言した場合のみ扱います。Docker への言及、Dockerfile の作成、デプロイプラットフォームに関する一般的な話題だけでは、起動してはいけません。こうした手がかりから推測しないでください。ユーザーが本当に Zeabur を使うつもりなのか不明な場合は、まず確認してください。AGENTS.md を先に変更してはいけません。

重要な事実

Zeabur は PaaS プラットフォームで、デプロイの仕組みは次のとおりです。

• Dockerfile をサポート：Zeabur はプロジェクトのルートディレクトリにある Dockerfile を自動検出し、それを使ってビルドとデプロイを行います。
• docker-compose.yml はサポートされません：Zeabur は docker-compose.yml を読み込みません。複数サービスの本番環境でのオーケストレーションには、「Zeabur の複数サービスプロジェクト」を使うか、compose を Zeabur Template YAML に変換する必要があります（Zeabur には公式変換ツール zeabur/docker-compose-to-zeabur-template があります）。
• したがって、Zeabur 上で動作させる必要があるサービスはすべて、単一の Dockerfile（または Zeabur が自動検出するビルド方法）だけでデプロイを完了できなければなりません。

ただし、docker-compose.yml を削除する必要はありません。「ローカル開発とテスト」には引き続き役立ちます（app + DB + cache を一度に起動できて便利です）。これは許可されているだけでなく、推奨されています。重要なのは、その位置づけを明確にすることです。compose はローカル開発／テスト環境であり、本番デプロイの設定ではありません。

Zeabur MCP（Claude から Zeabur を直接操作）

Zeabur には公式 MCP サーバーがあり、インストールすると Claude から Zeabur 上のプロジェクト、サービス、環境変数、ログを直接読み取り／変更したり、コンテナ内でコマンドを実行したりできます。

インストール（ユーザースコープ。すべてのプロジェクトで共通の設定を使用）：

{
  "mcpServers": {
    "zeabur": {
      "command": "npx",
      "args": ["@zeabur/mcp-server"],
      "env": {
        "ZEABUR_TOKEN": "sk-xxxxxx"
      }
    }
  }
}

または CLI で一行追加します。

claude mcp add zeabur --scope user -e ZEABUR_TOKEN=sk-xxxxxx -- npx @zeabur/mcp-server

ZEABUR_TOKEN は Zeabur Dashboard → Account Settings → API Tokens から生成します。このトークンは Zeabur アカウントの操作権限と同等です。パスワードと同様に扱ってください。git に書き込んだり、公開された会話に貼り付けたり、README に記載したりしてはいけません。ユーザーのインストールを支援した後、トークンが現在の会話に露出している場合は、Dashboard で revoke して再発行するよう必ず促してください。

インストール後、ツールを読み込むには Claude Code を再起動するか、新しい session を開く必要があります。ツールは mcp__zeabur__* という名前で表示されます。

MCP が公開する主なツール：サービスの list/get/create、create-environment-variable / update-environment-variable / delete-environment-variable、add-domain、update-service-ports、deploy-from-specification、get-build-logs / get-runtime-logs / get-deployments、execute-command（prebuilt service コンテナ内でコマンドを実行）、file-dir-read / read-file / list-files（読み取り専用のファイル操作）。

既知の制限：

• 単純な「redeploy / restart service」ツールはありません。環境変数を変更した後は、Zeabur Dashboard で手動で Redeploy をクリックする必要があります。操作を支援する際は、「Dashboard で該当する N 個の service の Redeploy をクリックしてください」と明確に伝え、変更が自動で反映されると思い込まないでください。
• 「write-file」ツールはありません。コンテナ内でファイルを変更するには execute-command を使うしかありませんが、PREBUILT_V2 template では通常、設定ファイルが read-only bind mount として注入されるため（次のセクションを参照）、書き込めません。
• project-level shared variables の編集インターフェースは操作できません（ただし、ある service の update-environment-variable を介して間接的に shared variables を変更できます）。

環境変数の envsubst と redeploy の仕組み（最も陥りやすい落とし穴）

Zeabur の環境変数には、「env を変更すればすぐ反映される」という直感とは異なる、重要な動作が 4 つあります。ユーザーの Zeabur 操作を支援する際は、必ずこれらを念頭に置いてください。

1. env var を変更しても自動で redeploy されません

Dashboard または MCP から env var を更新しても、実行中のコンテナは自動的には再起動しません。新しい値を反映させるには、Zeabur Dashboard で該当する service の「Redeploy」を手動でクリックする必要があります。コンテナ内で kill 1 を実行しても効果はありません。再起動されるのは同じ pod で、同じ baked artifact が使われます。env は Kubernetes pod spec に由来します（実際には新しい env に更新されます）が、「ファイルの再レンダリングが必要なサービス」には効果がありません（2 を参照）。

2. envsubst はコンテナの起動時ではなく、deploy イベント時に実行されます

PREBUILT_V2 template（Supabase template の Kong service など）は、deploy 段階で env var を設定ファイルにレンダリングします（たとえば ${ANON_KEY} を /home/kong/kong.yml に書き込みます）。その後、レンダリング済みのファイルが read-only bind mount としてコンテナにマウントされます。つまり、次のとおりです。

• コンテナ内で sed -i / cat > を実行しても変更できません（ファイルが read-only です）。「Resource busy」または「Read-only file system」という症状が発生します。
• コンテナ内で kill 1 を実行して pod を再起動しても、新しい pod には同じレンダリング済みファイルがマウントされるため、内容はまったく変わりません。
• env var の変更後に設定ファイルを再レンダリングするには、Zeabur プラットフォーム層で Redeploy するしかありません。

3. project-shared variables は service をまたいで参照されますが、cascade redeploy は行われません

Zeabur の ${...} は project-level shared reference です。Service A に JWT_SECRET=xxx を設定すると、Service B の GOTRUE_JWT_SECRET=${JWT_SECRET} は A の xxx に解決されます。しかし、参照元 service の raw 値を変更した後は、その変数を参照するすべての service を、それぞれ個別に Redeploy する必要があります。Zeabur は自動で cascade しません。secret をまとめて一通り変更したら、影響を受ける service の一覧をユーザーに提示してください。

4. stale な shared variables が残ることがあります

ある project を削除し、別の project で同名の service を再作成すると、shared variable pool に古い service の ID 値が残ることがあります（たとえば POSTGRESQL_HOST が、存在しなくなった service ID を参照したままになることがあります）。症状を診断するには、service の runtime log に service-XXX (port Y) への接続が表示されているものの、X が新しい service の実際の ID と異なり、かつ Connection refused が発生しているか確認します。修正するには、その env var を ${STALE_HOST} から内部 hostname（たとえば postgresql、auth）の直接指定に変更するか、正しい service ID に明示的に update します。Zeabur の内部 DNS は「service 作成時の名前」を hostname として使い、service の rename では DNS は変わりません。shared var に依存するより、hostname を直接指定するほうが安定します。

このスキルが起動したときに行うこと

ステップ 1：プロジェクトルートの AGENTS.md を探す

現在の作業ディレクトリから上方向にたどってプロジェクトルートを探します（通常は .git、package.json、pyproject.toml などが目印です）。対象ファイルはそのルートディレクトリにある AGENTS.md です。存在しない場合は作成します。プロジェクトに AGENTS.md を参照する CLAUDE.md がない場合は、「Read AGENTS.md before doing any project work.」という一行の CLAUDE.md も作成します。

ステップ 2：Zeabur セクションがすでにあるか確認する

AGENTS.md を読み、## Zeabur 部署規範 という見出しのセクションがすでにあるか確認します。

• ない場合 → assets/agents-md-section.md の内容をすべてファイルの末尾に追加します（前に空行を 1 行入れます）。
• ある場合 → 内容を比較し、assets/agents-md-section.md と一致しなければ最新の内容に更新します。一致する場合は変更せず、すでに最新であることをユーザーに伝えます。

同じセクションを重複して挿入してはいけません。

ステップ 3：結果を報告する

実施した内容（追加／更新／既存）を簡潔に伝え、書き込んだ主要なルールを 1〜2 文で言い換えて、ユーザーの認識と一致していることを確認します。

書き込み後の継続的な対応

この規範が AGENTS.md に追加されたら、見た目だけの記述にせず、このプロジェクトでの以後の開発で実際に遵守します。

1. サービスや依存関係を追加するときは、まず「これだけで Zeabur 上で動作する Dockerfile があるか」と自問します。答えは必ず「はい」でなければなりません。compose でしか動かせず、対応する Dockerfile のデプロイ方法がないサービスがあれば、Zeabur 上で動作しないことを積極的に指摘します。
2. docker compose up をデプロイコマンドやデプロイ手順の主要な方法として扱ってはいけません。デプロイ手順では Dockerfile／Zeabur のサービス設定を中心に説明します。
3. compose と本番環境の設定を同等に保ちます。docker-compose.yml の環境変数、ポート、起動コマンドが Zeabur のサービス設定または Dockerfile に対応するようにし、両者の設定が乖離しないようにします。
4. 複数サービスの本番環境での構成を compose に頼ってはいけません。Zeabur の複数サービスプロジェクトを使うか、compose を Zeabur Template YAML に変換することを推奨します。
5. ユーザーから Zeabur 用の Dockerfile を明確に求められた場合は、compose なしで単独でビルドできることを確認して支援します。
6. 各 Dockerfile の冒頭に、そのサービスで Zeabur 上に設定が必要な環境変数をコメントとして記載します。Zeabur の環境変数は各サービスの UI で個別に設定するため、一覧がなければ必要な設定を知るにはソースコードを調べる必要があります。Dockerfile の作成や変更を支援する際は、このコメントを積極的に追加または更新します。コメントには以下を含めます。
   • 必須／任意の区別、用途の説明、一般的な値。
   • dev／prod の対応する値（たとえば、Supabase URL は環境ごとに異なる project を指します）。
   • Runtime と Build-time の明確な区別：
     • バックエンド／常駐プロセスは runtime env（Zeabur Variables。再起動で反映されます）。
     • Vite などの静的ビルドツールは build-time arg（Zeabur Build-time Variables／Build Args。値を変更した後は再ビルドが必要です）。Dockerfile では対応する ARG を宣言し、ENV に変換してビルド環境変数として設定します。
   • セキュリティ境界に関する警告：Vite の VITE_* など、フロントエンドの bundle に含まれる変数はすべて公開されます。service_role key、バックエンド API token などの機密値を絶対に設定してはいけません。 環境変数を追加／削除したときは、実際に読み込む変数との食い違いを防ぐため、コメントも合わせて変更します。ユーザーがこのコメントのない Dockerfile を使っている場合は、追加を積極的に提案します。
7. Zeabur の runtime env var を変更した後は、Dashboard で該当サービスの Redeploy を実行するよう、ユーザーにはっきり伝えます（Zeabur はコンテナを自動で再起動しません）。project-shared 変数を変更した場合は、その変数を参照するすべてのサービスで個別に Redeploy が必要です。ひとつの Redeploy で連鎖的に反映されると想定せず、対象サービスの一覧をユーザーに示します。PREBUILT_V2 template（Supabase Kong など、envsubst で設定ファイルをレンダリングするサービス）では、ファイルの再生成には必ず Redeploy が必要であることを強調します。kill 1 では再生成されません。詳しくは、上記の「環境變數的 envsubst 與 redeploy 機制」を参照してください。

例外的な状況

• プロジェクトに別のデプロイ用セクションがすでにある場合：上書きせず、独立した ## Zeabur 部署規範 セクションを追加します。
• ユーザーがローカル開発に compose を使っているだけで、まだデプロイする予定がない場合：規範を追加してかまいませんが、報告時に「compose はローカルでの使用に問題ありません。この規範は、今後 Zeabur にデプロイする際のものです」と説明し、ユーザーが今すぐ compose の使用をやめる必要があると誤解させないようにします。
• monorepo／デプロイ可能なサービスが複数ある場合：規範は同様に適用されます。重要なのは「Zeabur にデプロイする各サービスに、それぞれ独立してビルド可能な Dockerfile が必要であること」です。報告時にこの点を指摘できます。