本記事について
当サイトを閲覧いただきありがとうございます。 本記事はシリーズ『生成AI時代のアーキテクチャ超入門』の「開発運用アーキテクチャ」カテゴリ第4弾として、開発環境とローカル実行について解説する記事です。
新人が入社してから初コミットまでの時間はチームの成熟度を測る最も正直な指標です。本記事ではdevcontainer／docker-compose／シークレット配布／IDE設定を「初コミットまで半日」を到達可能にする実務設計として扱います。「俺のマシンでは動く」と誰かが言い出した時点で、その仕組みは設計されていません。
本記事のテーマについてさらに詳しく知りたい方は『実践Claude Code入門』・『Claude CodeによるAI駆動開発入門』も参考にしてみてください。
この記事の結論
- docker-composeで「1コマンドで動く」ベースラインを作る
- devcontainerで設定を共有する
- シークレットは配らない運用にし、初コミットまで半日を目標にする
この記事を読む前に
本記事は開発・テスト・リリース・監視といった、サービスを作って動かし続ける工程の話が中心です。IT用語にあまり馴染みがない方は、基礎編の「開発から運用までの流れ」を先に読んでおくと格段に分かりやすくなると思います。また、読んでいて分からない用語が出てきたときは用語集で調べながら読み進められます。
そもそも開発環境とは何か
新居への引っ越しを想像してください。家具・家電・Wi-Fi・ガスの開栓──住み始められるまでのセットアップに1週間かかるか、即日で済むかは事前にどこまで準備されているかで決まります。
開発環境とは、エンジニアがコードを書き始めるために必要なソフトウェア・設定・接続情報・テストデータなど一式の作業場です。この作業場を誰でも短時間で再現できるように整備するのが「開発環境設計」です。
もし開発環境設計がなければ、新人が入社してから初めてのコードを書くまでに数日〜1週間かかる状態になります。さらにメンバー間で環境が微妙に異なり、「自分のPCでは動くのに」が日常化します。
なぜ開発環境設計が必要か
第一に、新人の立ち上がり速度がチームの成熟度を測るからです。初コミットまで1週間かかるチームと半日で済むチームでは、採用効果もチームの拡張性も段違いです。手順が属人化していると、教える側の生産性も犠牲になります。
第二に、環境差異がバグの温床になるからです。「自分のPCでは動くのに本番で落ちる」問題の大半は開発環境と本番環境の差異が原因で、統一する仕組みがなければ環境依存のバグを永遠に追い続けることになります。
第三に、リモートワーク時代の前提です。オフィスの隣の席で口頭サポートできた時代は終わり、どこからでも同じ環境を即座に再現できることが前提条件になりました。
開発環境の4世代
開発環境の歴史は「環境差を吸収する」ことへの連続した改善です。
| 世代 | 方式 | 代表 |
|---|---|---|
| 第1世代 | 各自の PC に直接インストール | brew install / apt install を手順書で配布 |
| 第2世代 | VM で共通化 | Vagrant + VirtualBox |
| 第3世代 | コンテナで共通化 | Docker Compose（現時点の主流） |
| 第4世代 | 宣言的な開発環境 | devcontainer / Nix / GitHub Codespaces |
現時点でdocker-composeは既にベースラインで、devcontainerのような「宣言的環境」が上に積まれる構成が増えています。手順書配布の第1世代に戻る理由はなく、VMは起動の遅さとリソース消費で選ぶ意味がほぼ消えました。
docker-compose — ベースライン
docker-composeは、複数のコンテナ（アプリ・DB・キャッシュ・キュー）を1つのYAMLで定義し一斉に起動するツールです。現時点でもローカル開発の骨格としての地位は揺らいでいません。
# compose.yaml の例
services:
app:
build: .
ports: ["3000:3000"]
depends_on: [db, redis]
db:
image: postgres:16
volumes: [pgdata:/var/lib/postgresql/data]
redis:
image: redis:7
volumes:
pgdata:docker compose up の1コマンドで環境一式が起動し、CIのIntegration Testでも同じ定義を使えます。弱点はホストOS依存が残ること（特にWindowsのファイルI/Oが遅い、MacのARM / x86イメージ差）ですが、それを補って余りあるのが本番と同じPostgreSQLバージョンをローカルで使える価値です。SQLiteで開発してPostgreSQLで本番、という構成は地雷で、方言差のバグが本番でしか発覚しません。
devcontainer — 宣言的な開発環境
devcontainer（コンテナで包んだ開発環境をVS Code／GitHub Codespaces／JetBrainsが自動で展開する仕組み）は、エディタ設定・拡張機能・シェル設定まで含めて共有できる第4世代のやり方です。
// .devcontainer/devcontainer.json
{
"image": "mcr.microsoft.com/devcontainers/typescript-node:20",
"features": {
"ghcr.io/devcontainers/features/docker-in-docker:2": {}
},
"postCreateCommand": "npm install",
"customizations": {
"vscode": {
"extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"]
}
}
}ここで指定したVS Code拡張が自動でインストールされ、postCreateCommand で依存解決まで完了します。新人は「リポジトリをclone → Dev Containersを開く」の2ステップで、同じバージョンのNode.js・同じLint設定が整った環境に辿り着きます。devcontainer.jsonをコミットすれば、Macの新人もWindowsの新人も同じ環境になります。
さらにGitHub Codespacesは、devcontainer定義をベースにクラウド上にフル開発環境を立てるサービスで、ローカルPCにはブラウザだけあれば開発できる世界を実現します。PC配布・社内VPN接続・セットアップ時間がすべて省略でき、低スペックPCでもマシンパワーをクラウドに逃がせて、業務委託・外部パートナーに社内環境を配らず開発参加してもらえます。利用時間課金で1日2時間×20日＝月約15〜30ドル程度──新人1人が2週間のセットアップから解放されるだけで投資回収します。
なお、さらに一段先の宣言性を求めるNix（全依存をハッシュで固定する究極の宣言的環境）もありますが、学習コストが急峻で9割のチームには早すぎる選択です。docker-compose + devcontainerで到達できない再現性が必要な場合のみ検討するのが無難です。
環境構築で何を自動化するか — 段階別の実務
環境構築は「READMEに書いてある手順を全部bash化する」ではなく、人の介在タイミングで段階を切って考えるのが実用的です。
| 段階 | 何をやるか | 目標時間 |
|---|---|---|
| ①リポジトリ取得 | git clone | 1分以内 |
| ②依存解決 | npm install／bundle install 等 | 3分以内 |
| ③シークレット取得 | .env の雛形コピー + Vault からキー取得 | 5分以内 |
| ④DB初期化 | スキーマ作成 + seedデータ投入 | 5分以内 |
| ⑤初回起動 | npm run dev で localhost にアクセス | 1分以内 |
| 合計 | clone から localhost まで | 15分以内 |
合計15分以内が本命の目標です。ここを超えるチームは、「どこで時間が溶けているか」を計測していないのが典型です。新人1人に実測させ、ボトルネックから潰していくのが現場で効きます。make setup 1発で②〜④が終わる状態を作るのがゴールです。
シークレット管理と本番データの扱い
APIキー・DB接続文字列を開発者のPCに配るのは既に古い運用です。Slackで .env を送りつける・Google Driveに置くのは即廃止の対象。主役はAWS Secrets Manager / Parameter Store（AWS環境の本命）とDoppler / Infisical（.env を中央管理しCLIでローカルに展開、小〜中規模でも現実的）。理想は開発者にシークレットを配らない運用で、開発者は自分のIAMロールで一時トークンを取得し、本番キーには一切触りません。詳細は秘密情報管理の記事も参照してください。
本番データも同様です。「本番のデータで動作確認したい」という要求は必ず出ますが、本番DBダンプをそのまま配るのは禁じ手です。本命は氏名・住所・カード番号をダミーに置換したマスク済みダンプの自動生成（pg_dump + マスキングSQL + 日次スケジュール）、PIIを完全回避するならFaker等の合成データです。個人情報保護法・GDPR等で本番データの持ち出しが違法になるケースもあるため、「個人情報を開発者のPCに載せない」という線引きが最初の設計判断になります。
IDE設定の共有
開発体験の均質化にはIDE設定の共有が効きます。共有すべきはformatterの設定（保存時整形）・推奨拡張機能（.vscode/extensions.json）・デバッグ構成（launch.json）・ワークスペース固有のLint例外。逆に個人のキーバインド・テーマ・フォントは共有しません。
.vscode/extensions.json の recommendations に拡張を列挙するだけで、リポジトリを開いた瞬間にVS Codeが「この拡張を入れますか？」とプロンプトします。新人のセットアップ工数を地味に削る、入れるだけで恩恵しかない低コスト施策です。
3つのシナリオで考える
個人開発・スタートアップの場合
docker-composeと .env.example、READMEの最小構成で十分だと思います。本番と同じバージョンのDBをcomposeで立てて、.env.example から .env を生成するスクリプトを用意しておく。たったこれだけのことで、「俺のマシンでは動く」問題の大半が消えてしまいます。
中小SaaS企業の場合
docker-composeにdevcontainer、Doppler（またはSecrets Manager）、マスク済みダンプの日次配布まで揃えるのが鉄板です。make setup 1発でclone後15分以内にlocalhostが立ち上がる状態を維持して、新人の初コミット半日を目標に実際に計測してみてください。
大企業の場合
GitHub Codespacesのようなクラウド開発環境が本命になります。PC配布やVPN設定を省略できますし、業務委託の方にも社内環境を配らずに済むのが大きいです。機密性の極めて高いコードは社内ポリシーとの相談になりますが、規制業種でも「ソースを端末に残さない」という方向で、むしろクラウド環境が好まれるケースが増えていると感じています。
AI判断軸 ― 宣言的環境がAIの前提になる
devcontainerがAIコーディングの再現性を保証する
devcontainerで開発環境を定義しておくと、AIが生成したコードが「自分の環境では動くが他の人の環境では動かない」問題を排除できます。Node.jsのバージョン・データベースの設定・OS依存のライブラリがすべてコンテナ内で統一されるため、AI生成コードのテスト結果も環境間で一致します。CodespacesやGitpodでも同じdevcontainer定義が使えるため、再現性がローカル・クラウドどちらでも保証されます。
環境構築手順の自動化がAIによるオンボーディング支援を可能にする
開発環境のセットアップが docker-compose up 一発で完了する状態であれば、新しいメンバーのオンボーディングもAIが支援できます。「このリポジトリをcloneして開発環境を立ち上げるまでの手順を教えて」と聞かれた時に、READMEとdevcontainer定義を読めばAIが正確に回答できるからです。逆に、手動インストール手順が10ステップ以上ある環境では、AIも正確な案内ができず、結局人間が横についてサポートする必要があります。
やってはいけないこと
ローカルで動いたのに本番で落ちる、という事故の99%は本番と微妙に違う環境が原因です。特に危険な6つに絞ります。
| 禁じ手 | なぜダメか → どうするか |
|---|---|
| ローカルだけSQLite、本番はPostgreSQL | SQL方言差でクエリが通らない → コンテナで本番と同じミドルウェアを使う |
| 言語ランタイムのバージョンずれ | 依存ライブラリの非互換で落ちる → devcontainer / .tool-versions で固定する |
| タイムゾーン混在（Asia/Tokyo と UTC） | 日付境界のバグが本番でしか発覚しない → CI含めUTCに統一する |
.env を各自が手で書く | キー名のtypoで検知困難な挙動になる → .env.example から生成を自動化する |
| 「READMEが充実していればOK」と信じ込む | READMEは必ず古くなる → 実行可能なコード（compose / devcontainer）を真実にする |
| 本番DBダンプをそのまま配布 | PII漏洩リスクが制御不能・法令違反の恐れ → マスク済みか合成データの二択 |
筆者メモ — 初コミットまで2週間の中規模SaaS
ある中規模SaaS企業で、新規参画したエンジニアが初コミットまで2週間かかる状態にあった事例が業界で広く知られています。原因は、環境構築手順が口伝で共有されていたこと、DBダンプを持っている人を毎回探し回らなければならなかったこと、必要な社内認証ツールのインストール手順がConfluenceの複数ページに散在していたこと──一つずつは小さい摩擦でも、積み重なって2週間になる典型です。
このチームはdevcontainer + 社内Vaultからのキー取得自動化 + マスク済みDBダンプの日次配布を整備し、初コミットまでの時間を半日まで短縮しました。その後のオンボーディング工数が毎回激減し、新人の離職率まで改善した──と報告されています。環境構築の摩擦は、採用した人材の立ち上がり速度に直接効く投資です。
決めるべきこと — 自分のプロジェクトでの答えは？
以下の項目について、自分のプロジェクトの答えを1〜2文で言語化してみてください。曖昧なまま着手すると、必ず後から「なぜそう決めたんだっけ」が問われます。
- ベースライン環境（docker-compose / VM / 実機）
- 宣言的環境の採用（devcontainer / Nix / なし）
- クラウド環境の採用（Codespaces / Gitpod / なし）
- 初コミット目標時間（半日 / 1日 / 1週間）
- シークレット配布方法（Vault / Secrets Manager / Doppler）
- 本番データの扱い（マスク済み / 合成データ）
- タイムゾーン統一方針（UTC固定推奨）
- IDE設定共有（
.vscode/settings.jsonコミット）
この記事に関連する記事
まとめ
本記事は開発環境とローカル実行について、docker-compose・devcontainer・Codespaces・シークレット配布・本番データ扱い・IDE設定共有まで含めて解説しました。如何だったでしょうか。
docker-composeでベースライン、devcontainerで設定共有、シークレットは配らない運用に、初コミット目標を半日に設定する。これが2026年の開発環境設計の現実解です。
次回はコードレビュー（PR運用・CODEOWNERS・マージキュー）について解説します。
シリーズ目次に戻る → 『生成AI時代のアーキテクチャ超入門』の歩き方
本記事で扱った内容の詳細は Visual Studio Code も合わせて参考にしてください。
それでは次の記事も閲覧いただけると幸いです。
📚 シリーズ：生成AI時代のアーキテクチャ超入門（63/95）