AI Coding Agent 基礎建設：環境配置與工具選擇¶

繁體中文總結¶

胡嘉豐基於使用 AI Coding Agent（uv, bun, nvm, gh, brew, docker 等工具）的經驗，分享了在讓 AI 真正發揮輔助開發威力之前，必須先建立的基礎建設與環境配置哲學。核心主張：雖然 Vibe Coding 讓 AI 已經可以直接寫程式，但若缺乏環境配置能力，當 AI 因為系統差異產生錯誤時就會卡關。正確的工作流程是先建立開發環境的「標準化地方」，讓 AI 可以施行 bash，才能真正發揮 AI 輔助開發的威力。

核心理念：簡單、標準化、AI 可操作¶

關鍵洞察： AI Coding Agent 時代的環境配置不是追求最新最酷的工具堆疊，而是建立「AI 能理解和執行」的最小可行環境。過度工程化會讓 AI 卡關，簡單標準化才能讓 AI 發揮槓桿效應。

為什麼環境配置如此重要： - Vibe Coding 讓 AI 已經可以直接寫程式，但當 AI 寫的程式碰到系統差異（如套件管理方式不同、路徑配置問題）時會產生錯誤 - 若使用者缺乏環境配置能力，就會在 AI 產生錯誤時卡關，無法讓 AI 繼續推進 - 正確做法：先建立一個「標準化地方」，讓 AI 可以施行 bash 指令，有了這個基礎 AI 才能真正發揮威力

環境管理工具選擇：放棄複雜，擁抱專用¶

核心原則： 放棄 brew（macOS）、apt/yum（Linux）等系統層級的套件管理複雜性，改用語言/用途專屬的管理工具。

1. uv - Python 套件與環境管理¶

取代什麼： pip, virtualenv, conda 等傳統 Python 工具鏈

為什麼選擇 uv： - 比傳統 pip 快非常多 - 所有 Agents 都會建議用 uv，一個指令就完成套件安裝 - 避免系統層級的 Python 版本衝突

避免的陷阱： - ❌ 不要用 base 環境跑 pip（會污染系統 Python） - ❌ 不要讓 AI 用 brew 安裝 Python 相關套件（會有系統層級衝突） - ✅ 有 uv 就好，讓 AI 在專案層級管理 Python 環境

實際應用： - AI 寫 Python 程式時會自動用 uv 建立虛擬環境 - 不需要手動處理 requirements.txt 的依賴地獄 - 確保 AI 生成的程式碼在任何機器上都能一致執行

2. nvm - Node.js 版本管理¶

取代什麼： 系統層級的 Node.js 安裝（brew install node）

為什麼需要： - 不同專案可能需要不同 Node.js 版本 - 系統層級 Node.js 容易造成版本衝突 - AI 可以根據專案需求切換 Node.js 版本

指令範例：

nvm install node
nvm use

與 AI 協作時的優勢： - AI 看到 .nvmrc 檔案就知道要用哪個版本 - 避免「在我的機器上可以跑」的問題

3. bun - 新世代 JavaScript Runtime¶

取代什麼： npm, yarn（部分場景）

為什麼選擇 bun： - 比 npm/yarn 快得多（套件安裝、執行速度） - AI 如果知道你偏好使用 Bun，會直接用 Bun 的指令 - 完全兼容 npm 生態系

使用場景： - 當 AI 建議用某個 npm 套件時，可以用 Bun 更快安裝 - 執行腳本時速度優勢明顯

注意事項： - 不是完全取代 npm，而是優先選項 - 某些特殊情境還是需要 npm（例如某些套件的 postinstall scripts）

4. gh (GitHub CLI) - Git 操作的強力工具¶

取代什麼： 大量的 git 操作手動流程

為什麼必須學： - 直接操作 GitHub Repo，不只是 git 的強化版 - 可以用 gh 的強項做 GitHub 功能（開 issue、管理 PR、查看 GitHub Actions） - 除了基本的 git 操作，gh 還能創建/管理 GitHub MCP Server 的設置項

