env-manager

環境変数マネージャー（env-manager）

最新の Web アプリケーション向けに、環境変数の包括的な検証、セキュリティスキャン、管理を行います。

概要

env-manager スキルは、ローカル開発、CI/CD パイプライン、デプロイプラットフォームにおける環境変数の体系的な管理を実現します。変数の不足、シークレットの漏えい、フレームワーク固有の設定エラーなど、よくある問題を防ぎます。

主な機能：

• フレームワークを考慮した検証：Next.js、Vite、React、Node.js、Flask に対応
• セキュリティを最優先：シークレットをログに記録せず、漏えいした認証情報を検出
• プラットフォームとの連携：Vercel、Railway、Heroku、CI/CD にすぐに対応
• 高速：1000 個の変数を 0.025 秒で検証（目標の 2 秒より 80 倍高速）
• 依存関係ゼロ：純粋な Python で、どこでも動作

env-manager を使う理由

解決する一般的な問題：

• 「自分のマシンでは動くのに、本番環境では動かない」（環境変数の不足）
• クライアントサイドのコードで API キーを誤って公開してしまう（シークレットを含む NEXT_PUBLIC_）
• デプロイ時に必須変数が不足している
• チームメンバー間で .env ファイルに一貫性がない
• 必須の環境変数に関するドキュメントがない
• シークレットの漏えいによるセキュリティ上の脆弱性

クイックスタート

インストール

インストールは不要です！env-manager は Claude MPM に同梱されているスキルです。

要件：

• Python 3.7+
• 外部依存関係なし

5 分で始めるクイックスタート

# 1. Validate your .env file
python3 scripts/validate_env.py .env

# 2. Check for framework-specific issues (Next.js example)
python3 scripts/validate_env.py .env --framework nextjs

# 3. Compare with .env.example to find missing vars
python3 scripts/validate_env.py .env --compare-with .env.example

# 4. Generate .env.example for documentation
python3 scripts/validate_env.py .env --generate-example .env.example

# 5. Get JSON output for CI/CD integration
python3 scripts/validate_env.py .env --json

これで完了です！環境変数が適切に検証されるようになりました。

使用例

基本的な検証

.env ファイルに構造上の問題がないか検証します。

python3 scripts/validate_env.py .env

検査内容：

• 有効な key=value 形式
• キーの重複がないこと
• 適切な命名規則（UPPERCASE_WITH_UNDERSCORES）
• 空の値がないこと（明示的に許可されている場合を除く）
• 空白を含む値が適切に引用符で囲まれていること

出力例：

✅ Validation successful!
   - 15 variables validated
   - 0 errors
   - 0 warnings

フレームワーク固有の検証

Next.js

Next.js の環境変数を検証します。

python3 scripts/validate_env.py .env.local --framework nextjs

Next.js 固有の検査：

• NEXT_PUBLIC_* 変数はクライアントに公開されます（シークレットを検出した場合に警告）
• .env.local、.env.production、.env の階層
• クライアントサイド変数に含まれるシークレットを検出

例：

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_API_KEY=secret123  # ⚠️  WARNING: Secret in client-exposed variable!
DATABASE_URL=postgresql://...   # ✅ Server-side only

Vite

python3 scripts/validate_env.py .env --framework vite

Vite 固有の検査：

• VITE_* 変数はクライアントに公開されます
• VITE_ で始まる変数にシークレットを検出した場合に警告

React（Create React App）

python3 scripts/validate_env.py .env --framework react

React 固有の検査：

• REACT_APP_* 変数はクライアントに公開されます
• REACT_APP_ で始まる変数にシークレットが含まれている場合に警告

Node.js/Express

python3 scripts/validate_env.py .env --framework nodejs

Node.js 固有の検査：

• 一般的な NODE_ENV、PORT、DATABASE_URL のパターン
• 標準的な Node.js の規則

Flask/Python

python3 scripts/validate_env.py .env --framework flask

Flask 固有の検査：

