OpenCode 讓終端編碼變成迴圈

OpenCode 把終端 AI coding 變成可規劃、可實作、可回滾、可分享的工作流。

我用一堆 AI coding 工具一陣子了，越用越確定一件事：很多時候不是模型不行，是外面那層 wrapper 很煩。你一開口，它就急著吐一大坨答案；你還沒想清楚要不要改，它已經開始動檔案。這種工具看起來很忙，實際上常常在製造收尾工作。我最怕的就是這種「先做再說」的助手，因為最後收爛攤子的還是我。

所以我看到 OpenCode 文件時，第一眼不是被什麼 AI agent 口號吸引，而是它把流程講得很像真的在做事：終端優先、Plan mode、Build mode、Undo、Share。這些詞很土，但土得對。因為真正麻煩的不是模型會不會寫，是它能不能被我控制在一個夠短的迴圈裡，讓我在它把 repo 弄髒之前先踩煞車。

我先看終端，不看花俏外殼

“OpenCode is an open source AI coding agent. It’s available as a terminal-based interface, desktop app, or IDE extension.”

這句話翻譯一下就是：它不是先把你關進一個漂亮介面，再叫你適應它；它是先回到終端，桌面版和 IDE 擴充只是其他入口。這點我很買單。對很多開發者來說，終端本來就是控制中心，尤其是我在 repo、腳本、git history 之間來回切的時候，根本不想再跳去另一個視窗裝模作樣地「和 AI 協作」。

我之前試過幾個 browser-based 的 coding assistant，前幾分鐘都很順，真的要做事就開始卡：不知道現在在哪個目錄、不知道 repo 狀態、不知道我剛剛 shell 裡做了什麼。結果它輸出的建議跟現場脫節，像是隔壁桌的人硬要指導我修電腦。OpenCode 把主戰場放在 terminal，這才像是把工具塞回開發者本來就在的位置。

實操上，我會先問自己三件事：它能不能在 terminal 跑？它能不能貼著 git？它能不能在 repo root 直接工作，而不是要我先開一個奇怪的工作區？如果這三個答案不漂亮，我通常就不會把它放進日常流程。因為一旦入口不對，後面每一步都會被摩擦感拖慢。

• 終端優先，通常比較容易接到既有 shell 流程。
• Repo-local context 比漂亮 UI 更重要。
• 少一次 app switch，就少一次放棄使用的藉口。

安裝流程故意做得無聊，反而比較像正經工具

OpenCode 文件把安裝寫得很直接：有安裝腳本，也有 npm、Bun、pnpm、Yarn、Homebrew、Arch、Chocolatey、Scoop、Mise、Docker 這些路線。Windows 也沒有假裝一切都美好，反而明講最好走 Windows Subsystem for Linux。這種寫法不漂亮，但很實際。

它給的安裝腳本是 curl -fsSL https://opencode.ai/install | bash，這種東西你一看就知道是給想快點上手的人；但它也沒有把其他安裝方式藏起來，反而把各種 package manager 版本都列出來。這代表它預設使用者不是只活在某一種環境，而是真的有人在 macOS、Linux、Windows、Docker 裡切來切去。這種現實感，我覺得比一堆「一鍵啟動」有誠意多了。

我以前踩過一個坑：工具在我主力機上跑得好好的，換到團隊另一台機器就開始出現奇怪問題，最後發現是安裝說明太含糊。只要 setup 變成猜謎，團隊 rollout 就會直接變 Slack 災難。OpenCode 至少把路鋪清楚了，沒有故意裝神秘。

實操寫法很簡單：如果你要把類似工具帶進團隊，先寫一條「唯一推薦」安裝路徑，再補上其他可行路徑，不要反過來。平台差異也要先講，像 Windows 這種就直接說明推薦 WSL。你越早把環境差異攤開，後面越少支援地獄。

• 先提供一條最快的安裝路徑。
• 再列出 package manager 選項給進階使用者。
• 平台限制要先講，不要等人踩雷才補文件。

模型選擇別裝成魔法，直接當設定就好

OpenCode 沒有假裝自己內建一顆萬能大腦。它要你接 LLM provider 的 API key，或者用它們提到的 OpenCode Zen，也就是一組經過驗證的模型清單。這種姿態我很喜歡，因為它沒有把模型層包成神祕黑盒子。

在 認證流程裡，你可以在 TUI 裡跑 /connect，選 opencode，登入、加 billing、把 API key 貼回去；也可以選其他 provider。意思很白話：你自己決定模型來源，自己承擔費用與限制。沒有什麼「AI 自動幫你選好」的假象。

