前言
我从来没有使用过 Claude Code或是Codex，太贵了。订阅一个GPT的价格，完全可以同时订阅三家顶级的国产模型。
所以我一直在用开源方案构建自己的 AI 编码环境：以 OpenCode 为基础，配合 OpenSpec（SDD）。
我的想法是：如果清楚自己在做什么，并且是个经验丰富的开发者，那么像 Qwen3.6-Plus、Kimi-k2.5、GLM-5.1、Minimax M2.7 这些前沿开源模型（即便他们在各种评测中不及最新的GPT和opus），完全可以 handle 日常编码任务。
开源软件还有巨大的社区，可以针对不同模型调优系统提示和模型参数，让开源模型发挥出最大潜力。
一、安装与配置OpenCode
1.1 安装 OpenCode
相比于Claude Code和大多数只有一个命令行界面的编码Agent，OpenCode 提供了带图形界面的桌面应用，这为每一次Code Review提供了极大的方便。
配置模型提供商
打开设置窗口，选择 “提供商”，拉到底部有“选择更多提供商”，就像我使用的模型商，在输入框里输入minimax，就可以看到他们家的Coding Plan选项，然后输入你的ApiKey就接入完成了。
这里的配置实际上被写入到了~/.local/share/opencode/auth.json这个文件中，里面可以看到我的所有模型提供商的key。
启用 Workspaces
我们在工作中的一个痛点是，开发者经常会收到零碎又紧急的需求。
传统的做法是我们临时保存当前分支，然后切一个 fix/some-bug 分支出来修改后立即提交到master上去。
高级且更方便一点的做法是可以使用 git worktree 切一个新的 worktree，并在里面开发。
Opencode 原生支持 worktree 功能，这个功能叫做 "工作区"。
启用方式：在左侧的项目图标上右键点击，然后从菜单中选择 "启用工作区"，此时 Opencode 会使用 git worktree 功能，从 master 上创建一个 opencode/xxx 的分支，然后可以对新建的工作区重新命名，之后就可以在多个工作区中同时使用AI工作。
当某个工作区里的编码工作完成后，可以让 AI 为当前代码提交一个 PR，然后删除该工作区，创建时产生的分支和代码目录会自动清理，非常方便。
选择合适的 Agent
OpenCode 在没有任何插件的情况下，只提供两个主 Agent：Build 和 Plan。Build Agent 拥有完整的工具访问权限。Plan Agent 的任务是在我描述需求时向我澄清问题，最终产出一个执行计划。
对于日常的小任务，可以会直接选择 Build Agent。
但对于复杂任务，Build 往往会基于自己的理解直接开始编码。正确的方式是：每个新需求都先用 Plan Agent 进行需求澄清，拿到一个执行计划，要求他把计划落实成一个PLAN.md，人工检查该文件，确认没问题后，再开启一个新的会话，让 Build 加载执行计划文档然后开始执行。
务必创建 AGENTS.md
在得到一个新项目的时候，一定要先让 AI 创建一个AGENTS.md，这样可以显著减少后续编码过程中的幻觉。
在 OpenCode 中可以通过 /init 命令自动创建AGENTS.md。它告诉 LLM 在编码过程中需要遵循哪些工程约束。
提高 Skills 加载成功率
Skills 在正常情况下其实并不一定可靠。 Skill的来源非常广泛，不同的创建Skill的方式、使用不同的LLM都可能让同一个Skill的表现不完全一致。
原因呢，一方面，Skill 中的description通常写得很模糊。它应该清楚说明该 Skill 适用于具体什么场景、提供什么能力。
另一方面，对于常见编码场景，LLM 在预训练阶段已经学到了太多东西，觉得不需要加载 Skill 来获取额外指导。
我们可以手动在 AGENTS.md 中添加这一行：
Prioritize retrieval-led reasoning over pretrained-knowledge-led reasoning.
收到这个指令后，LLM 会针对给定的编码场景加载相关 Skill，而不是依赖内部预训练知识。LLM也会更加频繁的使用 glob/grep 等工具检查现有代码结构，通过websearch在线查找资料。它遵循“先搜索再验证”的方式，而不是依赖直觉。
二、安装和配置OpenSpec
2.1 为什么需要 SDD？
所谓SDD，其实就是一种以规范文档为核心的开发方式，我们的产品写明详细需求文档，我们规划编码方式和测试计划，最后才开始写代码。
很多模型编码能力的测试，都是用类似“用一句话描述构建一个xxx Demo”这样的方式来评价一个LLM模型，但这种操作和实际工作相差甚远。
OpenSpec是一个轻量化的SDD工作流工具，适用于绝大多数日常项目。他不是 OpenCode 的插件，而是一个完全独立的程序。我可以让他介入到任意的Agent工具当中。
配置工作流
通过 npm install -g @fission-ai/openspec@latest 来在系统全局安装这个工具。
然后运行
cd your-project
openspec init
注意：init操作需要到每一个项目下都运行一次，后续才能对某个项目单独运行OpenSpec命令
按照提示为opencode安装skill后，项目下会出现openspec 和.opencode 文件夹，前者会存放所有的需求和操作文档，后者则是为opencode安装了新的skill命令。
现在当我打开 Opencode，找到我的项目，按下 / ，就可以看到下面4个新命令： opsx-explor、opsx-propose、opsx-apply 和 opsx-archive。分别对应探索需求、创建需求文档、实施和归档。
/opsx:explor ──► /opsx:propose ──► /opsx:apply ──► /opsx:archive
与Opencode自带的 Plan 模式相比，opsx-explor 命令使用 Skill 来引导用户澄清需求，帮助用户更完整地思考问题。这个命令不会创建任何文件，只是和我讨论需求。
然后，可以运行 opsx-propose 来把需求落实为一系列的markdown文档，存放在/openspec中。每一次提案，都会放在新的一个文件夹中，这样就可以方便的管理每一次的需求文档。
确认需求后，可以运行 opsx-apply 来实施需求。他会根据上一步创建的checklist一步一步的完成需求。
在编码完成后，就可以使用 opsx-archive 将本次的需求归档。归档后本需求的文档会被移动到/openspec/archive中，以便后续查找。
如果没有上面的命令怎么办
OpenSpec有十几个命令，根据版本的不同，默认只开放了其中的3~4个。
如果里面没有想要的命令，可以使用 openspec config profile 打开配置，然后选择 opsx-explorer 和 opsx-verify，之后重启OpenCode即可看到默认隐藏的命令了。
配置多语言支持
OpenSpec 创建的文档，偶尔会是英文的。我可以找到 /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
除了语言，还可以在这里配置其他设置，比如技术栈以及对 proposal.md 和 tasks.md 文件的具体要求。
三、日常开发工作流
3.1 项目初始化
AI 时代的开发过程应该以面向 AI 构建为中心，这与传统编码工作流是不同的。所有配置和文档都应该以 AI 能够理解和遵循的方式编写。
创建项目后，首先要初始化 OpenSpec 。在项目根目录运行 openspec init。然后在界面中选择 OpenCode。
最后，进入 openspec 目录，编辑 config.yaml 添加自己的规则。
所有配置完成后，在 OpenCode 中运行 /init 命令，让 OpenCode 生成 AGENTS.md 文件，锁定所有这些配置选择。
3.2 开发工作流
最好的开始方式是在 OpenCode 中打开一个新会话，从 /opsx-explorer 开始。 /opsx-explorer 会帮我完善细节，帮助 LLM 澄清问题。
从小处着手，一次做一个小的需求，而不是一次性增加一整个大型模块。AI 每次完成少量工作，可以避免上下文限制导致的 AI 跑偏。
需求讨论基本完成后，运行 /opsx-propose 创建提案。这将讨论和开发计划锁定为 spec 文档。OpenSpec 会根据复杂度将内容分解为一个或多个变更，然后生成 proposal.md、design.md 和 tasks.md。
仔细检查这三个文件。LLM 生成的任务可能存在遗漏或误解。如果发现错误，可以直接让 OpenSpec 重新生成文档，或者直接编辑规则文件，然后让 OpenSpec 重新生成文档。
文档看起来没问题后，开启一个新会话以获得全新的上下文。然后运行 /opsx-apply 进入实施阶段。
编码完成后，需要切到一个新的会话，然后运行 /opsx-verify 来验证所有任务是否完成，在运行这一步时，建议使用另一个模型来让他来验证代码。
最后，运行 /opsx-archive 来归档变更。
当下一个新需求进来时，用新会话和 /opsx-explorer 重新开始。
