前言
我從來沒有使用過 Claude Code或是Codex，太貴了。訂閱一個GPT的價格，完全可以同時訂閱三家頂級的國產(chǎn)模型。
所以我一直在用開源方案構(gòu)建自己的 AI 編碼環(huán)境：以 OpenCode 為基礎(chǔ)，配合 OpenSpec（SDD）。
我的想法是：如果清楚自己在做什么，并且是個經(jīng)驗(yàn)豐富的開發(fā)者，那么像 Qwen3.6-Plus、Kimi-k2.5、GLM-5.1、Minimax M2.7 這些前沿開源模型（即便他們在各種評測中不及最新的GPT和opus），完全可以 handle 日常編碼任務(wù)。
開源軟件還有巨大的社區(qū)，可以針對不同模型調(diào)優(yōu)系統(tǒng)提示和模型參數(shù)，讓開源模型發(fā)揮出最大潛力。
一、安裝與配置OpenCode
1.1 安裝 OpenCode
相比于Claude Code和大多數(shù)只有一個命令行界面的編碼Agent，OpenCode 提供了帶圖形界面的桌面應(yīng)用，這為每一次Code Review提供了極大的方便。
配置模型提供商
打開設(shè)置窗口，選擇 “提供商”，拉到底部有“選擇更多提供商”，就像我使用的模型商，在輸入框里輸入minimax，就可以看到他們家的Coding Plan選項(xiàng)，然后輸入你的ApiKey就接入完成了。
這里的配置實(shí)際上被寫入到了~/.local/share/opencode/auth.json這個文件中，里面可以看到我的所有模型提供商的key。
啟用 Workspaces
我們在工作中的一個痛點(diǎn)是，開發(fā)者經(jīng)常會收到零碎又緊急的需求。
傳統(tǒng)的做法是我們臨時保存當(dāng)前分支，然后切一個 fix/some-bug 分支出來修改后立即提交到master上去。
高級且更方便一點(diǎn)的做法是可以使用 git worktree 切一個新的 worktree，并在里面開發(fā)。
Opencode 原生支持 worktree 功能，這個功能叫做 "工作區(qū)"。
啟用方式：在左側(cè)的項(xiàng)目圖標(biāo)上右鍵點(diǎn)擊，然后從菜單中選擇 "啟用工作區(qū)"，此時 Opencode 會使用 git worktree 功能，從 master 上創(chuàng)建一個 opencode/xxx 的分支，然后可以對新建的工作區(qū)重新命名，之后就可以在多個工作區(qū)中同時使用AI工作。
當(dāng)某個工作區(qū)里的編碼工作完成后，可以讓 AI 為當(dāng)前代碼提交一個 PR，然后刪除該工作區(qū)，創(chuàng)建時產(chǎn)生的分支和代碼目錄會自動清理，非常方便。
選擇合適的 Agent
OpenCode 在沒有任何插件的情況下，只提供兩個主 Agent：Build 和 Plan。Build Agent 擁有完整的工具訪問權(quán)限。Plan Agent 的任務(wù)是在我描述需求時向我澄清問題，最終產(chǎn)出一個執(zhí)行計(jì)劃。
對于日常的小任務(wù)，可以會直接選擇 Build Agent。
但對于復(fù)雜任務(wù)，Build 往往會基于自己的理解直接開始編碼。正確的方式是：每個新需求都先用 Plan Agent 進(jìn)行需求澄清，拿到一個執(zhí)行計(jì)劃，要求他把計(jì)劃落實(shí)成一個PLAN.md，人工檢查該文件，確認(rèn)沒問題后，再開啟一個新的會話，讓 Build 加載執(zhí)行計(jì)劃文檔然后開始執(zhí)行。
務(wù)必創(chuàng)建 AGENTS.md
在得到一個新項(xiàng)目的時候，一定要先讓 AI 創(chuàng)建一個AGENTS.md，這樣可以顯著減少后續(xù)編碼過程中的幻覺。
在 OpenCode 中可以通過 /init 命令自動創(chuàng)建AGENTS.md。它告訴 LLM 在編碼過程中需要遵循哪些工程約束。
提高 Skills 加載成功率
Skills 在正常情況下其實(shí)并不一定可靠。 Skill的來源非常廣泛，不同的創(chuàng)建Skill的方式、使用不同的LLM都可能讓同一個Skill的表現(xiàn)不完全一致。
原因呢，一方面，Skill 中的description通常寫得很模糊。它應(yīng)該清楚說明該 Skill 適用于具體什么場景、提供什么能力。
另一方面，對于常見編碼場景，LLM 在預(yù)訓(xùn)練階段已經(jīng)學(xué)到了太多東西，覺得不需要加載 Skill 來獲取額外指導(dǎo)。
我們可以手動在 AGENTS.md 中添加這一行：
Prioritize retrieval-led reasoning over pretrained-knowledge-led reasoning.
收到這個指令后，LLM 會針對給定的編碼場景加載相關(guān) Skill，而不是依賴內(nèi)部預(yù)訓(xùn)練知識。LLM也會更加頻繁的使用 glob/grep 等工具檢查現(xiàn)有代碼結(jié)構(gòu)，通過websearch在線查找資料。它遵循“先搜索再驗(yàn)證”的方式，而不是依賴直覺。
二、安裝和配置OpenSpec
2.1 為什么需要 SDD？
所謂SDD，其實(shí)就是一種以規(guī)范文檔為核心的開發(fā)方式，我們的產(chǎn)品寫明詳細(xì)需求文檔，我們規(guī)劃編碼方式和測試計(jì)劃，最后才開始寫代碼。
很多模型編碼能力的測試，都是用類似“用一句話描述構(gòu)建一個xxx Demo”這樣的方式來評價一個LLM模型，但這種操作和實(shí)際工作相差甚遠(yuǎn)。
OpenSpec是一個輕量化的SDD工作流工具，適用于絕大多數(shù)日常項(xiàng)目。他不是 OpenCode 的插件，而是一個完全獨(dú)立的程序。我可以讓他介入到任意的Agent工具當(dāng)中。
配置工作流
通過 npm install -g @fission-ai/openspec@latest 來在系統(tǒng)全局安裝這個工具。
然后運(yùn)行
cd your-project
openspec init
注意：init操作需要到每一個項(xiàng)目下都運(yùn)行一次，后續(xù)才能對某個項(xiàng)目單獨(dú)運(yùn)行OpenSpec命令
按照提示為opencode安裝skill后，項(xiàng)目下會出現(xiàn)openspec 和.opencode 文件夾，前者會存放所有的需求和操作文檔，后者則是為opencode安裝了新的skill命令。
現(xiàn)在當(dāng)我打開 Opencode，找到我的項(xiàng)目，按下 / ，就可以看到下面4個新命令： opsx-explor、opsx-propose、opsx-apply 和 opsx-archive。分別對應(yīng)探索需求、創(chuàng)建需求文檔、實(shí)施和歸檔。
/opsx:explor ──? /opsx:propose ──? /opsx:apply ──? /opsx:archive
與Opencode自帶的 Plan 模式相比，opsx-explor 命令使用 Skill 來引導(dǎo)用戶澄清需求，幫助用戶更完整地思考問題。這個命令不會創(chuàng)建任何文件，只是和我討論需求。
然后，可以運(yùn)行 opsx-propose 來把需求落實(shí)為一系列的markdown文檔，存放在/openspec中。每一次提案，都會放在新的一個文件夾中，這樣就可以方便的管理每一次的需求文檔。
確認(rèn)需求后，可以運(yùn)行 opsx-apply 來實(shí)施需求。他會根據(jù)上一步創(chuàng)建的checklist一步一步的完成需求。
在編碼完成后，就可以使用 opsx-archive 將本次的需求歸檔。歸檔后本需求的文檔會被移動到/openspec/archive中，以便后續(xù)查找。
如果沒有上面的命令怎么辦
OpenSpec有十幾個命令，根據(jù)版本的不同，默認(rèn)只開放了其中的3~4個。
如果里面沒有想要的命令，可以使用 openspec config profile 打開配置，然后選擇 opsx-explorer 和 opsx-verify，之后重啟OpenCode即可看到默認(rèn)隱藏的命令了。
配置多語言支持
OpenSpec 創(chuàng)建的文檔，偶爾會是英文的。我可以找到 /OpenSpec/config.yaml 文件中配置語言：
schema: spec-driven
context: |
Language: Chinese
Write in Chinese, but:
- Keep technical terms like "API", "REST", "GraphQL" in English
- Code examples and file paths remain in English
Tech stack: TypeScript, VUE3, Nuxt.js
Rules:
proposal:
- Keep proposals under 1500 words
- Always include a "Non-goals" section
tasks:
- Break tasks into chunks of max 2 hours
除了語言，還可以在這里配置其他設(shè)置，比如技術(shù)棧以及對 proposal.md 和 tasks.md 文件的具體要求。
三、日常開發(fā)工作流
3.1 項(xiàng)目初始化
AI 時代的開發(fā)過程應(yīng)該以面向 AI 構(gòu)建為中心，這與傳統(tǒng)編碼工作流是不同的。所有配置和文檔都應(yīng)該以 AI 能夠理解和遵循的方式編寫。
創(chuàng)建項(xiàng)目后，首先要初始化 OpenSpec 。在項(xiàng)目根目錄運(yùn)行 openspec init。然后在界面中選擇 OpenCode。
最后，進(jìn)入 openspec 目錄，編輯 config.yaml 添加自己的規(guī)則。
所有配置完成后，在 OpenCode 中運(yùn)行 /init 命令，讓 OpenCode 生成 AGENTS.md 文件，鎖定所有這些配置選擇。
3.2 開發(fā)工作流
最好的開始方式是在 OpenCode 中打開一個新會話，從 /opsx-explorer 開始。 /opsx-explorer 會幫我完善細(xì)節(jié)，幫助 LLM 澄清問題。
從小處著手，一次做一個小的需求，而不是一次性增加一整個大型模塊。AI 每次完成少量工作，可以避免上下文限制導(dǎo)致的 AI 跑偏。
需求討論基本完成后，運(yùn)行 /opsx-propose 創(chuàng)建提案。這將討論和開發(fā)計(jì)劃鎖定為 spec 文檔。OpenSpec 會根據(jù)復(fù)雜度將內(nèi)容分解為一個或多個變更，然后生成 proposal.md、design.md 和 tasks.md。
仔細(xì)檢查這三個文件。LLM 生成的任務(wù)可能存在遺漏或誤解。如果發(fā)現(xiàn)錯誤，可以直接讓 OpenSpec 重新生成文檔，或者直接編輯規(guī)則文件，然后讓 OpenSpec 重新生成文檔。
文檔看起來沒問題后，開啟一個新會話以獲得全新的上下文。然后運(yùn)行 /opsx-apply 進(jìn)入實(shí)施階段。
編碼完成后，需要切到一個新的會話，然后運(yùn)行 /opsx-verify 來驗(yàn)證所有任務(wù)是否完成，在運(yùn)行這一步時，建議使用另一個模型來讓他來驗(yàn)證代碼。
最后，運(yùn)行 /opsx-archive 來歸檔變更。
當(dāng)下一個新需求進(jìn)來時，用新會話和 /opsx-explorer 重新開始。
