environment-setup

环境配置

将此技能用作仓库中更专注于应用配置和 .env 兼容性的技能。

其目标是让应用配置在不同环境中清晰且安全：

• 确定哪些内容应放入环境变量，
• 设计 .env 文件结构和优先级规则，
• 验证必需配置，
• 区分公开值和私密值，
• 减少本地、CI、预发布和生产环境之间的配置漂移，
• 明确机密信息的交接方式。

遇到特殊情况，或需要判断实际需求是否应归入 system-environment-setup 时，请阅读 references/env-patterns.md 和 references/scope-boundaries.md。

如果用户的主要需求是：

• 工具链、本地服务、Docker Compose、devcontainer 或入门配置 → 转交给 system-environment-setup
• 部署或 CI 机密信息接入 → 与 deployment-automation 配合使用
• 安全架构或策略 → 与 security-best-practices 配合使用

何时使用此技能

• 设计 .env.example、.env.local 或按环境划分的配置结构
• 说明环境变量的优先级，以及哪些值应或不应提交
• 使用类型检查或运行时检查验证必需的环境变量
• 区分仅供服务端使用的环境变量与向客户端公开的环境变量
• 减少本地、CI、预发布和生产环境之间的配置漂移
• 整理环境变量文件、机密信息文档和运行时预期不一致的仓库
• 判断环境变量是否足够，还是需要通过机密管理器注入

何时不使用此技能

• 主要任务是让整个仓库能在不同机器上运行 → 使用 system-environment-setup
• 主要任务是编排本地服务、配置 Docker 或 devcontainer → 使用 system-environment-setup
• 主要任务是自动化部署或生产环境发布 → 使用 deployment-automation
• 主要任务是进行更广泛的安全审查，而非整理配置 → 与 security-best-practices 配合使用

指令

第 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

第 2 步：选择一种主要模式

每次运行只选择一种模式：

1. env-file-structure
   • 主要需求是文件布局、命名和优先级时使用。
2. env-validation
   • 缺失或格式错误的值导致运行时或构建问题时使用。
3. secret-handoff-boundary
   • .env 文件与机密管理器或凭据交付问题相互冲突时使用。
4. framework-config-rules
   • 主要问题是框架特定的环境变量行为（公开/私有前缀、构建时与运行时的值暴露等）时使用。
5. drift-cleanup
   • 环境变量模板、文档、CI 变量和实际运行时预期不一致时使用。

第 3 步：应用配置规则

• 不要将特定于部署的值写入源代码，只提交安全的模板。
• 区分已提交的模板与开发者本地值。
• 让公开/客户端可见的环境变量与仅供服务端使用的值在视觉上明显不同。
• 当应用规模大到配置漂移成本较高时，优先采用类型化验证。
• 记录机密信息的来源：本地文件、机密管理器、CI 变量或云平台。
• 如果实际阻碍是机器配置、Docker 或本地服务，而非配置设计，则转交给其他技能。

第 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)