翻譯一下就是，OpenCode 把模型當成配置，不是信仰。這很重要。因為我看過太多團隊把時間浪費在「哪個 model 最強」這種空話上，最後真正該問的其實是：哪個 provider 符合預算、延遲、政策和可用性。工具如果能讓你乾淨切換 backend，你就不用為了換模型重寫整個工作流。

我自己會把這件事看成責任切分：模型慢、貴、亂，就換 provider，不要把所有問題都怪到工具本身。這樣團隊也比較容易標準化。正式環境用一個 provider，個人測試用另一個，流程不會散掉。

實操寫法：把 model 設定寫成像一般 dependency 一樣。文件裡要有預設 provider、備援 provider、billing 影響。你如果是在做工具，也別把這層藏在「AI 魔法」後面，開發者要的是控制感，不是神秘感。

先初始化 repo，才像真的知道你在做哪個專案

OpenCode 的流程不是叫你直接丟 prompt 就開始亂寫。它先要你進到專案目錄、跑 opencode，再用 /init。這個指令會分析專案，然後在 repo root 建一個 AGENTS.md。文件還建議把這個檔案 commit 進 Git，讓工具能記住專案結構和 coding patterns。

這一步很對。因為真正的 codebase 不是白紙，它有慣例、有歷史包袱、有不成文規則。你如果每次都把 AI 當成剛認識 repo 的外包，它就會很自信地亂發明 helper、亂造抽象層，結果整個專案看起來像被不同人接力寫過。AGENTS.md 這種東西就是把規則從腦內記憶變成檔案，讓人和機器都看得到。

我之前在一個 backend 專案遇過類似狀況：assistant 一直生出和現有架構不合的 helper pattern，問題不是它不會寫，而是它根本沒有持久的專案上下文。你只靠聊天紀錄，過兩輪就忘光。把專案規則落地成檔案，至少可以讓它在每次開始工作時先讀一次，不用每回都重新猜。

實操寫法：如果你的工具有 bootstrap 步驟，就讓它產生一個可版本控制的 artifact。不要只依賴 ephemeral chat memory。把慣例寫進檔案，讓團隊能 review、diff、commit。這樣 assistant 的假設才不是黑箱。

我也喜歡文件明講要 commit AGENTS.md。這表示 assistant 不是站在版本控制外面指手畫腳，它本來就該被納入 repo 的治理裡。這點很務實。

Plan mode 不是裝樣子，是先把風險攔住

“OpenCode has a Plan mode that disables its ability to make changes and instead suggest how it’ll implement the feature.”

這句是整份文件裡我最想抄走的地方。Plan mode 的意思很簡單：先讓它講打算怎麼做，先不要碰檔案。對我來說，這不是多一個功能而已，這是把「設計」和「執行」分開。很多工具最煩的地方，就是它一邊想一邊改，像沒寫好草稿就直接上墨水。

文件還建議你把 OpenCode 當成 team 裡的 junior developer 來對話。這個比喻很準。你不會叫 junior dev 先亂改，再回頭看他是不是改對；你會先看他的理解、路線、邊界，再決定要不要讓他動手。AI coding 也是一樣。先看 plan，才知道它到底有沒有理解問題。

白話講，Plan mode 的價值就是讓我在 repo 被污染前先檢查方向。尤其是多檔案變更、資料流調整、或會影響使用者行為的改動，沒有 plan 真的很容易一不小心變成大重構。這種事我吃過虧，工具很會寫，但方向一歪，後面每一步都在補洞。

實操寫法：只要是跨檔案、動資料模型、碰 UI flow 的任務，我都強制先走 plan。給它目標、限制、例子，然後把 plan 當成 PR description 來審。plan 不順眼就先修 plan，不要急著進 build。這個習慣很救命。

• 多檔案變更先用 plan mode。
• 先要步驟，再要程式碼。
• 把 plan 當成 pull request 來看。

Build mode 要晚一點開，別讓衝動先動手

Plan 看完沒問題，再切回 Build mode，用 Tab 讓 OpenCode 開始改。文件也很老實：如果任務夠簡單，你可以直接跳過 plan，直上 build。這個設計我覺得平衡感剛好，不是每件事都要儀式感，但也不是每件事都適合盲改。

文件裡舉的例子其實很像真實需求：把 notes workflow 改成刪除時在資料庫標記 deleted，然後做一個最近刪除清單頁，還要能 restore 跟 permanent delete。這不是玩具 prompt，這是會真的碰到資料流、路由和 UI 的任務。它給的資訊夠多，能讓 agent 開工，但又不會細到把每一行都框死。

翻譯一下就是，OpenCode 預設你要像帶人一樣帶它。這個心態很重要。太模糊，它會自己補洞；太死板，它又只會照字面做。比較好的方式是先定義意圖，再留一點空間讓它處理機械性工作。