• FLASK_APP、FLASK_ENV 変数
• SQLAlchemy の DATABASE_URL 形式

.env.example との比較

.env にすべての必須変数があることを確認します。

python3 scripts/validate_env.py .env --compare-with .env.example

検査内容：

• .env.example のすべての変数が .env に存在すること
• .env にドキュメント化されていない余分な変数がないこと

出力例：

❌ Missing variables:
   - DATABASE_URL (required in .env.example)
   - STRIPE_SECRET_KEY (required in .env.example)

⚠️  Extra variables not in .env.example:
   - DEBUG_MODE (consider adding to .env.example)

次の用途に最適です：

• 新しいチームメンバーのオンボーディング
• CI/CD の検証
• デプロイ前のチェック

.env.example の生成

環境変数のドキュメントを作成します。

python3 scripts/validate_env.py .env --generate-example .env.example

処理内容：

• .env ファイルを読み込みます
• シークレット値を無害化します（プレースホルダーに置き換えます）
• 安全なデフォルト値を含む .env.example を生成します

例：

# Input: .env
DATABASE_URL=postgresql://user:pass@localhost/db  # pragma: allowlist secret
STRIPE_SECRET_KEY=sk_live_abc123xyz
NEXT_PUBLIC_API_URL=https://api.example.com

# Output: .env.example
DATABASE_URL=postgresql://user:password@localhost/dbname  # pragma: allowlist secret
STRIPE_SECRET_KEY=your_stripe_secret_key_here
NEXT_PUBLIC_API_URL=https://api.example.com

セキュリティに関する注意： env-manager は一般的なシークレットのパターンを検出し、安全なプレースホルダーに置き換えます。

CI/CD との連携

自動化されたワークフロー向けに、機械可読な JSON 出力を取得します。

python3 scripts/validate_env.py .env.example --strict --json

JSON 出力形式：

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "stats": {
    "total_vars": 15,
    "errors": 0,
    "warnings": 0
  }
}

終了コード：

• 0：検証に合格
• 1：検証エラーを検出
• 2：必須ファイルがない
• 3：警告を検出（--strict モードの場合のみ）

GitHub Actions の例：

name: Validate Environment Variables

on: [push, pull_request]

jobs:
  validate-env:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Validate .env.example
        run: |
          python3 scripts/validate_env.py .env.example --strict --json
        working-directory: ./path/to/skill

      - name: Check for framework-specific issues
        run: |
          python3 scripts/validate_env.py .env.example --framework nextjs --json
        working-directory: ./path/to/skill

厳格モード

警告をエラーとして扱います（CI/CD に便利です）。

python3 scripts/validate_env.py .env --strict

使用する場面：

• デプロイ前の検証
• CI/CD パイプライン
• リリースゲート
• チーム標準の徹底

静音モード

エラーのみを表示し、警告を抑制します。

python3 scripts/validate_env.py .env --quiet

使用する場面：

• 警告をすでに確認済みの場合
• エラーのみを対象とする自動スクリプト
• 警告が煩わしいノイズの多い環境

対応フレームワーク

フレームワーク	プレフィックス	クライアントに公開	備考
Next.js	NEXT_PUBLIC_*	はい	ブラウザーに自動公開
Vite	VITE_*	はい	クライアントコードにバンドル
React (CRA)	REACT_APP_*	はい	本番ビルドに埋め込み
Node.js	N/A	いいえ	サーバー側のみ
Flask	N/A	いいえ	サーバー側のみ

セキュリティ警告： クライアントに公開される変数（NEXT_PUBLIC_、VITE_、REACT_APP_）には、シークレットを決して設定しないでください。env-manager は、一般的なシークレットのパターンを検出すると警告します。

CLI リファレンス

コマンド構造

python3 scripts/validate_env.py <file> [options]

オプション

