devcontainers-best-practices

Devcontainer のベストプラクティス

このスキルは、Development Container エコシステムの適切なドキュメントやリファレンスを案内します。devcontainer.json の作業、Feature や Template の選択、またはユーザーが dev container、containers.dev、サポートツールについて質問した場合に使用してください。

クイックスタート

イメージと Feature を使用した最小限の devcontainer.json の例です："image": "mcr.microsoft.com/devcontainers/base:ubuntu"、"features": { "ghcr.io/devcontainers/features/git:1": {} }。プロパティの詳細と検証については、クイックリファレンスの項目 1 と references/schema.md を参照してください。

このスキルを使用する場面

• devcontainer.json の編集または検証
• プロパティの確認（構文、型、ツールのサポート状況）
• Feature または Template の選択や参照
• 仕様をサポートするツールや、ツール固有のプロパティ／制限事項の確認
• 仕様の理解（ライフサイクル、マージロジック、イメージメタデータ）
• Dev Container Feature の作成または公開（references/features.md の「作成」セクションと containers.dev の作成ガイドを参照）
• 複数の dev container の設定（マルチプロジェクト、共有 Compose）。references/tools.md と VS Code / マルチコンテナのドキュメントを参照してください。

公式ソース

このスキルとそのリファレンスのすべての内容は、以下のソースに基づいています。

• 仕様とリファレンス：containers.dev/implementors/spec、containers.dev/implementors/json_reference
• スキーマ：containers.dev/implementors/json_schema
• ガイド：containers.dev/guides（事前ビルド、Dockerfile／Compose の使用、Feature 作成のベストプラクティス、GitLab CI）
• サポートツール：devcontainers.github.io/supporting
• Feature：containers.dev/implementors/features、github.com/devcontainers/features
• Template：containers.dev/implementors/templates、github.com/devcontainers/templates

リファレンスファイル

詳細は references/ ディレクトリにあります。必要なものだけを読み込んでください。

必要な情報	ファイル
完全な仕様を参照する場面、主要な概念、マージロジック、ライフサイクル	references/spec.md
JSON リファレンスとスキーマの違い、正式な URL、検証方法	references/schema.md
サポートツール、ツール固有のプロパティ、制限事項	references/tools.md
VS Code のワークフロー、要件、事前ビルド、ポート、拡張機能、制限事項、dotfiles、コンテナの管理	references/vscode-containers.md
ヒントとコツ（OS、Git、パフォーマンス、トラブルシューティング、プロファイルの永続化、問題の報告）	references/tips-and-tricks.md
公式 Feature、OCI 参照、バージョン管理、オプション、インストール順序、Feature の作成	references/features.md
公式 Template、Template と Feature と Dockerfile の使い分け	references/templates.md

クイック検索

1. devcontainer.json のプロパティまたは動作
   プロパティごとの詳細については、Dev Container メタデータリファレンス（またはreferences/spec.md）をご覧ください。検証には、devcontainer.json スキーマまたは Dev Container CLI を使用してください。references/schema.mdをご覧ください。

2. ツールのサポートまたはツール固有の設定
   ツールの一覧、customizations.*（例：customizations.vscode、customizations.codespaces）、制限事項については、devcontainers.github.io/supportingをご確認ください。概要はreferences/tools.mdにあります。

3. 高度なシナリオ（環境変数、マウント、パフォーマンス、非 root ユーザー、リモート Docker、複数コンテナー、Git 認証情報）
   VS Code の高度なコンテナー構成をご覧ください。概要とワークフローへのリンクはreferences/vscode-containers.mdにあります。

4. 複数の開発コンテナー（複数プロジェクト、共有 Docker Compose）
   references/tools.mdの「複数コンテナー／複数プロジェクト」と、Chris Ayers – 複数の開発コンテナーをご覧ください。

5. OS 固有の情報またはトラブルシューティング（Git、Docker Desktop、クリーンアップ、ログ）
   VS Code Dev Containers のヒントとコツをご覧ください。概要はreferences/tips-and-tricks.mdにあります。

