docker-local-dev

Docker によるローカル開発

委任

デフォルトではメインの会話内で作業します。委任すると利用量が増える可能性があるため、サブエージェントを使う前に、提案するエージェント数と作業範囲について明示的な承認を得てください。承認された範囲内であれば、その承認を再利用してください。承認済みのエージェント数や作業範囲を拡大する場合は、改めて確認してください。

ガードレール

• ローカル開発を前提に設計します。本番用イメージ、シークレット、デプロイ、証明書、実行時のトポロジーは分けて扱います。
• 質問やサービスの提案をする前に調査します。検出結果は根拠として扱い、決定権があるものとはみなしません。
• 既存の Docker ファイルと、無関係な作業ツリーの変更を保持します。スタックに重要な変更を加える場合は、意味が分かる差分を維持します。通常の設定変更はセットアップまたは修復の依頼に含まれますが、ボリュームの削除、破壊的なリセット、データ移行については、それらの影響を対象とする承認が必要です。
• プロジェクトで使用しているサービス、またはユーザーが明示的に要求したサービスのみを生成します。プロジェクトが SQLite、ホスト上のサービス、外部データベースを使用している場合、データベースは必須ではありません。
• フォアグラウンドでの直接実行と、サービスごとに懸念事項を1つに絞る方法を優先します。プロジェクトですでに必要とされている場合、または本番環境との同等性を検証する正当な理由がある場合に限り、Supervisor または PM2 を追加します。
• 安定したトップレベルの Compose name: と、役割に基づくサービス名を優先します。デフォルトでは container_name を設定しません。サービスのスケーリングを妨げ、プロジェクト間の衝突を招くためです。
• プロジェクトの制約、チームや本番環境との互換性、信頼できる発行元、サポートされるバージョン、アーキテクチャに基づいてイメージを選択します。すでにダウンロード済みのイメージは、同等の条件で選択する際の決め手としてのみ扱います。生成するファイルでは、可変の latest タグを避けます。
• ホストからアクセスする必要があるポートのみを公開します。ローカル専用ポートはデフォルトで 127.0.0.1 にバインドします。可能な場合は、データベース、キャッシュ、SMTP、PHP-FPM、内部 API を外部に公開しないでください。
• コミット対象のファイル、生成ドキュメント、コマンド出力、フロントエンドまたはプロキシコンテナにシークレットを含めないでください。設定が必要な場合は、Git の追跡対象外となるローカル env ファイルと、安全なサンプルを生成します。

ワークフロー

1. プロジェクトを調査する

プロジェクトのコマンドは、対象プロジェクトのディレクトリから実行します。同梱されているヘルパーは <skill-directory>/scripts/ から見つけてください。ヘルパーの場所とプロジェクトの作業ディレクトリは別です。構文を選ぶ前に、Docker と Compose の機能を確認します。

docker version
docker compose version

次の項目が存在する場合は調査します。

• compose.yaml、compose.yml、docker-compose*.yml、オーバーライドファイル
• Dockerfile*、.dockerignore、.devcontainer/、Makefile、パッケージスクリプト
• アプリケーションのマニフェスト、ロックファイル、ランタイムバージョンファイル、env のサンプル、モノレポ／ワークスペースのファイル
• 既存のローカルプロキシの慣例、Compose プロジェクト名、ネットワーク、ボリューム、ホストのポートマッピング
• 追跡対象ファイルを編集する前の Git ステータスとリポジトリの指示

有用な根拠が得られる場合は、スタック検出を使用します。対象が明確で範囲の狭い修復であれば、直接調査するだけで十分です。このスキルディレクトリからスクリプトを見つけます。

"<skill-directory>/scripts/detect-stack.sh" "<project-root>"

スクリプトは標準出力に JSON を、標準エラー出力に診断情報を出力します。不確かな検出結果は、シークレットの値を表示せずにソースファイルで確認します。

Docker が利用できる場合は、任意でローカルイメージとネットワークを調査します。

"<skill-directory>/scripts/detect-images.sh"
"<skill-directory>/scripts/detect-network.sh"

キャッシュされたイメージや検出されたネットワークによって、プロジェクトの互換性や分離要件が損なわれないようにしてください。

2. 設計を決める

次の内容を推定して要約します。

• 対象範囲のアプリ、開発コマンド、内部ポート、共有パッケージ、ライブリロードの要件
• 制約とロックファイルに基づくランタイムとパッケージマネージャーのバージョン
• 実際に使用されているデータベース、キャッシュ、キュー、スケジューラー、メール、デバッグ用サービス
• 既存のリバースプロキシ、明示的な .localhost ホスト名、同一オリジンの /api ルーティング、必要なホストへの公開
• バインドマウントと Compose Watch のどちらを使うか。Watch はインストール済みの Compose バージョンが対応している場合に限り使用します。
• 既存の Docker ファイルを統合するか、対象を絞って修復するか、置き換えるか

通常のセットアップ上の選択は、調査結果に基づいて決定します。不足情報によって対象アプリ、データ互換性、ネットワークへの公開範囲、または未依頼の重要な置き換えが変わる場合に限り、質問します。

3. 関連するリファレンスのみを読みます

必要な情報	読むファイル
検出ルールとモノレポの検出	references/tech-stack-detection.md
イメージ、プロセス、依存関係、マウント、環境、Dockerfile	references/service-configuration-guide.md
WordPress、Drupal、Joomla	references/cms-configuration-guide.md
ポート、プロキシ、ドメイン、ネットワーク、ホストアクセス	references/networking-ports-guide.md
既存の Compose または Dockerfile の変更	references/merge-backup-strategy.md
レディネスチェックとスモークテスト	references/health-check-patterns.md