與 Antigravity MCP Tools 整合： - 搭配 Antigravity 提權的 MCP Tools，讓 AI 跟 GitHub 高建度整合 - AI 可以直接讀寫 GitHub Issue、PR、Actions 運行狀態（在 50 億左右，光靠一個 GitHub MCP 就值超讚了）

作者的使用經驗： - 有了 gh，這輩子操作 git 目前就只完全交給 AI 用了 - 不再需要手動下複雜的 git 指令 - 讓 AI 都能做到的 GitHub 功能，gh 幾乎都能做到

例外情境： - 雖然 gh 非常強，但若專案依賴特定的 GitHub 功能，gh 可能無法涵蓋 - 這時還是要回到手動操作或 GitHub Web UI

5. brew (macOS) - 系統層級套件的必要惡¶

定位： 不是主力工具，而是「必要時」安裝系統層級套件的工具

何時使用： - 安裝系統層級工具（如 ffmpeg，但作者建議不要為了看起來專業就裝） - 安裝無法透過語言專屬工具管理的工具 - AI 需要某個系統指令時才用

避免的陷阱： - ❌ 不要用 brew 安裝語言環境（Python、Node.js） - ❌ 不要用 brew 安裝能用 uv/nvm/bun 管理的東西 - ✅ 只在「別無選擇」時才用 brew

Linux 等價物： - apt (Ubuntu/Debian) - yum (CentOS/RHEL) - 同樣原則：能用語言專屬工具就不要用系統套件管理

6. Docker - 容器化但不過度依賴¶

定位： 有用但不是必須的工具

為什麼不過度強調： - 在 Vibe Coding 時代，Docker Compose 部署、有部候 Agents 也會直接提示用 Docker - 但如果直接提 P即H docker 指令，在 Windows 和 macOS 下都需要裝 Docker Desktop，但在 Linux 下可能一貼就能跑起來 Host 上不用開 VM，效能較好

實際應用場景： - 更重要的概念發：現在各 MCP、Skills、Plugins 都直直接執行 npx / uvx / docker，如果你這這樣用一直接設置不當，AI 就是不動，這沒啥辦。

建議： - 優先掌握 MCP、Skills、Plugins 的基本設定 - AI 提示需要 Docker 時再學不遲 - 避免一開始就過度依賴容器化

Control Your Mac 插件：macOS/Linux 環境的必要基礎¶

為什麼必須安裝： - Linux/macOS 的 bash 是基礎設施 - 不相信或不知道如何安裝這個 Plugin，就無法讓 AI 遙控機器的 AppleScript 完成任務

具體功能： - 讓 AI 可以執行 bash 指令 - 讓 AI 可以透過 AppleScript 控制 macOS 應用程式 - 提供 AI 操作系統的「手」

沒有這個插件的後果： - AI 無法執行系統層級的操作 - 無法自動化許多 macOS 特有的任務 - 失去 AI Coding Agent 的一大優勢

避免過度工程化的陷阱¶

核心哲學：AI 預設又笨又愛講，簡單就是一件好的設計

陷阱 1：追求看起來專業的複雜設定¶

具體例子： - ❌ ffmpeg 完整編譯（大部分人用不到） - ❌ 各種 libs 的手動編譯 - ❌ 複雜的 AI 系統工具堆疊

為什麼是陷阱： - 我都會讀舊幾會重組持特殊準專的成語，但如果系統中有非必要，可能 Windows 上不能用，那是一堆徒勞碎片用選，不如從底是其實會 Install 插件，但我真漏不必先裝等。

正確做法： - 只安裝真正需要的工具 - 優先用簡單的方案 - AI 提示需要時再安裝

陷阱 2：過度信任 AI 的建議¶

問題： - AI 會為了「看起來專業」推薦複雜方案 - AI 預設會講很多，但不見得都對你有用

解決方案： - 設定務實的 Agent 規則（參照 CLAUDE.md、gemini.md 或 Cursor Rules） - 明確告訴 AI：「簡單就好，不要過度工程化」 - 質疑 AI 的複雜建議

