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、devcontainer、ハイブリッドなワークフローから選ぶ
• ランタイム／ツールのバージョンを固定し、マシン間の差異を抑える
• データベース、キャッシュ、キュー、検索などのローカル支援サービスをセットアップする
• ブートストラップコマンド、セットアップチェック、オンボーディングフローを設計する
• ローカルセットアップのドキュメント、スクリプト、コンテナ、実際のランタイム動作にずれが生じた原因を診断する
• ローカル環境と本番環境が同一であるかのように装うことなく、ローカル環境の同等性を高める

このスキルを使用しない場面

• 主なタスクがアプリレベルの .env 整理、環境変数スキーマの検証、またはフレームワークの環境変数ルールである場合 → environment-setup を使用してください
• 主なタスクが本番デプロイ、クラウドへの展開、または CI のオーケストレーションである場合 → deployment-automation を使用してください
• 主なタスクがホスト型インフラストラクチャのセキュリティレビューである場合 → security-best-practices と組み合わせてください
• より広範な環境に関する判断が不要で、パッケージを1つインストールするだけのタスクである場合 → 利用可能であれば、より対象を絞ったインストール／セットアップのスキルを使用してください

手順

ステップ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つ選ぶ

実行ごとに、モードを必ず1つ選んでください。

1. bootstrap-and-onboarding
   • コントリビューター向けに、初回実行の手順を整える必要がある場合に使用します。
2. toolchain-reproducibility
   • マシン間でランタイム、CLI、パッケージのバージョンに差異がある場合に使用します。
3. local-services-and-parity
   • ローカルの DB／キャッシュ／キュー／検索、またはアプリとサービスの構成が主な課題である場合に使用します。
4. containerized-dev-environment
   • Docker Compose、devcontainer、または Codespaces 形式のフローが主な手段となる場合に使用します。
5. setup-diagnosis-and-hardening
   • スクリプト、ドキュメント、コンテナ、実際の動作にずれが生じている場合に使用します。

ステップ3：問題を解決できる最小限の再現可能なスタックを選ぶ

次のルールに従ってください。

• リポジトリを確実に実行可能にできる、最小限のスタックを優先してください。
• リポジトリがシンプルな場合は、重いコンテナを導入する前に、ランタイム／バージョンの固定を行ってください。
• 支援サービスや、共有ローカル構成が重要な場合は、Docker Composeを使用してください。
• ホストネイティブな使いやすさよりも、エディター／ランタイムの標準化とオンボーディングの迅速化が重要な場合は、devcontainerを使用してください。
• ブートストラップスクリプト／Makefile／タスクランナーは補助として使用し、それだけを唯一の信頼できる情報源にしないでください。
• ローカル環境と本番環境が同等だと装わず、残る同等性の差異を明示してください。
• アプリレベルの環境変数ファイルの設計と検証の詳細は、このスキルを肥大化させずに 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)