dockerfile-skill

Dockerfile Generator Skill

概要

このスキルは、4 段階のプロセスを通じて、本番環境ですぐに使える Dockerfile を生成します。

1. 詳細分析 - プロジェクト構造、ワークスペース、マイグレーション、ビルドの複雑さを把握します
2. 生成 - マイグレーション処理とビルドの最適化を含む Dockerfile を作成します
3. ビルドと修正 - 実際にビルドして検証し、エラーを反復的に修正します
4. 実行時の検証 - マイグレーションの実行、アプリの動作、データベースへのデータ投入を確認します

主な機能

• ワークスペース／モノレポのサポート：pnpm ワークスペース、Turborepo、npm ワークスペース
• カスタム CLI の検出：カスタムビルド CLI（turbo、nx、lerna、rush、またはプロジェクト固有のもの）を自動検出し、適切な構文を使用します
• Git ハッシュの回避：git のコミットハッシュ（GITHUB_SHA）が必要なプロジェクトを検出して対応します
• ビルド時の環境変数：Next.js SSG 用のプレースホルダーを自動検出して追加します
• エラーパターンデータベース：40 種類以上の既知のエラーパターンと自動修正機能
• スマートな .dockerignore：ワークスペースで必要なファイルや CLI 設定の依存ファイルが除外されないようにします
• カスタムエントリーポイント：カスタムサーバーランチャーをサポートします
• マイグレーションの検出：ORM とマイグレーションを自動検出し、スタンドアロンモードに対応します
• ビルドの最適化：OOM を防ぐため、負荷の大きい CI タスク（lint／型チェック）をスキップします
• 実行時の検証：マイグレーションの実行、データベースへのデータ投入、アプリの動作を確認します
• ネイティブモジュールのサポート：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 でマイグレーションを検出し、実行を設定します 修正方法：

• スタンドアロン + 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. スタンドアロンモードで ORM が見つからない

症状：ランタイムで Cannot find module 'drizzle-orm' 原因：Next.js のスタンドアロンモードでは、すべての node_modules が含まれるわけではありません 予防策：分析フェーズでスタンドアロン + 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 ハッシュへの依存を検出します 修正：ENV GITHUB_SHA=docker-build を設定して、Git の要件を回避します

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. イメージサイズが妥当である（ほとんどのアプリでは 2GB 未満）
3. 本番環境のベストプラクティスに従っている（マルチステージ、非 root ユーザー、バージョンの固定）
4. 必要な補助ファイル（.dockerignore、docker-compose.yml など）がすべて含まれている
5. すべてのワークスペース／モノレポの要件に対応している

実行フェーズ - 重要： 6. コンテナが正常に起動する（クラッシュしない） 7. データベースのマイグレーションが正常に実行される（マイグレーションが検出された場合） 8. データベースのテーブルが作成されている（psql で確認する） 9. アプリケーションが有効な HTTP ステータスコード（200／302／401）を返す（500 ではない） 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 エンドポイントが有効なステータスを返す
• アプリケーションログにエラーがない
• ヘルスチェックに合格する