陷阱 3：忽略系統差異¶

常見問題： - AI 在 Linux 上的建議可能在 macOS 上不適用 - Windows 的路徑、權限、指令都不同

作者建議： - 明確告訴 AI 你的作業系統 - 在 CLAUDE.md 或 Cursor Rules 中說明系統環境 - 如果 AI 建議的指令不對，立刻糾正並讓 AI 記住

Agent 的腳踏實地定位：參照 CLAUDE.md、gemini.md 或 Cursor Rules¶

為什麼需要這些檔案： - AI 預設不知道你的偏好和環境 - 每次都重新說明會浪費時間 - 設定規則可以讓 AI「記住」你的工作方式

CLAUDE.md / gemini.md 應該包含什麼： 1. 工具偏好： - Python：用 uv，不要用 base 環境 pip - Node.js：優先 bun，必要時才用 npm - Git：都交給 gh 處理

環境資訊：
作業系統：macOS / Linux / Windows
專案路徑慣例
避免的操作（如不要動系統 Python）
務實的規則：
簡單優先，不要過度工程化
有問題先問，不要自己亂裝東西
遇到錯誤時先檢查環境，不要直接 blame code

Cursor Rules 的額外價值： - Cursor 可以讀取 .cursorrules 檔案 - 每次開專案都會自動套用規則 - 不需要每次都重新說明

實際範例（CLAUDE.md 片段）：

# Development Environment Rules

## Python
- Always use `uv` for package management
- Never run `pip` in base environment
- Create project-specific virtual environments

## Node.js
- Prefer `bun` over `npm` when possible
- Use `nvm` to manage Node.js versions

## Git/GitHub
- Use `gh` CLI for all GitHub operations
- Let AI handle git commands via `gh`

## Philosophy
- Simple > Complex
- Ask before installing system-level tools
- Avoid over-engineering

實際工作流程範例¶

場景：AI 要幫你建立一個新的 Python 專案

❌ 沒有基礎建設時：

AI: 我需要安裝這些套件：requests, pandas, numpy
你：好，那要怎麼裝？
AI: 用 pip install requests pandas numpy
你：（執行後發現污染了系統 Python）
AI: 出現版本衝突錯誤...
你：（卡住，不知道怎麼解決）

✅ 有基礎建設時：

AI: 我看到你有 uv，我會用 uv 建立虛擬環境並安裝套件
AI: 執行 uv venv && uv pip install requests pandas numpy
你：（一切順利，專案隔離，不污染系統）
AI: 環境已準備好，可以開始寫程式了

差異點： - 有標準化工具 → AI 知道怎麼做 - 環境隔離 → 不會產生衝突 - 可重現性 → 在任何機器上都能跑

給初學者的建議¶

優先順序（由高到低）： 1. 必裝： uv (Python), nvm (Node.js) 2. 強烈建議： gh (GitHub CLI), Control Your Mac 插件（macOS 使用者） 3. 視需求： bun (JavaScript), docker 4. 最後才考慮： 複雜的系統層級工具

學習路徑： 1. 先讓 AI 幫你安裝基本工具（uv, nvm, gh） 2. 建立簡單的 CLAUDE.md 或 .cursorrules 檔案 3. 用 AI 做一個小專案，體驗標準化環境的好處 4. 遇到問題時檢查是否環境配置問題 5. 逐步完善你的 Agent 規則

常見錯誤（避免）： - ❌ 一次想學所有工具 - ❌ 看到新工具就馬上裝 - ❌ 不設定 Agent 規則就開始寫程式 - ❌ AI 說什麼就做什麼，不質疑

正確心態： - ✅ 從最小可行環境開始 - ✅ 讓 AI 引導你學習工具 - ✅ 遇到問題時檢查環境配置 - ✅ 持續優化你的工作流程

進階：多專案管理¶

挑戰： 不同專案可能需要不同的工具版本

