environment-setup

環境設定

このスキルは、リポジトリのアプリケーション設定と .env の互換性に特化したスキルとして使用してください。

目的は、環境をまたいでアプリケーション設定を明確かつ安全にすることです。

• 環境変数に何を含めるかを判断する
• .env ファイルと優先順位のルールを構成する
• 必須の設定を検証する
• 公開値と非公開値を分ける
• ローカル、CI、ステージング、本番環境の設定のずれを減らす
• シークレットの受け渡しを明確にする

通常とは異なるケースや、実際のニーズが system-environment-setup に属するか判断する場合は、references/env-patterns.md と references/scope-boundaries.md を読んでください。

ユーザーの主なニーズが以下の場合：

• ツールチェーン、ローカルサービス、Docker Compose、開発コンテナ、またはオンボーディング → system-environment-setup に引き継ぎます
• デプロイまたは CI のシークレット配線 → deployment-automation と併用します
• セキュリティアーキテクチャまたはポリシー → security-best-practices と併用します

このスキルを使う場合

• .env.example、.env.local、または環境ごとの設定構成を設計する
• 環境変数の優先順位と、コミットすべき値・すべきでない値を説明する
• 型チェックや実行時チェックで必須の環境変数を検証する
• サーバー専用の環境変数とクライアントに公開される環境変数を分ける
• ローカル、CI、ステージング、本番環境の設定のずれを減らす
• 環境変数ファイル、シークレットのドキュメント、実行時の要件に食い違いがあるリポジトリを整理する
• 環境変数で十分な場合と、シークレットマネージャーによる注入が必要な場合を判断する

このスキルを使わない場合

• 主なタスクが、すべてのマシンでリポジトリ全体を実行可能にすること → system-environment-setup を使用します
• 主なタスクが、ローカルサービスのオーケストレーション、Docker、または開発コンテナであること → system-environment-setup を使用します
• 主なタスクが、デプロイの自動化または本番環境へのリリースであること → deployment-automation を使用します
• 主なタスクが、設定の整理ではなく、より広範なセキュリティレビューであること → security-best-practices と併用します

手順

Step 1: 設定の問題を分類する

まず、依頼内容を以下の形式に整理します。

env_config_intake:
  primary_goal: env-structure | validation | secret-handoff | public-private-split | drift-cleanup | framework-rules | unknown
  app_shape: backend | frontend | fullstack | monorepo | unknown
  current_storage: env-files | framework-config | secret-manager | mixed | unknown
  drift_surface:
    - missing-required-vars
    - duplicate-env-files
    - CI-local-mismatch
    - public-private-leak-risk
    - undocumented-secret-source
    - framework-prefix-confusion
    - unclear
  confidence: high | medium | low

Step 2: 主要モードを1つ選ぶ

実行時に使用するモードを、次の中から正確に1つ選びます。

1. env-file-structure
   • 主なニーズがファイルの配置、命名、優先順位の場合に使用します。
2. env-validation
   • 値の欠落や形式の不備によって、実行時またはビルド時に問題が発生している場合に使用します。
3. secret-handoff-boundary
   • .env ファイルが、シークレットマネージャーや認証情報の受け渡しに関する問題と衝突している場合に使用します。
4. framework-config-rules
   • 主な問題が、フレームワーク固有の環境変数の挙動（公開用／非公開用のプレフィックス、ビルド時と実行時の公開範囲など）の場合に使用します。
5. drift-cleanup
   • 環境変数のテンプレート、ドキュメント、CI 変数、実際の実行時要件に食い違いがある場合に使用します。

Step 3: 設定ルールを適用する

• デプロイ固有の値をソースコードに含めず、安全なテンプレートのみをコミットします。
• コミットするテンプレートと開発者のローカル値を分けます。
• 公開／クライアントに公開される環境変数とサーバー専用の値を、見た目で区別できるようにします。
• 環境変数のずれによるコストが高くなる規模のアプリでは、型付きの検証を優先します。
• シークレットの取得元（ローカルファイル、シークレットマネージャー、CI 変数、またはクラウドプラットフォーム）を記録します。
• 実際の障害要因が設定設計ではなく、マシンのセットアップ、Docker、またはローカルサービスである場合は、適切な担当先に引き継ぎます。

Step 4: 設定概要を作成する

以下の正確な構成で返します。

# Environment Config Brief

## Recommended mode
- Mode: env-file-structure | env-validation | secret-handoff-boundary | framework-config-rules | drift-cleanup
- Why this mode fits: ...

## Current config surface
- App shape: ...
- Config sources: ...
- Main drift or risk: ...
- Confidence: high | medium | low

## Recommended config layout
1. ...
2. ...
3. ...

## Example files / checks
```bash
...

この構成がより安全な理由

• ...
• ...

注意点

• ...
• ...

関連する引き継ぎ先

• ... には system-environment-setup を使用します
• ... には deployment-automation を使用します
• ... には security-best-practices を使用します

### Step 5: Use mode-specific guidance

**For env-file-structure**
- Define the committed template files first.
- Call out local-only overrides and ignored files explicitly.
- Make precedence easy to explain.

**For env-validation**
- Choose a schema/validation layer appropriate for the stack.
- Fail fast with clear missing-variable messages.
- Keep validation close to app startup.

**For secret-handoff-boundary**
- Name which values are safe in templates and which must come from a secret source.
- Document how a developer obtains sensitive values.
- Avoid pretending secret-manager adoption removes the need for local conventions.

**For framework-config-rules**
- Explain public/private env prefixes and build-time/runtime behavior.
- Call out framework-specific exposure risks.

**For drift-cleanup**
- Compare templates, runtime code, CI vars, and docs.
- Remove duplicate or stale env file conventions.
- Make one source of truth obvious.

### Step 6: Keep boundaries sharp
Before finalizing:
- Do **not** turn this into a Docker/devcontainer tutorial.
- Do **not** bury public/private env exposure risk.
- Do **not** assume `.env` files are enough for all secret workflows.
- Do **not** keep this as a peer duplicate of `system-environment-setup`; route broader setup work outward.

## Examples

### Example 1: Env template cleanup
Input: "Help me structure `.env.example` and `.env.local` so new devs stop guessing values."
Output: chooses `env-file-structure`, defines committed templates vs local overrides, and keeps the scope at app config.

### Example 2: Validation hardening
Input: "We keep forgetting env vars until runtime."
Output: chooses `env-validation`, recommends typed validation, and shows how to fail fast.

### Example 3: Framework split
Input: "Which env vars can be exposed to the frontend and which must stay server-only?"
Output: chooses `framework-config-rules`, explains the client/server split, and avoids broad setup drift.

## Best practices
1. Treat this as the app-config layer, not the whole-machine setup skill.
2. Make secret sources explicit rather than implied.
3. Prefer committed templates plus local-only overrides.
4. Add validation once env drift becomes expensive.
5. Route broader runnable-repo work to `system-environment-setup`.

## References
- [Environment patterns](references/env-patterns.md)
- [Scope boundaries](references/scope-boundaries.md)
- [Twelve-Factor config](https://12factor.net/config)
- [Next.js env guide](https://nextjs.org/docs/app/guides/environment-variables)
- [T3 Env intro](https://env.t3.gg/docs/introduction)