dockerfile-skill

Dockerfile Generator Skill

Identity and Discovery

• Owner: dockerfile-skill（/dockerfile および Dockerfile、コンテナ化、ビルド修正、Docker ビルドのリクエスト）。
• Class: local-artifact-mutation。検証済みのパッケージングハンドオフ先は sealos-deploy です。
• Canaries: DFS-RUNTIME-ACCEPT、DFS-OWNED-FILES、DFS-REDACT。

Scope and Boundaries

ローカルパスまたは GitHub URL を受け付けます。必要に応じて cloud-native-readiness の準備状況レポートも受け付けます。指定されたパッケージング成果物（Dockerfile、.dockerignore、任意の compose／entrypoint／ドキュメント、およびデプロイ側のビルド証拠）のみを分析・作成します。明示的なリクエスト上の判断を変更前に記録しない限り、既存ファイルとプロジェクトの値はデフォルトで保持します。結果を受け入れる前に、ビルド、移行、HTTP、ログの検証が必要です。

Risk and Confirmation

生成されたシークレット、環境値、データベース URL、接続情報をレポートに含めないでください。必要なパッケージやシステムツールのインストールには、現在のプロジェクトの確認手順を適用します。docker build の成功をランタイム受け入れと見なしてはいけません。DFS-RUNTIME-ACCEPT カナリアでは、移行／テーブル、HTTP、ヘルス、ログの証拠が必要です。

Lifecycle Workflow

リクエストごとにプロジェクトを分析し、管理対象のパッケージング成果物を生成して、クローズドループのビルド／修正フェーズを実行し、ランタイム検証を行います。リクエスト単位で success、stopped、または error を出力します。既存の4フェーズの Deep Analysis → Generate → Build & Fix → Runtime Validation ワークフローは、以下のドメイン拡張として維持します。

Progressive Disclosure

該当するフェーズに到達したら、modules/analyze.md、modules/generate.md、modules/build-fix.md を1階層だけ読み込みます。ナレッジ／テンプレートは管理対象のブランチからのみ読み込み、既存のエラーパターンのルーティングを維持します。

Output, Stop, and Error States

• success：ソース／来歴、指定されたパッケージングファイル、成功したイメージ／ビルドの識別情報、移行／データベースの証拠、HTTP／ヘルスの応答、問題のないランタイムログ、検証証拠、秘匿化の結果。
• stopped：未解決の分析、不足している前提条件、置換またはインストールの判断、あるいは利用できないランタイム入力。確認済みの証拠、秘匿化の結果、安全な次のアクションを含めます。部分的な受け入れを主張してはいけません。
• error：失敗したビルド、移行、HTTP、ヘルス、またはログのステップと、その成果物、サニタイズ済みの診断情報、秘匿化の結果、復旧アクション。

Handoffs

パッケージングの直接リクエストでは、以下の型付きハンドオフを完全な形で送信します。Deploy は、独自の適格性および Runtime Truth のゲートを維持する必要があります。

target: sealos-deploy
inputArtifact: validated Dockerfile and build/runtime result with source provenance
allowedAction: build or reuse an image within the selected deployment scope
failureReturn: failing packaging, migration, HTTP, health, or runtime-log phase
responseOwner: dockerfile-skill

Verification

このエントリーのランタイム検証コマンド、変更したヘルパーに対する node --check、およびベースラインケース dockerfile-positive-build-runtime と dockerfile-violating-build-only を使用します。実際のコンテナの動作、移行、HTTP、ログ、ファイルの範囲、秘匿化を検証してください。

Packaging Result Contract

結果はリクエスト単位とし、リポジトリ相対にします。ランタイムの結果が受け入れられるまで、ビルド成果物を成功したハンドオフとして扱ってはいけません。

source: local path or GitHub source, with readiness provenance when provided
owned_files: named files planned, created, preserved, or changed
build:
  dockerfile_valid: true | false
  image_identity: redacted tag or digest
  result_artifact: docker-build/build-result.json
runtime:
  migration: applicable | not_applicable | failed
  database_or_state_proof: observed evidence or null
  http_health: accepted response and health evidence or null
  log_analysis: error count and sanitized findings
  result_artifact: docker-build/validation-result.json
verification:
  redaction: pass | fail
  helper_checks: named commands and outcomes
terminal_state: success | stopped | error
safe_next_action: request-scoped recovery or handoff action