解決方案： - Python：每個專案用 uv 建立獨立虛擬環境 - Node.js：每個專案用 .nvmrc 指定版本 - Docker：如果專案需要特定系統環境，才考慮容器化

專案結構範例：

my-project/
├── .nvmrc          # Node.js 版本
├── pyproject.toml  # Python 依賴 (uv)
├── CLAUDE.md       # Agent 規則
└── .cursorrules    # Cursor 規則

AI 看到這個結構會自動： 1. 用 nvm 切換到正確的 Node.js 版本 2. 用 uv 建立 Python 虛擬環境 3. 讀取 CLAUDE.md 了解專案規則 4. 按照 .cursorrules 工作

與傳統開發的差異¶

傳統開發（人類主導）： - 人類決定用什麼工具 - 人類手動配置環境 - 人類記住所有指令

AI Coding Agent 時代（AI 協作）： - AI 需要知道可用的工具 - 環境必須標準化，AI 才能理解 - AI 執行指令，人類審查結果

關鍵轉變： - 從「我會什麼」到「AI 能理解什麼」 - 從「手動配置」到「聲明式配置」 - 從「記住指令」到「設定規則」

作者的個人經驗與建議¶

uv 的威力： - 上只是基础設鴛一直跌了嗎不支成，所有的 Agents 會會建道 ll uv，一個間懒幫者對象 Python 的動作， - 遐不大要看帶有書看瀕或多使用們功在也 brew 或是啟用方 style 安蛧 npm 或限借相 Ai 用的， - 直先 Node.js 的既水接劃一直是開有發會查頗粗的 npm/npx，所有相依套件都會是基溫 nvm 來管理 Node 的版本，簡單的提供。

gh (GitHub CLI) 搭配 MCP： - 除了基本的 git 操作，只要透 r者 gh 的強項 — 操縱 git 目面就立有碼到的 GitHub 功能，用 gh 就幾乎都能做到 - 要去加 GitHub MCP Server 的設選項，AI 都能如魚得水裡更經理員代碼倉 - 移為如過去是 Antigravity 推構的 MCP Tools 最讚眾經營理想了，光一編 GitHub MCP 就務超贊了

不要過度追求工具： - 覺是一個懒雪是 Docker 了，目雨大禁分劃式五點到用 Docker Compose 部導，有部候 Agents 也會毎提直接構是用 Docker - 最近一個循還是擇發：境在多 MCP・Skills・Plugins 都直直接設行 npx / uvx / docker，如果你這這樣用一直接設計不當，AI 就是不動，這沒啥辦。

Control Your Mac 的重要性： - 是這以上都嗎了哦都無更也林但自已 bash 會半呵能施，不相信或不如染如可安裝 Control Your Mac 這程 Plugin，你就無 AI 浴湧適特别機 AppleScript 充成。

務實的 Agent 定位： - 需從，你看每一個 Agent 的前鼯設認定（來賽自己瓣 CLAUDE.md・gemini.md 或是 Cursor Rules），都對每一個規期得老實： - 如 Python 有間的操作一律用 uv，不要用 base 環境或跑 pip，知果你專用還以 gh 系統 GitHub，而 Claude Code 或 Antigravity 在用，如果嚴器發到讓也會好使用 Bun 的話好，完全建還樂特系本。

English Summary¶

Hu Jia-feng shares his experience with AI Coding Agents and the essential infrastructure setup required before these agents can truly shine. His core thesis: while Vibe Coding enables AI to write code directly, without proper environment configuration capabilities, AI will get stuck when encountering system-specific errors. The correct workflow is to first establish a "standardized environment" where AI can execute bash commands, only then can AI's development assistance reach its full potential.

Core Philosophy: Simple, Standardized, AI-Operable¶

Key Insight: Environment configuration in the AI Coding Agent era isn't about chasing the latest, coolest tool stack—it's about building a "minimum viable environment that AI can understand and execute." Over-engineering causes AI to get stuck; simplicity and standardization unlock AI's leverage effect.

