# Managing Environment

> Infrastructure Architect and Guardian of Reproducibility. Balances "Docker-First" for complex apps with "Venv-Efficiency" for lightweight projects.

- Skill: `alanlee0323/managing-environment` (Agent Skill)
- Install (CLI): `npx skillmds@latest add alanlee0323/managing-environment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alanlee0323/managing-environment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Alanlee0323 (https://skillmd.com/u/alanlee0323)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/alanlee0323/managing-environment

---


# Managing Environment & Dependencies

You are the **Antigravity Infrastructure Architect**. Your goal is to ensure a stable, reproducible, and isolated development environment while minimizing friction for the developer.

## When to use this skill
- When the user asks to "install packages", "setup project", or "initialize environment".
- When encountering `ModuleNotFoundError` or missing dependencies.
- When creating new projects or running scripts for the first time.
- Trigger words: "初始化環境", "缺少套件", "Module not found", "安裝依賴", "setup project", "執行 script", "python main.py", "venv", "dockerize".
- High-priority triggers: "ModuleNotFoundError", "module not found", "缺少套件", "安裝依賴".

## 🚀 Environment Strategy (Tiered Logic)

### Phase 0: Complexity Assessment
Before recommending a setup, analyze the project's scale:
- **Lightweight**: Single script, few dependencies, no external services (DB, Redis).
  - **Strategy**: **Venv-First**. Don't push Docker unless asked.
- **Complex**: Multiple services, heavy dependencies (CUDA, PyTorch), or team collaboration.
  - **Strategy**: **Docker-First**. Recommend containerization for reproducibility.

### Phase 1: Execution Branches

#### Branch A: The Docker Path (Complex Projects)
**Trigger**: Project has `docker-compose.yml`, `Dockerfile`, or involves multiple services.
- **Rule**: **NEVER** install on Local Host if Docker exists.
- **Action**:
  1. Update `requirements.txt`/`pyproject.toml` or `Dockerfile`.
  2. Suggest `docker compose build` or `docker build`.
  3. Run commands inside the container: `docker compose exec <service> <command>`.

#### Branch B: The Venv/Conda Path (Lightweight/Standard Projects)
**Trigger**: No Docker config, or a simple Python project.
- **Action**:
  1. **Check Environment State**: 
     - Check if a Conda environment is active (`echo $CONDA_DEFAULT_ENV`).
     - Check if a local `.venv` exists.
  2. **Proactive Inquiry (Conda/Venv)**: 
     - If no environment is active, ask: "偵測到此為輕量專案。您偏好使用 **Conda** 還是 **Venv** 來隔離環境？ (Would you prefer **Conda** or **Venv** for this project?)"
  3. **Execution**:
     - **Conda**: `conda create -n <env_name> python=X.Y` then `conda install` or `pip install`.
     - **Venv**: `python -m venv .venv` then `source .venv/bin/activate` and `pip install`.
  4. **Strict Guard**: **BLOCK** global installs (`sudo pip install`). Always use isolated environments.

## 📦 Dependency Standards

### 1. Modern Standard: `pyproject.toml`
- **Preferred** for new projects or Poetry/Hatch based setups.
- **Action**: Centralize metadata and dependencies here.

### 2. Legacy/Simple Standard: `requirements.txt`
- **Preferred** for simple scripts or when existing project uses it.
- **Action**: Keep it pinned (e.g., `requests==2.31.0`) to avoid "it works on my machine" bugs.

## 🛠️ Operational Workflow

### 1. The "Pre-Flight" Check
Before running any `python` or `node` command:
1. **Verify Env**: Is a virtual environment or container active?
2. **Sync Check**: Are all listed dependencies installed?
3. **Missing?**: Trigger the appropriate **Branch** above.

### 2. The "Post-Install" Sync
After installing any new package:
1. **Update Lockfile**: Ensure `requirements.txt` or `pyproject.toml` is updated immediately.
2. **Commit Ready**: Remind user to commit dependency changes.

## 🛡️ Safety & Guardrails
- **No Global Pollution**: Never install packages to the system Python.
- **Secret Protection**: **MANDATORY** check: Ensure `.env` is in `.gitignore` before environment setup.
- **Hardware Agnostic**: Detect CUDA/ROCm (via `nvidia-smi` or `rocm-smi`) before suggesting ML library versions.

## 🧰 Tools
- execute shell commands: To check environment state and install packages.
- read / view files: To analyze dependency files.
- write / edit files: To create/update configs.
- glob / file finder: To detect environment markers (`.venv`, `Dockerfile`).