infra-config-setup-env

環境管理

クイックガイド： アプリごとに .env ファイルを使用します。フレームワーク固有のプレフィックス（Next.js では NEXT_PUBLIC_*、Vite では VITE_*）を使用します。起動時に Zod で検証します。.env.example テンプレートを維持します。シークレットは決してコミットしません（.gitignore）。環境ベースの機能フラグを使用します。

---

<critical_requirements>

重要：このスキルを使用する前に

すべてのコードはプロジェクトの規約に従う必要があります（CLAUDE.md）（kebab-case、名前付きエクスポート、インポート順序、import type、名前付き定数）

（アプリケーションの起動時に、すべての環境変数を Zod で検証する必要があります）

（クライアント側の変数には、フレームワーク固有のプレフィックスを使用する必要があります。Next.js では NEXT_PUBLIC_*、Vite では VITE_* を使用します）

（必須の変数をすべて記載した .env.example テンプレートを維持する必要があります）

（バージョン管理にシークレットをコミットしてはいけません。.env.local と CI シークレットを使用してください）

（アプリごとに .env ファイルを使用する必要があります。ルートレベルの .env ファイルは使用しないでください）

</critical_requirements>

---

自動検出： 環境変数、.env ファイル、Zod 検証、t3-env、@t3-oss/env、シークレット管理、NEXT_PUBLIC_ プレフィックス、VITE_ プレフィックス、機能フラグ、z.stringbool

使用する場面：

• 起動時に型安全な環境変数を得るための Zod 検証を設定するとき
• フレームワーク固有のプレフィックスを使って、アプリごとの .env ファイルを管理するとき
• シークレットを保護するとき（決してコミットせず、.env.local と CI シークレットを使用します）
• 環境ベースの機能フラグを実装するとき

使用しない場面：

• 実行時の設定変更（外部の機能フラグサービスを使用してください）
• ユーザーごとの設定（データベースまたはユーザー設定を使用してください）
• 頻繁に変更される値（設定 API またはデータベースを使用してください）
• 段階的なロールアウトを伴う複雑な A/B テスト（専用の機能フラグサービスを使用してください）

対象となる主なパターン：

• アプリごとの .env ファイル（競合を防ぐため、ルートレベルには置きません）
• 型安全性と早期エラーのための起動時の Zod 検証
• Next.js/Vite プロジェクト向けの T3 Env パターン（推奨）
• フレームワーク固有のプレフィックス（クライアントでは NEXT_PUBLIC_*、Vite クライアントでは VITE_*）
• ドキュメントと導入のための .env.example テンプレート

詳細なリソース：

• コード例は examples/ フォルダーを参照してください：
  • examples/core.md - 基本パターン（アプリごとの .env、Zod 検証）
  • examples/t3-env.md - Next.js/Vite 向けの T3 Env パターン（推奨）
  • examples/naming-and-templates.md - フレームワークのプレフィックス、.env.example
  • examples/security-and-secrets.md - シークレット管理
  • examples/feature-flags-and-config.md - 機能フラグ、一元管理された設定
• 判断の枠組みとアンチパターンについては、reference.md を参照してください

---

基本方針

環境管理は、設定はコードであるという原則に従います。つまり、設定は検証され、型付けされ、バージョン管理されるべきです。このシステムでは、アプリごとの .env ファイル、フレームワーク固有のプレフィックス、起動時の Zod 検証、そしてシークレットの漏えいを防ぐ厳格なセキュリティ対策を使用します。

---

基本パターン

パターン 1：アプリごとの環境ファイル

競合を防ぎ、所有者を明確にするため、各アプリ／パッケージには独自の .env ファイルがあります。

ファイル構成

apps/
├── client-next/
│   ├── .env                    # Local development (NEXT_PUBLIC_API_URL)
│   └── .env.production         # Production overrides
├── client-react/
│   ├── .env                    # Local development
│   └── .env.production         # Production overrides
└── server/
    ├── .env                    # Local server config
    ├── .env.example            # Template for new developers
    └── .env.local.example      # Local overrides template

packages/
├── api/
│   └── .env                    # API package config
└── api-mocks/
    └── .env                    # Mock server config

ファイルの種類と用途

1. .env - 開発用のデフォルト値（アプリではコミットし、機密性の高いパッケージでは gitignore に追加します）
2. .env.example - ドキュメント用テンプレート（コミットし、必須の変数をすべて記載します）
3. .env.local - 開発者用のローカル上書き設定（gitignore に追加し、.env より優先されます）
4. .env.production - 本番環境の設定（コミットするか、CI シークレットに保存します）
5. .env.local.example - ローカル上書き設定のテンプレート（コミットします）

読み込み順序と優先順位

Next.js の読み込み順序（優先度の高い順）：

1. process.env（環境にすでに設定されているもの）
2. .env.$(NODE_ENV).local（例：.env.production.local）
3. .env.local（NODE_ENV=test の場合は読み込まれません）
4. .env.$(NODE_ENV)（例：.env.production）
5. .env

Vite の読み込み順序：

1. .env.[mode].local（例：.env.production.local）
2. .env.[mode]（例：.env.production）
3. .env.local
4. .env

例外： キャッシュ無効化のため、共通変数はビルドツールの環境変数設定に記述できます

コード例の全体については、examples/core.md を参照してください。

---

パターン 2：Zod を使用した型安全な環境変数

Zod スキーマを使用して、アプリケーションの起動時に環境変数を検証します。スキーマを定義し、起動時に解析して、型付けされた env オブジェクトをエクスポートします。