6. Feature ID、オプション、インストール順序
   公式 Features：containers.dev/features、github.com/devcontainers/features。OCI 参照：ghcr.io/devcontainers/features/<name>:<version>。詳細はreferences/features.mdにあります。Features の作成については、同ページの作成セクションとcontainers.dev/guide/feature-authoring-best-practicesをご覧ください。

7. テンプレート、または「テンプレートと Feature と Dockerfile の違い」
   公式 Templates：containers.dev/templates、github.com/devcontainers/templates。どれを使うべきかについては、references/templates.mdをご覧ください。

8. 仕様の概念（ライフサイクル、マージ、イメージのメタデータ）
   仕様全体：containers.dev/implementors/spec。概要：references/spec.md。

ベストプラクティス（公式ドキュメントより）

仕様または公式の devcontainer ドキュメントに記載されている推奨事項のみを適用してください。関連する場合は出典を引用してください。

• 環境変数：可能であれば、コンテナー内のすべてのプロセスから変数を参照でき、クライアント固有にならないよう、remoteEnv より containerEnv を優先してください。値が固定ではなく、再ビルドを避けたい場合は remoteEnv を使用してください。（Dev Container metadata reference – containerEnv/remoteEnv。）
• ポート転送：ほとんどの場合、appPort ではなく forwardPorts プロパティを使用してください。転送されたポートは、アプリケーションからは localhost のように動作します。公開ポートまたはネットワークからアクセス可能なポートが必要な場合は、appPort（または Docker Compose の ports）を使用してください。（VS Code – Forwarding or publishing a port、Dev Container metadata reference。）
• 可能な場合は事前ビルド：イメージを事前ビルドすると（例：Dev Container CLI または GitHub Actions を使用）、起動が速くなり、ツールのバージョンを固定できます。イメージのメタデータは継承できるため、リポジトリには最小限の devcontainer.json だけを用意すれば済みます。（VS Code – Pre-building dev container images、containers.dev/guides。）
• セキュリティと信頼性：Dev Container の設定とイメージは任意のコマンドを実行できます。信頼できるソースの設定とイメージのみを使用してください。サンドボックス化とセキュリティコンテキストについては、仕様とコミュニティの記事（例：出典を明記した The Red Guild – Where do you run your code）を参照してください。
• Feature のバージョン：特定のバージョンに固定するには、Feature ID の末尾にバージョンを追加してください（例：versions list）。省略した場合、:latest タグが暗黙的に適用されます。（Features – containers.dev。）
• 変更後に再ビルド：Dev Container の設定を変更した後は、ツールに変更を反映させるために再ビルドしてください（例：VS Code または Cursor などの互換エディターで、コマンドパレットから「Dev Containers: Rebuild Container」または「Codespaces: Rebuild Container」を実行します）。（VS Code Dev Containers extension、GitHub Codespaces。）
• ライフサイクルスクリプトの実行順序：作成スクリプトは次の順序で実行されます：onCreateCommand → updateContentCommand → postCreateCommand。いずれかが失敗すると、それ以降のスクリプトは実行されません。（Dev Container metadata reference – Lifecycle scripts。）

仕様または公式ドキュメントに推奨事項が記載されていない場合は、それをベストプラクティスとして提示しないでください。記載を省くか、出典を明示した提案として記述してください。

任意／コミュニティの指針： コミュニティの記事（例：Daytona – Ultimate guide to dev containers）では、イメージを軽量に保つ、依存関係をキャッシュする、複数サービスの構成に Docker Compose を使用するといったプラクティスが提案されています。出典を明記して使用し、公式ドキュメントと矛盾する場合は公式ドキュメントを優先してください。

概要

• devcontainer.json の編集、Features／Templates の選択、Features の作成、または dev container や containers.dev に関する質問への回答に、このスキルを使用してください。
• 上記の正規 URL と references/ 配下のリファレンスファイルを参照して、質問を解決してください。
• ベストプラクティス：containers.dev または devcontainers.github.io を引用し、そこに記載されている指針のみを含めてください。OS 固有の問題やトラブルシューティングについては、VS Code Dev Containers Tips and Tricks と references/tips-and-tricks.md を参照してください。