オプション	説明	例
--compare-with FILE	.env.example と比較します	--compare-with .env.example
--framework {nextjs|vite|react|nodejs|flask|generic}	フレームワーク固有の検証を行います	--framework nextjs
--strict	警告をエラーとして扱います	--strict
--json	自動化向けに JSON 形式で出力します	--json
--quiet	エラーのみを表示します	--quiet
--generate-example OUTPUT	.env.example を生成します	--generate-example .env.example

終了コード

コード	意味	条件
0	成功	エラーなし（--strict が指定されていない場合、警告は許容）
1	検証エラー	構造上の問題、重複など
2	ファイルが見つかりません	指定された .env ファイルが存在しません
3	厳格モードでの警告	警告があり、--strict が有効です

よくある使用例

シナリオ 1：新しい開発者のオンボーディング

# New developer clones repo
git clone <repo>
cd <project>

# Copy example and fill in values
cp .env.example .env
# Edit .env with actual values...

# Validate setup
python3 scripts/validate_env.py .env --compare-with .env.example

# If missing variables, fix them
# Validation passes ✅

シナリオ 2：デプロイ前の確認

# Before deploying to Vercel/Railway/Heroku
python3 scripts/validate_env.py .env.production --framework nextjs --strict

# Fix any errors
# Deploy with confidence ✅

シナリオ 3：セキュリティ監査

# Check for accidentally exposed secrets
python3 scripts/validate_env.py .env.local --framework nextjs

# Look for warnings like:
# ⚠️  NEXT_PUBLIC_STRIPE_SECRET: Contains potential secret in client-exposed variable

シナリオ 4：チームのドキュメント作成

# After adding new environment variable
echo "NEW_API_KEY=abc123" >> .env

# Regenerate .env.example
python3 scripts/validate_env.py .env --generate-example .env.example

# Commit updated .env.example
git add .env.example
git commit -m "docs: add NEW_API_KEY to environment variables"

シナリオ 5：CI/CD 品質ゲート

# In your CI pipeline
- name: Validate environment configuration
  run: |
    python3 scripts/validate_env.py .env.example --strict --json > validation.json

    # Fail pipeline if validation fails
    if [ $? -ne 0 ]; then
      cat validation.json
      exit 1
    fi

パフォーマンス

env-manager は高速に動作するよう設計されています。

ベンチマーク：

• 1000 個の変数を 0.025s で検証
• 目標の 2 秒より 80 倍高速
• 外部依存関係なし
• メモリー使用量は最小限

重要な理由：

• 開発中にすばやくフィードバックを得られます
• CI/CD の速度を低下させません
• リソースが限られた環境でも動作します

セキュリティに関する注意事項

重要なセキュリティ機能：

1. シークレットをログに記録しない： env-manager は、出力にシークレットの実際の値を決して表示しません
2. クライアントへの公開を検出： NEXT_PUBLIC_、VITE_、REACT_APP_ 変数にシークレットが含まれている場合に警告します
3. シークレットのサニタイズ： .env.example の生成時に、シークレットを安全なプレースホルダーに置き換えます
4. ネットワーク呼び出しなし： 検証はすべてローカルで行われ、データがマシンの外部に送信されることはありません

セキュリティ監査済み： このスキルはセキュリティレビューを受けています。詳細は references/security.md を参照してください。

ベストプラクティス：

• シークレットを含む .env ファイルを決してコミットしない
• ドキュメントには常に .env.example を使用する
• 本番環境ではプラットフォームのシークレットマネージャー（Vercel、Railway など）を使用する
• デプロイの前に必ず検証する
• セキュリティスキャンを定期的に実行する

よくある問題

「等号がありません」エラー

原因： .env の行に区切り文字 = がありません

修正：

# ❌ Bad
API_KEY

# ✅ Good
API_KEY=your_key_here

「キーが重複しています」エラー

原因： 同じ変数が複数回定義されています

修正：

# ❌ Bad
API_KEY=value1
API_KEY=value2

# ✅ Good
API_KEY=value2

「変数名が無効です」警告

原因： 変数名が UPPERCASE_WITH_UNDERSCORES の規則に従っていません