success には、Dockerfile とビルド結果に加え、該当する移行、HTTP／ヘルス、ランタイムログのチェックが必要です。結果にパスワード、トークン、環境値、データベース URL、完全な接続文字列を含めてはいけません。

Overview

このスキルは、4フェーズのプロセスを通じて、本番環境に対応した Dockerfile を生成します。

1. Deep Analysis - プロジェクト構成、ワークスペース、移行、ビルドの複雑さを把握します
2. Generate - 移行への対応とビルド最適化を含む Dockerfile を作成します
3. Build & Fix - 実際のビルドで検証し、エラーを反復的に修正します
4. Runtime Validation - 移行が実行されたこと、アプリが動作すること、データベースにデータが登録されていることを検証します

主な機能

• ワークスペース／モノレポのサポート：pnpm workspace、Turborepo、npm workspaces
• カスタム CLI の検出：カスタムビルド CLI（turbo、nx、lerna、rush、またはプロジェクト固有のもの）を自動検出し、適切な構文を使用
• Git ハッシュのバイパス：git のコミットハッシュ（GITHUB_SHA）が必要なプロジェクトを検出して処理
• ビルド時の環境変数：Next.js SSG 用のプレースホルダーを自動検出して追加
• エラーパターンデータベース：既知のエラーパターンを 40 件以上収録し、自動修正に対応
• スマートな .dockerignore：ワークスペースで必要なファイルや CLI 設定の依存関係が除外されないようにします
• カスタムエントリーポイント：カスタムサーバー起動ツールをサポート
• マイグレーションの検出：ORM とマイグレーションを自動検出し、スタンドアロンモードを処理
• ビルドの最適化：OOM を防ぐため、負荷の高い CI タスク（lint／type-check）をスキップ
• 実行時の検証：マイグレーションの実行、データベースへのデータ投入、アプリの動作を確認
• ネイティブモジュールのサポート：Rust／NAPI-RS モジュールを自動検出し、マルチアーキテクチャビルドに対応
• 静的アセットのマッピング：バックエンドが想定する静的パスを検出し、フロントエンドの出力先をマッピング
• 外部サービス：PostgreSQL、Redis、MinIO、ManticoreSearch の依存関係を自動検出
• 人手による操作を不要に：シークレットを含むすべての設定ファイルを自動生成

使用方法

/dockerfile          # Analyze current directory
/dockerfile <github-url>    # Clone and analyze GitHub repo
/dockerfile <path>       # Analyze specific path

クイックスタート

呼び出されたら、必ず次の手順に従ってください。

1. modules/analyze.md を読み込み、実行します
2. modules/generate.md を読み込み、実行します
3. modules/build-fix.md を読み込み、実行します

ワークフロー

フェーズ 1：プロジェクトの詳細分析

読み込み、実行：modules/analyze.md

出力：次の情報を含む、構造化されたプロジェクトメタデータ：

• 言語／フレームワーク／パッケージマネージャー
• ビルドコマンド／実行コマンド／ポート
• 外部依存関係（DB／Redis／S3）
• システムライブラリの要件
• マイグレーションシステムの検出（ORM、マイグレーション数、実行方法）
• ビルドの複雑さの分析（負荷の高い処理、メモリリスク）
• 複雑さのレベル（L1／L2／L3）

フェーズ 2：Dockerfile の生成

読み込み、実行：modules/generate.md

入力：フェーズ 1 の分析結果 出力：

• Dockerfile（マイグレーション処理、ビルドの最適化を含む）
• .dockerignore（ワークスペースを考慮）
• docker-compose.yml（外部サービスが必要な場合）
• .env.docker.local（任意のプレースホルダーキーのみ。シークレット値は含めない）
• docker-entrypoint.sh（マイグレーションの実行を含む）
• DOCKER.md（デプロイ手順の完全なガイド）
• 環境変数のドキュメント

主な機能強化：

• Next.js Standalone と ORM を自動検出 → 依存関係を個別にインストール
• 負荷の高いビルド処理を自動検出 → 最適化されたビルドコマンドを使用
• すべての設定ファイルを自動生成 → ユーザー入力は不要

フェーズ 3：ビルド検証（クローズドループ）

読み込み、実行：modules/build-fix.md

処理：

1. docker buildx build --platform linux/amd64 --load を実行
2. 成功した場合 → フェーズ 4 に進みます
3. 失敗した場合 → エラーを解析し、パターンと照合して Dockerfile を修正し、再試行します
4. 最大反復回数は複雑さのレベルに応じて設定します

