本記事について
当サイトを閲覧いただきありがとうございます。 本記事はシリーズ『生成AI時代のアーキテクチャ超入門』の「開発運用アーキテクチャ」カテゴリ第4弾として、開発環境とローカル実行について解説する記事です。
新人が入社してから初コミットまでの時間はチームの成熟度を測る最も正直な指標。本記事では devcontainer／docker-compose／シークレット配布／IDE設定を「初コミットまで半日」を到達可能にする実務設計として扱います。「俺のマシンでは動く」と誰かが言い出した時点で、その仕組みは設計されていません。
このカテゴリの他の記事
開発環境の4世代
開発環境の歴史は「環境差を吸収する」ことへの連続した改善です。世代ごとに、誰が・どこに・どれくらいの手間で環境を用意するかが変わってきました。
flowchart LR
G1["第1世代<br/>各自インストール<br/>(手順書配布)"]
G2["第2世代<br/>VM共通化<br/>Vagrant+VirtualBox"]
G3["第3世代<br/>コンテナ共通化<br/>docker-compose"]
G4["第4世代<br/>宣言的環境<br/>devcontainer/Nix/Codespaces"]
G1 -->|起動が遅い<br/>リソース消費大| G2
G2 -->|軽量化| G3
G3 -->|完全宣言化<br/>クラウド対応| G4
G3 -.|現時点の<br/>ベースライン|.- BASE[本命]
G4 -.|2025年以降<br/>標準化進行|.- FUTURE[次世代]
classDef old fill:#fee2e2,stroke:#dc2626;
classDef now fill:#dcfce7,stroke:#16a34a,stroke-width:2px;
classDef next fill:#dbeafe,stroke:#2563eb;
class G1,G2 old;
class G3,BASE now;
class G4,FUTURE next;| 世代 | 方式 | 代表 |
|---|---|---|
| 第1世代 | 各自の PC に直接インストール | brew install / apt install を手順書で配布 |
| 第2世代 | VM で共通化 | Vagrant + VirtualBox |
| 第3世代 | コンテナで共通化 | Docker Compose（現時点の主流） |
| 第4世代 | 宣言的な開発環境 | devcontainer / Nix / Gitpod / GitHub Codespaces |
現時点で、docker-compose は既にベースラインで、devcontainer や Nix のような「宣言的環境」が上に積まれる構成が増えています。手順書配布の第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:| メリット | デメリット |
|---|---|
1コマンドで環境一式起動（docker compose up） | ホスト OS 依存（特に Windows のファイル I/O が遅い） |
| 本番と同じミドルウェアをローカルで使える | Mac では ARM／x86 のイメージ差で嵌まることがある |
| 学習コストが低い | 複数サービスで構成管理が膨らむ |
| CI の Integration Test でも同じ定義を使える | 環境ごとの上書きが override.yml で散らかる |
本番と同じPostgreSQLバージョンをローカルで使える価値は圧倒的です。SQLite で開発して PostgreSQL で本番、という構成は地雷で、方言差のバグが本番でしか発覚しません。
devcontainer — 宣言的な開発環境
devcontainer（Dev Containers＝コンテナで包んだ開発環境を 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 の新人も同じ環境になります。
devcontainer + Codespaces — ゼロインストールの世界
GitHub Codespaces は、devcontainer 定義をベースにクラウド上にフル開発環境を立てるサービスで、ローカル PC にはブラウザだけあれば開発できる世界を実現します。新人のオンボーディングにおいては、PC 配布・社内 VPN 接続・セットアップ時間がすべて省略できる破壊力があります。
| ケース | 向き |
|---|---|
| 新人のオンボーディング高速化 | 本命（PC 準備不要） |
| 低スペック PC（モバイル端末・Chromebook） | マシンパワーをクラウドに逃がせる |
| 業務委託・外部パートナー | 社内環境を配らずに開発参加できる |
| オフライン・飛行機での開発 | ネット必須のため不向き |
| 機密性が極めて高いコード | 社内ポリシー次第 |
Codespaces は利用時間課金で、1日2時間×20日＝月約15〜30ドル程度。人件費から見れば誤差で、新人1人が2週間のセットアップから解放されるだけで投資回収します。JetBrains Gateway・Gitpod なども同系の選択肢で、現時点では「リモート開発環境」はもう少数派の選択ではなくなっています。
Nix — もう一段先の宣言性
Nix（正確には Nix package manager と NixOS の生態系）は、開発環境の全依存をハッシュで固定する究極の宣言的環境です。Node.js のバージョンも、PostgreSQL のバージョンも、シェル設定も、全て純関数的に固定されるため「俺のマシンでは動く」問題が原理的に消えます。
| Nixが強い場面 | Nixが辛い場面 |
|---|---|
| 環境の再現性を極限まで高めたい | 学習コストが急峻（関数型言語 Nix lang） |
| OSS・研究プロジェクトで多環境対応 | チーム全員の習熟が必要 |
| 長期メンテの依存ロック | トラブルシュートが難しい |
現時点では、Nix は刺さるチームにしか刺さらない道具で、9割のチームには早すぎる選択です。docker-compose + devcontainer で到達できない再現性が必要な場合のみ検討するのが無難。筆者も一時期 Nix に惚れて社内導入を試みたことがありますが、「チームの学習コストを過小評価」して3か月で撤退した事例をいくつも知っています。
環境構築で何を自動化するか — 段階別の実務
環境構築は「README に書いてある手順を全部 bash 化する」ではなく、人の介在タイミングで段階を切って考えるのが実用的です。各段階で目標時間を設定し、超えるものは自動化の検討対象にします。
| 段階 | 何をやるか | 目標時間 |
|---|---|---|
| ①リポジトリ取得 | git clone | 1分以内 |
| ②依存解決 | npm install／bundle install／pip install | 3分以内 |
| ③シークレット取得 | .env の雛形コピー + 社内 Vault からキー取得 | 5分以内 |
| ④DB初期化 | スキーマ作成 + seedデータ投入 | 5分以内 |
| ⑤初回起動 | npm run dev で localhost にアクセス | 1分以内 |
| 合計 | clone から localhost まで | 15分以内 |
合計15分以内が本命の目標です。ここを超えるチームは、「どこで時間が溶けているか」を計測していないのが典型です。新人1人に time コマンドで実測させ、ボトルネックから潰していくのが現場で効きます。make setup 1発で②〜④が終わる状態を作るのがゴールです。
ローカル実行の鬼門 — 本番と微妙に違う環境
ローカルで動いたのに本番で落ちる、という事故の99%は本番と微妙に違う環境が原因です。以下の禁じ手は、数時間〜数日の本番障害に直結します。
| 禁じ手 | なぜダメか |
|---|---|
| ローカルだけ SQLite、本番は PostgreSQL | SQL 方言差でクエリが通らない |
| ローカルと本番で Python のマイナーバージョンがズレる | 依存ライブラリの非互換で落ちる |
| ローカルだけ日本語ロケール、本番は UTC | 日付・ソート順・正規表現で事故 |
タイムゾーンが Asia/Tokyo 混在 | 日付境界で1日ズレるバグが頻発 |
.env を各自が手で書く | キー名の typo で検知困難な挙動になる |
対策はコンテナで本番と同じミドルウェアを使う、タイムゾーンはUTCに統一、.env は .env.example から生成を自動化、の3点。とくにタイムゾーン混在は、境界時刻（0:00付近）のバグがステージングでは再現せず本番で発覚する地雷で、CI でも UTC 固定が鉄則です。
タイムゾーン混在は隠れた爆弾。UTC で揃えるのが現代の基本です。
シークレット管理の実務
API キー・DB 接続文字列・認証トークンを開発者のPCに配るのは、現時点では既に古い運用です。Slack で .env を送りつける・Google Drive に置く・1Password で共有する、は漏洩リスクが常につきまとう。
| 方法 | セキュリティ | 運用負荷 | 推奨度 |
|---|---|---|---|
Slack／Drive で .env 送信 | 極低 | 低 | 即廃止 |
| 1Password／Bitwarden 共有 | 中 | 中 | 小規模のみ |
| HashiCorp Vault | 高 | 中 | 中〜大規模 |
| AWS Secrets Manager／Parameter Store | 高 | 低 | AWS 環境の本命 |
| Doppler／Infisical | 高 | 低 | SaaS 志向の本命 |
| 直接配布しない（開発者権限のみ） | 最高 | 中 | 理想 |
理想は開発者にシークレットを配らない運用です。開発者は自分のIAMロールで一時トークンを取得し、本番キーには一切触らない。Doppler や Infisical は .env を中央で管理し、CLIでローカルに展開する仕組みが整っており、小〜中規模チームでも現実的な選択肢になりました。
IDE設定の共有
開発体験の均質化には、IDE設定の共有が効きます。VS Code であれば .vscode/settings.json、JetBrains であれば .idea/ の特定ファイルをリポジトリにコミットすると、フォーマッタ・Lint・保存時アクションがチーム全員で揃います。
| 共有すべき | 共有すべきでない |
|---|---|
| formatter の設定（保存時整形など） | 個人のキーバインド |
推奨拡張機能（.vscode/extensions.json） | 個人のテーマ・色設定 |
デバッグ構成（.vscode/launch.json） | 個人の AI 補完設定 |
| ワークスペース固有の Lint 例外 | 個人のフォント設定 |
.vscode/extensions.json の recommendations に拡張を列挙するだけで、リポジトリを開いた瞬間に VS Code が「この拡張を入れますか？」とプロンプトします。新人のセットアップ工数を地味に削る効果があり、入れるだけで恩恵しかない低コスト施策です。
本番データをローカルで使うか
「本番のデータで動作確認したい」という要求は必ず出てきますが、本番DBダンプをそのまま配るのは現時点では禁じ手です。PII（個人識別情報）・決済情報・医療情報などの漏洩リスクが制御不能になります。
| 方法 | 内容 | 推奨度 |
|---|---|---|
| 本番ダンプを配布 | 開発者 PC に本番データが丸ごと | 絶対にやめる |
| マスク済みダンプを配布 | 氏名・住所・カード番号をダミーに置換 | 本命 |
| 合成データ（Faker 等）で生成 | 本番と同じボリューム・同じ分布のダミー | PII 完全回避 |
| ステージング環境への直接アクセス | ローカルから stg に接続 | 規模・ポリシー次第 |
マスク済みダンプの自動生成（pg_dump + マスキングSQL + 日次スケジュール）を整備するのが鉄板です。個人情報保護法・GDPR・HIPAA など地域の規制で本番データの持ち出しが違法になるケースもあるため、「個人情報を開発者のPCに載せない」という線引きが最初の設計判断になります。
本番ダンプの配布は禁じ手。マスクか合成の二択です。
AI時代の視点
AI 駆動開発では、開発環境はAIが読み書きしやすい状態に寄せる設計が決定的に効きます。AI（GitHub Copilot・Claude Code・Cursor・Windsurf 等）はdevcontainer・docker-compose・標準YAMLの情報量が圧倒的に多く、独自スクリプトや手順書ベースの環境はAIの補完精度が落ちます。
| AI時代に有利 | AI時代に不利 |
|---|---|
| devcontainer（標準的な AI 補完対象） | 独自の setup.sh 群 |
| docker-compose（学習データ豊富） | OS 依存のインストール手順 |
.env.exampleの整備 | 口伝のキー・設定 |
| Codespaces 等のクラウド環境 | ローカル PC の職人芸環境 |
宣言的な依存管理（package.json・pyproject.toml） | 手動で入れた依存・pip install の記憶 |
AIエージェントがローカルで動作確認する時代がもう始まっており、エージェントが環境を自力で立てられる状態が望ましい。docker-compose + devcontainer 化されたリポジトリは、AI エージェントが docker compose up で自走できるため、AI駆動開発との相性が最高です。
AI 時代は環境もコードで宣言。口伝は競争力を静かに殺します。
よくある勘違い①
開発環境に関する誤解は、新人の立ち上がりを直撃します。
READMEが充実していればOK
READMEは必ず古くなります。手順書で環境が作れる限り、実行可能な make setup や devcontainer に勝てません。README は補助、「実行可能なコードが唯一の真実」です。
Dockerは重いから実機で直接インストール
実機インストールこそ重いというのが実態です。OS アップデートでビルドが通らなくなる・他プロジェクトとバージョン衝突・再現性ゼロ。Docker の起動オーバーヘッドより、「動かなくなった時のデバッグ時間」の方が圧倒的に長い。
よくある勘違い②
Codespacesは贅沢で不要
新人の初日の価値はエンジニア年収÷240日。つまり1日1〜3万円の価値があり、Codespaces 月30ドルは桁違いに安い投資です。「贅沢」に見えるのは会計上の錯覚。
シークレットは面倒だから.env直配布でいい
漏洩時の事故コストが桁違いです。AWS の IAM キー1本が漏れて、仮想通貨マイニングに使われ数日で数百万円請求、という事例は現在も継続的に発生しています。OIDC + Secrets Manager は初期投資で済みます。
環境構築は見えない時間コストを削る仕事。目に見える成果は出ませんが、半年後に効きます。
決めるべきこと — あなたのプロジェクトでの答えは？
以下の項目について、あなたのプロジェクトの答えを1〜2文で言語化してみてください。曖昧なまま着手すると、必ず後から「なぜそう決めたんだっけ」が問われます。
- ベースライン環境（docker-compose／VM／実機）
- 宣言的環境の採用（devcontainer／Nix／なし）
- クラウド環境の採用（Codespaces／Gitpod／なし）
- 初コミット目標時間（半日／1日／1週間）
- シークレット配布方法（Vault／Secrets Manager／Doppler）
- 本番データの扱い（マスク済み／合成データ）
- タイムゾーン統一方針（UTC固定推奨）
- IDE 設定共有（
.vscode/settings.jsonコミット）
筆者メモ — 初コミットまで2週間の中規模SaaS
ある中規模 SaaS 企業で、新規参画したエンジニアが初コミットまで2週間かかる状態にあった事例が業界で広く知られています。原因は、環境構築手順が口伝で共有されていたこと、DB ダンプを持っている人を毎回探し回らなければならなかったこと、必要な社内認証ツールのインストール手順がConfluence の複数ページに散在していたこと──一つずつは小さい摩擦でも、積み重なって2週間になる典型です。
このチームは devcontainer + 社内 Vault からのキー取得自動化 + マスク済みDBダンプの日次配布 を整備し、初コミットまでの時間を半日まで短縮しました。その後のオンボーディング工数が毎回激減し、新人の離職率まで改善した──と報告されています。環境構築の摩擦は、採用した人材の立ち上がり速度に直接効く投資です。
「俺のマシンでは動く」を文化にしてはいけません。
最終的な判断の仕方
開発環境設計の本質は、個人の環境差を、仕組みで消し去るという発想です。人間の手順書配布は必ず劣化し、新人ごとに微妙に違う環境が量産される。だから選定の核は、コードとしてコミットされる環境定義（docker-compose／devcontainer／Nix）に全てを寄せ、READMEは補助扱いにすることです。新人が初コミットまで半日で辿り着けるかどうかが、チームの成熟度を測る正直な指標です。
現時点の鉄板は「docker-compose + devcontainer + Codespaces（選択的）+ Secrets Manager／Doppler + マスク済みダンプ + UTC固定」Nix は刺さるチームにしか刺さらず、9割のチームには早すぎる。AI 駆動開発では、AI エージェントが環境を自走できるかどうかが差になるため、標準的な宣言的環境に寄せるほど生成・補完の精度が上がります。口伝・手作業・個人スクリプトは、AI 時代には競争力を静かに失う選択です。
選定の優先順位
- docker-composeでベースライン — 本番と同じミドルウェア
- devcontainerでIDE設定・拡張まで含めて共有
- シークレットはSecrets Manager／Dopplerで配らない運用に
- 初コミット目標を半日に設定 — ボトルネックを計測して潰す
「環境はコードで宣言、口伝は即廃止」新人の初日の価値は、組織の未来そのものです。
まとめ
本記事は開発環境とローカル実行について、docker-compose・devcontainer・Codespaces・シークレット配布・本番データ扱い・IDE設定共有まで含めて解説しました。如何だったでしょうか。
docker-composeでベースライン、devcontainerで設定共有、シークレットは配らない運用に、初コミット目標を半日に設定する。これが2026年の開発環境設計の現実解です。
次回はコードレビュー（PR運用・CODEOWNERS・マージキュー）について解説します。
シリーズ目次に戻る → 『生成AI時代のアーキテクチャ超入門』の歩き方
それでは次の記事も閲覧いただけると幸いです。
📚 シリーズ：生成AI時代のアーキテクチャ超入門（57/89）