// lib/env.ts
const envSchema = z.object({
  VITE_API_URL: z.string().url(),
  VITE_API_TIMEOUT: z.coerce.number().default(DEFAULT_API_TIMEOUT_MS),
  VITE_ENABLE_ANALYTICS: z.stringbool().default(false), // Zod 4+ (NOT z.coerce.boolean())
});
export const env = envSchema.parse(import.meta.env);

主な注意点：

• z.coerce.boolean() は "false" を true に変換します（文字列は truthy です）。必ず z.stringbool() を使用してください
• Zod 4 のエラー処理には error.errors ではなく error.issues を使用してください

注： Next.js／Vite プロジェクトでは、クライアント変数とサーバー変数の分離およびビルド時の検証に、T3 Env（@t3-oss/env-nextjs または @t3-oss/env-core）の利用を検討してください。examples/t3-env.md を参照してください。

適切な例と不適切な例の比較を含むコード例の全体については、examples/core.md を参照してください。

---

パターン 3：フレームワーク固有の命名規則

クライアント側の変数にはフレームワーク固有のプレフィックスを使用し、すべての環境変数には SCREAMING_SNAKE_CASE を使用してください。

必須の規則

1. SCREAMING_SNAKE_CASE - すべての環境変数はアンダースコアを含む大文字で記述します
2. 説明的な名前 - 変数名から用途が明確にわかるようにします
3. フレームワークのプレフィックス - クライアント側の変数には NEXT_PUBLIC_*（Next.js）または VITE_*（Vite）を使用します

フレームワークのプレフィックス

Next.js：

• NEXT_PUBLIC_* - クライアント側からアクセス可能（バンドルに埋め込まれます）。API URL、公開鍵、機能フラグに使用します
• プレフィックスなし - サーバー側専用（データベース URL、シークレットキー、API トークン）

Vite：

• VITE_* - クライアント側からアクセス可能（バンドルに埋め込まれます）。API URL、公開設定に使用します
• プレフィックスなし - ビルド時専用（クライアントには公開されません）

Node.js／サーバー：

• NODE_ENV - 標準の環境（development、production、test）
• PORT - サーバーのポート番号
• プレフィックスなし - すべての変数をサーバー側で利用可能

適切な例と不適切な例の比較を含むコード例の全体については、examples/naming-and-templates.md を参照してください。

---

統合ガイド

主な依存関係：

• Zod（v4+）：環境変数の実行時検証と型推論
• T3 Env（@t3-oss/env-nextjs、@t3-oss/env-core）：クライアントとサーバーを分離するための推奨ラッパー

フレームワークのサポート：

• Next.js：.env ファイルの自動読み込み。クライアント側には NEXT_PUBLIC_* プレフィックスを使用
• Vite：.env ファイルの自動読み込み。クライアント側には VITE_* プレフィックスを使用

モノレポに関する考慮事項：

• キャッシュ無効化のため、共有環境変数をビルドツールの環境変数設定に宣言します
• モノレポでも、競合を防ぐためにアプリごとの .env ファイルを使用します

置き換え対象／競合するもの：

• ハードコードされた設定値（代わりに環境変数を使用します）
• 単純な真偽値フラグ向けの実行時機能フラグサービス（まず環境変数を使用し、段階的なロールアウトが必要になったら移行します）

---

<decision_framework>

判断フレームワーク

環境設定や機能フラグの判断を含む判断フレームワークの全体については、reference.md を参照してください。

</decision_framework>

---

<red_flags>

重大な問題

優先度の高い問題：

• シークレットをバージョン管理にコミットする（実際の認証情報を含む .env ファイル）
• Zod による検証を行わず、環境変数を直接使用する（実行時エラーの原因になります）
• シークレットに NEXT_PUBLIC_* または VITE_* プレフィックスを使用する（クライアントバンドルに埋め込まれます）

優先度が中程度の問題：

• .env.example のドキュメントがない（オンボーディングの質が低下します）
• 開発環境で本番環境のシークレットを使用する（セキュリティリスクになります）
• モノレポのルートレベルに .env を配置する（競合の原因になります）

注意点：

• Next.js/Vite はプレフィックス付きの変数を実行時ではなくビルド時に埋め込むため、変更するには再ビルドが必要です
• 環境変数は文字列です。数値には z.coerce.number()、ブール値には z.stringbool()（Zod 4 以降）を使用してください
• 重要： z.coerce.boolean() は "false" を true に変換します（文字列は truthy であるため）。代わりに z.stringbool()（Zod 4 以降）を使用してください
• 空文字列の環境変数は undefined ではありません。T3 Env の emptyStringAsUndefined: true オプションを使用してください
• モノレポのビルドツールのキャッシュは、ツールの環境変数設定で宣言しない限り、環境変数の変更によって無効化されない場合があります

重大な問題、アンチパターン、チェックリストの全項目については、reference.md を参照してください。

</red_flags>

---

<critical_reminders>

重要な注意事項

すべてのコードは CLAUDE.md のプロジェクト規約に従う必要があります

（アプリケーションの起動時に、すべての環境変数を必ず Zod で検証してください）

（クライアント側の変数には、必ずフレームワーク固有のプレフィックスを使用してください。Next.js では NEXT_PUBLIC_*、Vite では VITE_* を使用します）

（必要なすべての変数を記載した .env.example テンプレートを必ず用意してください）

（シークレットをバージョン管理にコミットしないでください。必ず .env.local と CI のシークレットを使用してください）

（必ずアプリごとの .env ファイルを使用してください。ルートレベルの .env ファイルは使用しないでください）

これらのルールを守らないと、実行時エラー、セキュリティの脆弱性、設定の混乱が生じます。

</critical_reminders>