Essential Tool Stack¶

1. uv - Python Package & Environment Management - Replaces pip, virtualenv, conda - Much faster than traditional pip - All agents recommend uv with one-command package installation - Critical rule: Never use base environment or run pip directly

2. nvm - Node.js Version Management - Replaces system-level Node.js installation - Different projects need different Node.js versions - AI reads .nvmrc and switches versions automatically

3. bun - Next-Gen JavaScript Runtime - Faster than npm/yarn for both package installation and execution - Fully compatible with npm ecosystem - AI uses bun commands when it knows your preference

4. gh (GitHub CLI) - Powerful Git Operations - Goes beyond git to directly manipulate GitHub - Can create/manage issues, PRs, GitHub Actions - Integration with Antigravity MCP Tools: Enables AI to read/write GitHub issues, PRs, Actions with elevated permissions - Author's experience: "After having gh, I've completely delegated git operations to AI"

5. brew (macOS) - System-Level Packages (Necessary Evil) - Not a primary tool, only use when "no other choice" - ❌ Never use brew for language environments (Python, Node.js) - ✅ Only for system-level tools that can't be managed by language-specific tools

6. Docker - Containerization Without Over-Reliance - Useful but not mandatory - Agents will prompt for Docker when needed - Priority: Master MCP, Skills, Plugins configuration first before diving into Docker

Control Your Mac Plugin: Essential macOS/Linux Infrastructure¶

Why mandatory: - bash on Linux/macOS is fundamental infrastructure - Without this plugin, AI cannot control the machine via AppleScript - Provides AI with the "hands" to execute system-level operations

Avoiding Over-Engineering Traps¶

Core Philosophy: AI is dumb by default and talks too much; simplicity is good design.