修正：

# ❌ Bad
apiKey=value
api-key=value

# ✅ Good
API_KEY=value

「クライアントに公開される変数にシークレットの可能性があります」警告

原因： NEXT_PUBLIC_、VITE_、または REACT_APP_ 変数にシークレットのような値が含まれています

修正：

# ❌ Bad (secret exposed to client!)
NEXT_PUBLIC_STRIPE_SECRET=sk_live_abc123

# ✅ Good (server-side only)
STRIPE_SECRET_KEY=sk_live_abc123
NEXT_PUBLIC_STRIPE_PUBLISHABLE=pk_live_xyz789

「値が空です」警告

原因： 変数に値がありません

修正：

# ❌ Bad
DATABASE_URL=

# ✅ Good (if optional, document it)
DATABASE_URL=  # Optional, uses SQLite if not set

# ✅ Better
DATABASE_URL=postgresql://localhost/mydb

ファイルが見つからないエラー

原因： 指定された .env ファイルが存在しません

修正：

# Check file exists
ls -la .env

# Or create it
touch .env

トラブルシューティング

ローカルでは検証に合格するのに、CI では失敗する

確認項目：

1. 改行コード（CRLF と LF）
2. ファイルのエンコーディング（UTF-8 が必要です）
3. ファイルの権限
4. Python のバージョン（3.7 以上が必要です）

クライアントに公開される変数に関する警告

これは意図された動作です！ env-manager は、NEXT_PUBLIC_API_KEY のような変数がブラウザー上で参照可能になることを警告しています。

選択肢：

1. シークレットをサーバー側の変数に移動します（NEXT_PUBLIC_ 接頭辞を削除）
2. クライアントに公開される変数には、公開用のキーのみを使用します
3. 本当にシークレットではない場合は、警告を無視します

.env.example の生成時に置換されすぎる

env-manager はシークレットを慎重に扱います。過剰にサニタイズされる場合は、次の方法をお試しください。

1. 生成後に .env.example を手動で編集します
2. .env で、サニタイズの対象にならない具体的なプレースホルダー値を使用します

高度な使い方

カスタム検証パターン

高度な検証パターンについては、references/validation.md を参照してください。

プラットフォーム固有のデプロイ

Vercel、Railway、Heroku との統合パターンについては、references/synchronization.md を参照してください。

フレームワーク固有のガイド

フレームワークに関する包括的なガイドについては、references/frameworks.md を参照してください。

関連ドキュメント

• 検証リファレンス：検証ワークフローとチェックの完全ガイド
• セキュリティリファレンス：シークレットのスキャンとセキュリティパターン
• 同期リファレンス：プラットフォーム同期パターン（近日公開）
• フレームワークリファレンス：フレームワーク固有のパターンと規約
• トラブルシューティングガイド：よくある問題と解決策

Claude MPM との統合

env-manager は Claude MPM にバンドルされているスキルです。エージェントは次の用途に利用できます。

• デプロイ前の検証
• セキュリティスキャン
• 環境設定の検証
• ドキュメントの生成

エージェントとの統合パターンについては、INTEGRATION.md を参照してください。

貢献

env-manager は Claude MPM の貢献ガイドラインに従っています。

1. 開発中に make lint-fix を実行します
2. コミット前に make quality を実行します
3. 新機能にはテストを追加します（カバレッジ 85% 以上が必要です）
4. ドキュメントを更新します

詳細については、CONTRIBUTING.md を参照してください。

ライセンス

MIT ライセンス - Claude MPM プロジェクトの一部

サポート

• 問題：GitHub Issues からバグを報告してください
• ドキュメント：references/ ディレクトリを参照してください
• 例：examples/ ディレクトリを参照してください
• 統合：INTEGRATION.md を参照してください

---

バージョン：1.0.0 ステータス：安定版、セキュリティ監査済み テストカバレッジ：85% 以上 パフォーマンス：目標値より 80 倍高速