system-environment-setup

系统与环境设置

将此技能用作仓库中更广泛环境设置的规范入口。

目标是让项目在不同开发者的机器和环境中都能运行且可重复。 通常包括以下部分：

• 运行时／工具版本固定
• 本地服务和容器
• 引导脚本
• 新手入门步骤
• 本地与生产环境的一致性权衡
• 密钥／配置交接边界
• 自动化偏离预期时的设置诊断

遇到特殊情况，或需要判断任务应归属此处还是 environment-setup 时，请阅读 references/operating-modes.md 和 references/scope-boundaries.md。

如果用户的主要需求是：

• .env 结构、环境变量优先级、验证或特定框架的应用配置 → 转交给 environment-setup
• CI/CD 流水线和托管部署自动化 → 转交给 deployment-automation 或 vercel-deploy
• 安全策略和密钥存储架构 → 与 security-best-practices 配合使用
• 项目任务拆分／新手入门清单的归属 → 与 task-planning 配合使用

何时使用此技能

• 让仓库能在全新机器上运行，并使用一致的工具
• 在多位贡献者之间统一本地开发设置
• 在本地主机、Docker Compose、devcontainers 或混合工作流之间进行选择
• 固定运行时／工具版本，减少不同机器间的偏差
• 设置本地配套服务，例如数据库、缓存、队列或搜索服务
• 设计引导命令、设置检查或新手入门流程
• 诊断本地设置文档、脚本、容器和实际运行行为彼此不一致的原因
• 改善本地环境与生产环境的一致性，但不假称二者完全相同

何时不使用此技能

• 主要任务是应用层的 .env 组织、环境变量架构验证或框架环境变量规则 → 使用 environment-setup
• 主要任务是生产部署、云端发布或 CI 编排 → 使用 deployment-automation
• 主要任务是托管基础设施安全审查 → 与 security-best-practices 配合使用
• 任务仅涉及安装一个软件包，不涉及更广泛的环境决策 → 有合适的专用安装／设置技能时，使用该技能

指引

步骤 1：确定设置范围

先按以下格式整理需求：

environment_intake:
  primary_goal: runnable-local-repo | standardized-onboarding | local-service-parity | toolchain-reproducibility | setup-diagnosis | hybrid
  current_state: greenfield | partially-working | drifted | broken-on-new-machine | unknown
  runtime_shape: single-service | app-plus-services | microservices | unknown
  host_strategy: host-native | docker-compose | devcontainer | hosted-remote-dev | hybrid | unknown
  config_strategy: simple-env-files | typed-validation | secret-manager-injection | mixed | unknown
  main_pain:
    - missing-prereqs
    - runtime-version-drift
    - local-service-startup
    - secrets-bootstrap
    - onboarding-doc-rot
    - cross-platform-differences
    - local-prod-parity
    - unclear
  confidence: high | medium | low

如果需求含糊不清，优先按最广义的可运行仓库来理解，并说明这一假设。

步骤 2：选择一种主要运行模式

每次运行必须且只能选择一种模式：

1. bootstrap-and-onboarding
   • 当仓库需要为贡献者提供清晰的首次运行流程时使用。
2. toolchain-reproducibility
   • 当运行时、CLI 或软件包版本在不同机器间不一致时使用。
3. local-services-and-parity
   • 当主要难点是本地数据库／缓存／队列／搜索服务，或应用与服务的拓扑结构时使用。
4. containerized-dev-environment
   • 当 Docker Compose、devcontainers 或 Codespaces 风格的流程是主要手段时使用。
5. setup-diagnosis-and-hardening
   • 当脚本、文档、容器和实际行为彼此不一致时使用。

步骤 3：选择能够解决问题的最小可重复环境方案

遵循以下规则：