アセットは出発点として使用し、変更不可の出力とはみなさないでください。選択しなかったサービスを削除し、検出したプロジェクトに合わせてプレースホルダー、ヘルスチェック、コマンド、パス、ユーザー、バージョンを調整します。

4. プレビューして生成する

既存のスタックに大幅な変更を加える場合は、変更内容（ファイル、サービスとバージョン、ホストポートとドメイン、マウント戦略）を作業の一環として明示します。

既存の許可範囲内で、必要最小限の一貫したセットアップを生成します。プロジェクトに応じて、開発用 Dockerfile またはビルドターゲット、.dockerignore、古いトップレベルの version を含まない compose.yaml、選択したプロキシまたはプロセスの設定、設定が必要な場合は env のサンプルと、Git の追跡対象から除外したローカル env ファイルを作成します。使用上の注意は、有用な場合または依頼された場合にのみ追加します。

以下を優先します。

• シンプルなアクティブ開発では、ソースをバインドマウントし、依存関係には名前付きボリュームを使用します。
• 大規模なツリー、ネイティブ依存関係、または細かな同期が有効なプロジェクトでは、sync、sync+restart、rebuild ルールを使った Compose Watch を使用します。
• ワンショットの依存関係インストーラーは、バインドマウントまたはモノレポの問題を実際に解決する場合にのみ使用し、正常終了が想定されることを明記します。
• アプリと同じイメージを使うワーカーサービスとスケジューラーサービスを分けます。
• 任意のデバッグツールや管理ツールには Compose プロファイルを使用します。
• 依存先に有効なヘルスチェックが定義されている場合にのみ、ヘルスチェックを条件とする依存関係を設定します。

マイグレーション、シード、CMS インストーラー、破壊的なクリーンアップ、データベースへの書き込みテストは、データへの影響が許可範囲に含まれている場合にのみ実行します。コンテナーの設定依頼だけでは、これらの操作は許可されたことになりません。

5. 検証する

まず静的チェックを実行します。

docker compose config --quiet
docker build --check .

インストール済みの Docker バージョンが対応している場合にのみ、docker build --check を使用します。依頼にローカルセットアップの実行または検証が含まれる場合は、ビルドして起動します。ファイル生成のみの依頼では、実行範囲をその限定された内容にとどめます。

docker compose build
docker compose up -d --wait
docker compose ps -a

--wait が使用できない場合は、デタッチモードで起動し、タイムアウトを設けて、宣言済みのヘルスチェックをポーリングします。失敗または再起動を繰り返しているサービスがないか、ログを確認します。

該当する場合は、同梱のチェックを実行します。

"<skill-directory>/scripts/health-check.sh"
"<skill-directory>/scripts/db-test.sh"          # connection/read-only query
"<skill-directory>/scripts/db-test.sh" --crud   # explicit temporary-table CRUD check

さらに、php artisan about、wp core version、drush status、python manage.py check、またはアプリケーションのヘルスエンドポイントなど、スタック固有のスモークチェックも実行します。ランタイム検証が対象範囲に含まれる場合は、無害な一時的変更を加えてホットリロードを確認し、その後元に戻します。関連する設定またはランタイム条件が変わらない限り、合格済みのチェックを再利用します。

6. 報告する

以下を報告します。

• 生成または変更したファイル
• 選択したサービス、バージョン、ローカル URL、明示的なホスト公開設定
• 検証に使用した正確なコマンドと結果
• 正常終了後に停止している想定のワンショットサービス
• 前提条件、省略したチェック、プラットフォーム固有の制限

報告にシークレットの値を含めないでください。

ホストポートレジストリ

ホストポートの継続的な追跡は任意です。まず、次を確認します。

PORT_REGISTRY_FILE="${DOCKER_LOCAL_DEV_PORT_REGISTRY:-${XDG_STATE_HOME:-$HOME/.local/state}/docker-local-dev/HOST_PORT_REGISTRY.md}"
test -f "$PORT_REGISTRY_FILE" && sed -n '1,220p' "$PORT_REGISTRY_FILE"

レジストリを作成または更新すると、現在のプロジェクト以外もスキャンされ、ローカルパスが記録されます。スキャンのルートと出力先について許可を得てください。すでに許可されている場合は、それを再利用します。その後、次を実行します。

node "<skill-directory>/scripts/scan-host-ports.mjs" --root "<approved-root>" --out "$PORT_REGISTRY_FILE" --yes

現在プロセスがリッスンしていなくても、登録済みポートは予約済みとして扱います。レジストリがない単一プロジェクトの場合は、稼働中のポートを確認すれば十分です。

受け入れ条件

• 生成された Compose 設定は、未解決のプレースホルダーがなく、解析できます。
• 選択したイメージとコマンドがプロジェクトの制約に一致し、未レビューの浮動タグが含まれていません。
• アプリコンテナは localhost ではなく、Compose のサービス名を使って依存先に接続します。
• オプションのサービスは含めないか、プロファイルで制御します。
• ホストポートは必要最小限で、競合がなく、より広いアクセスが求められない限りループバックにバインドします。
• ヘルスチェックでは、イメージ内で利用できるコマンドを実行し、プロセスの存在だけでなく準備状態を確認します。
• ソースの変更は意図したとおりに再読み込みされます。ロックファイルの変更には、文書化されたインストールまたは再ビルドの手順に従います。
• 生成されたファイルやレポートに、シークレット、本番データ、非公開ドメイン、許可されていない変更が含まれていません。