我自己的經驗是，大部分 AI coding 失敗都來自兩種情況：要嘛 prompt 太薄，要嘛使用者不肯讓工具完成一個完整回合。Plan / Build 的分離，剛好把這兩個問題都壓住。先審，再做；做完再看要不要下一輪。

實操寫法：簡單任務可以直接 build，複雜任務一定先 plan。只要牽涉 architecture、data、UX flow，我就不讓它跳步。這一條真的能少掉很多 cleanup。

Undo 和 Share 才是我在乎的安全帶

OpenCode 文件有 /undo、/redo、/share。乍看很小，但你真的做過幾輪 agentic coding，就知道這些不是附加功能，是保命機制。Undo 不是方便而已，是必需品。不能快速回退的工具，我不會把它當合作對象，只會當風險來源。

/undo 會回復上一組變更，還會把原始訊息還原，讓你可以重新試。/redo 則是把它拉回來。/share 會產生 conversation 連結並複製到剪貼簿，而且文件也說 conversation 預設不會被分享。這個預設很對，先私有，真的要給別人看再分享。

白話講，這代表 OpenCode 不只在意 code，也在意 code 旁邊那圈流程。Undo 支援試錯，Share 支援 review。兩個加起來，才像是能在團隊裡用的工具，不然很容易變成只有自己玩得懂的聊天機器。

我以前用過一些 AI 工具，分享對話麻煩到最後只能貼截圖到 Slack，活像回到十年前。這很荒謬。既然 assistant 真的在幫我做事，我就需要一個乾淨的方式把 thread 給同事看，或之後自己回來查。OpenCode 至少把這件事想到了。

實操寫法：每個 agent workflow 都要有 undo。要快、要明顯、要能回頭。只要 team 內有人需要 review，還要有可分享的 artifact，不要逼大家自己拼 prompt chain。

可抄的模板

# OpenCode 終端 AI coding 工作流模板（可直接貼進 README 或團隊 wiki）

## 1) 安裝
# 先選一條主路徑，文件只保留一個預設。
# 例：
# curl -fsSL https://opencode.ai/install | bash
# 或改用你團隊慣用的 package manager。

## 2) 配置 provider
# 在 OpenCode 裡跑 /connect
# 選 provider
# 貼上 API key
# 如果團隊有標準 provider，直接寫死在文件裡

## 3) 初始化專案
cd /path/to/project
opencode
/init

# 把生成的 AGENTS.md commit 進 Git。
# 讓 repo 規則成為版本控制的一部分。

## 4) 先要 plan，不要先改檔
# 用 Plan mode 處理多檔案、資料流、架構相關任務。
# 提示詞要包含：
# - 目標
# - 影響範圍
# - 限制條件
# - 預期行為範例

範例 prompt：
"我們要加 soft-delete 支援給 notes。
刪除時不要真的刪除，改成在資料庫標記 deleted。
再新增一個最近刪除頁面。
那個頁面要能 restore 和 permanent delete。
請先只給我 implementation plan，不要改檔。"

## 5) 審 plan
# 檢查：
# - data model 變更
# - route 變更
# - UI 變更
# - migration 需求
# - rollback 風險

## 6) 確認後才 build
# 切回 Build mode。
# 讓 agent 開始改。
# 一次只做一個明確任務。

## 7) 出事就 undo
# 如果結果不對：
# /undo
# 修正 prompt
# 再跑一次

## 8) 需要 review 就 share
# thread 有價值時：
# /share
# 把連結貼到 PR、ticket 或 chat

## 我常用的提示詞模式
# 普通版：
# "Implement X in the same style as Y, using Z constraints."
# 更好版：
# "First explain the plan, then wait for approval before editing."
# 最好版：
# "Use the repo patterns in AGENTS.md and keep changes minimal."

## 團隊規則
# - AGENTS.md 要進版控
# - 危險改動先用 plan mode
# - 優先可回滾的修改
# - 有價值的 thread 要能分享
# - 把 agent 當 junior dev，不要當魔法盒子

這就是我會真的拿去用的版本。順序很直白：安裝、設定、初始化、先 plan、再 build、必要時 undo、需要 review 就 share。沒有花俏包裝，只有能控制風險的流程。

我對 OpenCode 的結論很簡單：它最強的地方，不是它會不會寫，而是它把 AI coding 變成一個我看得懂、踩得住煞車的 loop。這點比任何宣傳詞都實在。

原始來源是 https://opencode.ai/docs/，另外我也參考了 https://opencode.ai/auth、https://learn.microsoft.com/windows/wsl/ 和 https://opencode.ai/。文件裡的流程、指令與安裝資訊來自原始來源；我拆解成台灣開發者比較好直接上手的版本，模板和判斷是我自己整理的。