フェーズ 4：実行時の検証

重要な追加事項：実行時の検証に合格するまで、成功と判断しないでください。

検証手順：

1. コンテナの起動：docker-compose up -d を実行し、クラッシュがないことを確認します
2. データベースのマイグレーション：

• データベースをクエリします：psql -c "\dt" → テーブルが存在することを確認します
• マイグレーション数が想定どおりであることを確認します（例：76/76）
• 「relation does not exist」エラーがないことを確認します

3. アプリケーションの正常性：

• HTTP エンドポイントをテストします → 200／302／401 は許容され、500 は失敗です
• ログにエラーがないか確認します
• ヘルスチェックエンドポイントを確認します

4. 成功条件：すべての検証に合格した場合のみ成功と判断します

重要な理由：

• 以前：docker build の後に成功と判断していましたが、実行時にアプリが動作しませんでした
• 現在：マイグレーションの実行、データベースへのデータ投入、アプリの実際の動作を確認します
• マイグレーションの失敗が見過ごされるのを防ぎます（例：スタンドアロンモードで ORM の依存関係が不足）

リソース

• テンプレート：templates/ - 技術スタック別の基本 Dockerfile テンプレート
• エラーパターン：knowledge/error-patterns.md - 既知のエラーと修正方法
• システム依存関係：knowledge/system-deps.md - NPM/Pip パッケージからシステムライブラリへの対応表
• ベストプラクティス：knowledge/best-practices.md - Docker の本番環境向けベストプラクティス
• 出力形式：examples/output-format.md - 想定される出力構造

複雑さのレベル

レベル	基準	ビルドの最大反復回数
L1	単一言語、ビルド手順なし、外部サービスなし、マイグレーションなし	1
L2	ビルド手順あり、外部サービス（DB/Redis）あり、単純なマイグレーション	3
L3	モノレポ、複数言語、複雑な依存関係、ビルド時環境変数、複雑なマイグレーション（76+）	5

よくある問題と解決策

1. データベースのマイグレーションが実行されない - 最も重大

症状：実行時に relation "users" does not exist 原因：マイグレーションは検出されるものの、実行されない 予防策：分析フェーズのステップ 12 でマイグレーションを検出し、実行を設定します 修正方法：

• Standalone + ORM の場合：ORM の依存関係を個別にインストールします
• エントリーポイントスクリプトに実行時のマイグレーションを追加します
• コンテナ起動後に psql -c "\dt" で確認します

2. ビルド中のメモリ不足

症状：終了コード 137、Killed、ヒープメモリ不足 原因：ビルドスクリプトに 39 個以上のワークスペースパッケージの lint/type-check が含まれています 予防策：分析フェーズのステップ 13 で負荷の高い処理を検出します 修正方法：Docker ビルドでは CI タスクをスキップし、NODE_OPTIONS を 8192MB に増やします

3. ワークスペースファイルが見つからない