• 优先选择能让仓库可靠运行的最小方案。
• 如果仓库较简单，先固定运行时／版本，再考虑引入更重型的容器。
• 如果配套服务或共享的本地拓扑结构很重要，则使用 Docker Compose。
• 如果编辑器／运行时标准化和新手入门速度比主机原生体验更重要，则使用 devcontainers。
• 将引导脚本／Makefiles／任务运行器作为辅助工具，而非唯一事实来源。
• 不要假称本地环境等同于生产环境；明确指出仍存在的一致性差异。
• 将应用层环境文件的设计和验证细节转交给 environment-setup，避免让此技能内容臃肿。

步骤 4：制定环境方案

按以下确切结构返回：

# Environment Setup Brief

## Recommended mode
- Mode: bootstrap-and-onboarding | toolchain-reproducibility | local-services-and-parity | containerized-dev-environment | setup-diagnosis-and-hardening
- Why this mode fits: ...

## Current setup surface
- Project shape: ...
- Host/container strategy: ...
- Config/secrets strategy: ...
- Main drift or blocker: ...
- Confidence: high | medium | low

## Recommended environment stack
1. ...
2. ...
3. ...

## Commands / files to create or verify
```bash
...

为什么这是合适的设置层级

• ...
• ...

需要说明的对等性差距

• ...
• ...

注意事项

• ...
• ...

相邻主题的交接

• 将 environment-setup 用于 ...
• 将 deployment-automation 用于 ...
• 将 security-best-practices 用于 ...

### Step 5: Apply mode-specific guidance

**For bootstrap-and-onboarding**
- Define the one clean happy path first.
- Separate prerequisites, secrets/bootstrap, and verification steps.
- Prefer a setup check (`make doctor`, `bin/setup --check`, etc.) when possible.

**For toolchain-reproducibility**
- Pin runtime versions explicitly.
- Choose one version-management layer per repo when possible.
- Call out cross-platform differences instead of hiding them.

**For local-services-and-parity**
- Name which services must run locally and which can stay remote.
- Prefer Docker Compose for shared service topology.
- Explain the local-prod gap instead of overselling parity.

**For containerized-dev-environment**
- Decide whether Compose, devcontainers, or both are necessary.
- Keep secrets/bootstrap out of committed container config unless clearly safe.
- State the editor or platform assumptions.

**For setup-diagnosis-and-hardening**
- Compare docs, bootstrap scripts, env templates, container files, and actual commands.
- Identify which artifact is authoritative.
- Reduce duplicate instructions and make verification explicit.

### Step 6: Keep boundaries sharp
Before finalizing:
- Do **not** bury `.env` / env validation details here when the real need belongs in `environment-setup`.
- Do **not** turn setup guidance into a cloud deployment tutorial.
- Do **not** claim total parity if auth, secrets, or platform quirks remain manual.
- Do **not** let bootstrap scripts become unexplained magic.

## Examples

### Example 1: Fresh repo onboarding
Input: "Set up this repo so a new developer can run it locally with the right Node version, Postgres, and Redis."
Output: chooses `bootstrap-and-onboarding`, recommends pinned runtime versions plus Compose for local services, and adds a verification path.

### Example 2: Containerized local standardization
Input: "Our team wants a devcontainer because everybody's local machine is different."
Output: chooses `containerized-dev-environment`, names which tooling should move into the container, and routes env-file details to `environment-setup`.

### Example 3: Drift diagnosis
Input: "The README says one thing, Docker says another, and new hires still can't run the app."
Output: chooses `setup-diagnosis-and-hardening`, compares setup artifacts, and identifies the authoritative source plus cleanup steps.

## Best practices
1. Optimize for a runnable repo, not maximal tooling sophistication.
2. Pick one canonical reproducibility story and make alternatives explicit.
3. Keep secrets/config guidance connected but not conflated with machine/runtime setup.
4. Add a verification step so onboarding is testable.
5. Name parity gaps instead of pretending containers solve everything.
6. Route narrower app-config questions to `environment-setup`.

## References
- [Scope boundaries](references/scope-boundaries.md)
- [Operating modes](references/operating-modes.md)
- [Docker Compose docs](https://docs.docker.com/compose/)
- [VS Code dev containers](https://code.visualstudio.com/docs/devcontainers/containers)
- [GitHub dev containers intro](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)