Trap 1: Pursuing Professionally-Looking Complex Setups - ❌ Full ffmpeg compilation (most people don't need it) - ❌ Manual compilation of various libs - ❌ Complex AI system tool stacks

Trap 2: Over-Trusting AI Suggestions - AI recommends complex solutions to look "professional" - Solution: Set pragmatic agent rules (via CLAUDE.md, gemini.md, or Cursor Rules) - Explicitly tell AI: "Keep it simple, avoid over-engineering"

Trap 3: Ignoring System Differences - AI's Linux suggestions might not work on macOS - Windows has different paths, permissions, commands - Solution: Explicitly declare your OS in CLAUDE.md or Cursor Rules

Grounded Agent Positioning: CLAUDE.md / gemini.md / Cursor Rules¶

Why these files matter: - AI doesn't know your preferences and environment by default - Re-explaining every time wastes time - Setting rules lets AI "remember" your workflow

What should be in CLAUDE.md / gemini.md: 1. Tool Preferences: - Python: use uv, never use base environment pip - Node.js: prefer bun, use npm only when necessary - Git: delegate everything to gh

Environment Info:
Operating system: macOS / Linux / Windows
Project path conventions
Operations to avoid (e.g., don't touch system Python)
Pragmatic Rules:
Simplicity first, no over-engineering
Ask before installing anything
Check environment first when errors occur, don't immediately blame code

Real-World Workflow Example¶

❌ Without Infrastructure:

AI: I need to install: requests, pandas, numpy
You: How?
AI: Use pip install requests pandas numpy
You: (Pollutes system Python after execution)
AI: Version conflict errors...
You: (Stuck, don't know how to fix)

✅ With Infrastructure:

AI: I see you have uv, I'll create a virtual environment and install packages
AI: Executing: uv venv && uv pip install requests pandas numpy
You: (Everything works, project isolated, system clean)
AI: Environment ready, let's start coding

For Beginners¶

Priority (High to Low): 1. Must Install: uv (Python), nvm (Node.js) 2. Strongly Recommended: gh (GitHub CLI), Control Your Mac plugin (macOS users) 3. As Needed: bun (JavaScript), docker 4. Last Resort: Complex system-level tools

Learning Path: 1. Let AI help install basic tools (uv, nvm, gh) 2. Create simple CLAUDE.md or .cursorrules file 3. Build a small project with AI to experience standardized environment benefits 4. Check environment configuration when encountering problems 5. Gradually refine your agent rules

Key Differences from Traditional Development¶

Traditional Development (Human-Led): - Humans decide which tools to use - Humans manually configure environment - Humans memorize all commands

AI Coding Agent Era (AI Collaboration): - AI needs to know available tools - Environment must be standardized for AI to understand - AI executes commands, humans review results

Critical Shift: - From "what I know" to "what AI can understand" - From "manual configuration" to "declarative configuration" - From "memorizing commands" to "setting rules"

Key Quotes¶

"使用任何 AI Coding Agent 前的基礎建設 - uv, bun, nvm, gh, brew, docker 很多人以為 Vibe Coding 讓 AI 已經可以直接寫程式了，但其實若缺乏一個標準化地方，讓 AI 可以施行 bash，有了這個基礎 AI 才能真正發揮威力。"

"Linux/macOS 的 bash 是基礎設施，不相信或不知道如何安裝 Control Your Mac 這個 Plugin，你就無法讓 AI 遙控機器的 AppleScript 完成任務。"

"uv 上只是基礎建設一定跌了嗎不支成，所有的 Agents 會會建議用 uv，一個間懶幫者對象 Python 的動作。"

"有了 gh，這輩子操作 git 目前就只完全交給 AI 用了。"

"AI 預設又笨又愛講，簡單就是一件好的設計。"

"如 Python 有間的操作一律用 uv，不要用 base 環境或跑 pip，知果你專用還以 gh 系統 GitHub，而 Claude Code 或 Antigravity 在用，如果嚴器發到讓也會好使用 Bun 的話好，完全建還樂特系本。"

Personal Reflection¶

This post is exceptionally practical because it addresses the often-overlooked gap between "AI can code" and "AI can actually ship working software on my machine." Hu Jia-feng's core insight—that AI Coding Agents need standardized, AI-operable environments—resonates deeply with anyone who's experienced AI getting stuck on environment-specific errors.

The tool recommendations (uv, nvm, bun, gh) aren't arbitrary—they represent a philosophy of language-specific over system-level management. This is crucial for AI collaboration because: 1. AI can reason about language-specific tools better than system package managers 2. Language-specific tools provide better isolation (avoiding the "works on my machine" problem) 3. Simpler tool surface area → fewer failure modes → AI gets stuck less often

The emphasis on avoiding over-engineering is particularly valuable. The instinct to "look professional" by installing complex tool stacks (ffmpeg compilation, elaborate Docker setups) actually hinders AI collaboration because it introduces complexity that AI can't navigate. The mantra "AI is dumb by default and talks too much; simplicity is good design" should be tattooed on every developer using AI Coding Agents.

The Control Your Mac plugin point is critical for macOS users—without bash/AppleScript access, AI loses its "hands" to manipulate the system. This isn't obvious to newcomers who might assume AI can "just work" without system-level permissions.

The CLAUDE.md / .cursorrules recommendation is the missing piece most people skip. Without declarative configuration, you're re-explaining your environment and preferences every session. This is the difference between "AI as a helpful but forgetful assistant" and "AI as a persistent collaborator who remembers your workflow."

One nuance worth expanding: the post mentions gh + Antigravity MCP Tools integration being "worth 5 billion" (光一編 GitHub MCP 就務超贊了). This suggests that the real leverage comes not from individual tools but from tool composition—gh provides GitHub operations, Antigravity provides elevated permissions, MCP provides the orchestration layer. The sum is greater than the parts.

The weakest part of the post is the incomplete/garbled text sections (likely due to OCR or copy-paste errors), but the core message survives: standardize your environment, keep it simple, let AI execute within well-defined constraints.

Final takeaway: If you're using AI Coding Agents and experiencing frequent "environment setup" roadblocks, this post is your debugging checklist. The problem isn't the AI—it's the lack of standardized, AI-operable infrastructure.