system-environment-setup（系统环境设置）

System & Environment Setup

Use this skill as the repository's canonical broader environment-setup anchor.

The job is to make a project runnable and repeatable across developer machines and environments. That usually includes some mix of:

• runtime/tool version pinning,
• local services and containers,
• bootstrapping scripts,
• onboarding steps,
• local-prod parity tradeoffs,
• secrets/config handoff boundaries,
• setup diagnosis when automation drifts.

Read references/operating-modes.md and references/scope-boundaries.md before unusual cases or when deciding whether the task belongs here or in environment-setup.

If the user mainly needs:

• .env structure, env precedence, validation, or framework-specific app config → route to environment-setup
• CI/CD pipelines and hosted deployment automation → route to deployment-automation or vercel-deploy
• security policy and secret-store architecture → pair with security-best-practices
• project slicing / onboarding checklist ownership → pair with task-planning

When to use this skill

• Make a repo runnable on a fresh machine with consistent tooling
• Standardize local dev setup across multiple contributors
• Choose between local-host, Docker Compose, devcontainers, or hybrid workflows
• Pin runtime/tool versions and reduce cross-machine drift
• Set up local supporting services like databases, caches, queues, or search
• Design bootstrap commands, setup checks, or onboarding flows
• Diagnose why local setup docs, scripts, containers, and actual runtime behavior have drifted apart
• Improve local parity without pretending local and production are identical

When not to use this skill

• The main task is app-level .env organization, env schema validation, or framework env rules → use environment-setup
• The main task is production deployment, cloud rollout, or CI orchestration → use deployment-automation
• The main task is hosted infrastructure security review → pair with security-best-practices
• The task is just one package install with no broader environment decision surface → use a narrower install/setup skill when available

Instructions

Step 1: Classify the setup surface

Normalize the request into this intake first:

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

If the request is ambiguous, prefer the broadest runnable repo interpretation and state the assumption.

Step 2: Choose one primary operating mode

Pick exactly one mode for the run:

1. bootstrap-and-onboarding

- Use when the repo needs a clean first-run path for contributors.

1. toolchain-reproducibility

- Use when runtimes, CLIs, or package versions drift between machines.

1. local-services-and-parity

- Use when local DB/cache/queue/search or app-plus-service topology is the main challenge.

1. containerized-dev-environment

- Use when Docker Compose, devcontainers, or Codespaces-style flows are the main lever.

1. setup-diagnosis-and-hardening

- Use when scripts, docs, containers, and actual behavior have drifted apart.

Step 3: Pick the smallest reproducibility stack that solves the problem

Use these rules:

• Prefer the smallest stack that makes the repo reliably runnable.
• Use runtime/version pinning before introducing heavier containers if the repo is simple.
• Use Docker Compose when supporting services or shared local topology matter.
• Use devcontainers when editor/runtime standardization and onboarding speed matter more than host-native ergonomics.
• Keep bootstrap scripts / Makefiles / task runners as glue, not the only source of truth.
• Do not pretend local equals production; name the remaining parity gaps explicitly.
• Route app-level env file design and validation details to environment-setup instead of bloating this skill.

Step 4: Build the environment plan

Return this exact structure:

# 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

...

## Why this is the right level of setup

- ...
- ...

## Parity gaps to acknowledge

- ...
- ...

## Watch-outs

- ...
- ...

## Adjacent handoff

- Use `environment-setup` for...
- Use `deployment-automation` for...
- Use `security-best-practices` for...

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
• Operating modes
• Docker Compose docs
• VS Code dev containers
• GitHub dev containers intro