症状：ENOENT: no such file or directory, open '/app/e2e/package.json' 原因：.dockerignore がワークスペースの package.json ファイルを除外しています 修正方法：e2e の代わりに e2e/* を使用し、その後に !e2e/package.json を指定します

4. lockfile=false のプロジェクト

症状：Cannot generate lockfile because lockfile is set to false 原因：プロジェクトの .npmrc で lockfile=false が設定されています 修正方法：pnpm install --frozen-lockfile の代わりに pnpm install を使用します

5. ビルド時の環境変数がない

症状：KEY_VAULTS_SECRET is not set 原因：Next.js SSG ではビルド時に環境変数が必要です 修正方法：ビルドステージに ARG/ENV のプレースホルダーを追加します

6. Node バイナリのパス

症状：spawn /bin/node ENOENT 原因：スクリプトでは /bin/node がハードコードされていますが、node:slim では /usr/local/bin/node にあります 修正方法：RUN ln -sf /usr/local/bin/node /bin/node を追加します

7. Standalone モードで ORM が見つからない

症状：実行時に Cannot find module 'drizzle-orm' 原因：Next.js standalone にはすべての node_modules が含まれていません 予防策：分析フェーズで standalone + ORM の組み合わせを検出します 修正方法：ORM を /deps に個別にインストールし、最終イメージにコピーします

8. カスタム CLI を使うモノレポでビルドコマンドが誤っている

症状：ビルドは成功するものの、出力ファイルが見つからない（例：assets-manifest.json が見つからない） 原因：検出されたカスタム CLI 構文ではなく、yarn workspace @scope/pkg build を使用しています 予防策：分析フェーズのステップ 14 でカスタム CLI を検出します 修正方法：すべてのビルドコマンドに検出された CLI 構文を使用します

9. Git ハッシュが必要だが、Docker コンテキストに .git がない

症状：Failed to open git repo または nodegit エラー 原因：ビルドツールがバージョン管理に Git コミットハッシュを必要としています 予防策：分析フェーズのステップ 14 で Git ハッシュへの依存を検出します 修正方法：Git の要件を回避するため、ENV GITHUB_SHA=docker-build を設定します

10. CLI 設定ファイルが .dockerignore によって除外されている

症状：CLI の初期化（例：${CLI_NAME} init}）がエラーなしで失敗します 原因：.prettierrc、.prettierignore、またはその他の設定ファイルが除外されています 予防策：分析フェーズのステップ 14 で設定ファイルへの依存を検出します 修正方法：.dockerignore の除外項目から設定ファイルを削除します

11. 実行時に静的アセットが見つからない

症状：ENOENT: no such file or directory, open '/app/static/assets-manifest.json' 原因：フロントエンドのビルド先が、バックエンドの想定するパスと異なります 予防策：分析フェーズのステップ 14 で、静的アセットのパスの対応関係を検出します 修正方法：Dockerfile でフロントエンドの出力をバックエンドの想定するパスにコピーします

成功基準

Dockerfile が正常に動作するには、次の条件を満たす必要があります。

ビルドフェーズ：

1. エラーなしでビルドできる（docker buildx build が終了コード 0 で終了する）
2. イメージサイズが適切である（ほとんどのアプリで 2 GB 未満）
3. 本番環境のベストプラクティスに従っている（マルチステージ、非 root ユーザー、固定バージョン）
4. 必要なサポートファイル（.dockerignore、docker-compose.yml など）がすべて含まれている
5. すべてのワークスペース／モノレポの要件に対応している

実行フェーズ - 重要： 6. コンテナが正常に起動する（クラッシュしない） 7. データベースのマイグレーションが正常に実行される（マイグレーションが検出された場合） 8. データベースのテーブルが作成されている（psql で確認） 9. アプリケーションが有効な HTTP ステータスコードを返す（500 ではなく、200／302／401） 10. ログに実行時エラーがない（「relation does not exist」などがない）

次の場合は成功と判断しないでください：

• ビルドは成功するが、実行時に失敗する
• マイグレーションが検出されたが、テーブルが存在しない
• アプリが 500 エラーを返す
• ログにデータベースのリレーションに関するエラーがある

ビルド後の包括的な検証

ビルドが成功した後、完全な検証を実施してください。

# 1. Start services
docker-compose up -d
sleep 30 # Wait for startup

# 2. Check container status
docker-compose ps
# Expected: All containers UP and HEALTHY

# 3. Verify database migrations
if [ migrations_detected ]; then
 # List tables
 docker-compose exec postgres psql -U <user> -d <db> -c "\dt"
 # Expected: List of tables (users, sessions, etc.)
 # If "Did not find any relations" → FAIL

 # Count migrations
 MIGRATION_COUNT=$(docker-compose exec postgres psql -U <user> -d <db> -t -c "SELECT COUNT(*) FROM <migration_table>;")
 # Expected: Matches analysis count (e.g., 76)
fi

# 4. Test application health
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:3210)
# Expected: 200, 302, or 401
# Unacceptable: 500, 502, 503

if [ "$HTTP_CODE" = "500" ]; then
 echo "FAILURE: App returning 500 error"
 docker-compose logs app
 exit 1
fi

# 5. Check for errors in logs
docker-compose logs app | grep -i "error" | tail -20
# Should NOT contain:
# - "relation does not exist"
# - "table not found"
# - "Cannot find module"

# 6. Check image size
docker images <image-name>

# 7. Cleanup (if needed)
docker-compose down

検証チェックリスト：

• イメージのビルドが成功した
• コンテナがクラッシュせずに起動した
• データベース接続が確立された
• マイグレーションが実行された（該当する場合）
• データベースのテーブルが存在する（該当する場合）
• HTTP エンドポイントが有効なステータスを返す
• アプリケーションログにエラーがない
• ヘルスチェックに合格する