从 IDE 智能提示，到 Copilot 行内补全，到 Chat 式问答，再到今天的 Code Agent——AI 在工程师工作流里的位置越来越靠近"决策端"，而不只是"执行端"。每一代的飞跃都不是"补全更准"，而是 AI 主动承担的范围更大：从一个词、一行、一段，到整个任务。
走到第 4 阶段（Code Agent）之后，你的角色变了。
过去你是写代码的人，AI 是辅助工具；现在 AI 是干活的人，你是派活、定边界、审产出的"项目经理"。这不是修辞——它是工作方式的彻底重组。
很多人第一次启动 OpenCode 会愣一下："咦？怎么是终端里的东西？我的 IDE 呢？"
这很正常。Code Agent 这一代工具刻意选择"住在终端"，不绑定任何 IDE——因为它不是来"补全你的代码"的，它是来"替你完成任务"的。它需要直接调用 shell、跑命令、读写文件，终端是最自然的栖息地。
OpenCode 默认是 Build 模式——可以读写文件、运行命令，全套工具都开着。这是日常干活的模式。
按 Shift+Tab 可以在 Build 模式 和 Plan 模式之间切换——它只能读、不能写：可以分析代码、出方案、回答问题，但所有"改文件、跑命令"的工具都被禁用。
Plan 模式适用场景：
Shift+Tab 切到 Plan 模式。这是比"嘴上告诉 AI 不要写代码"更可靠的安全护栏——因为是在工具层禁止，不是模型自觉。
即便在 Build 模式下，它要写文件、跑命令之前默认也会停下来让你确认（"这个文件要改成这样，OK 吗？"）。这是新手的安全模式。
熟练之后可以切到 YOLO 模式（You Only Live Once），全自动批准。它的好处是任务长链路时不用你每一步都点 yes，效率高很多；代价是一旦它跑偏了，等你发现时损失可能已经发生。
什么时候开 YOLO：
OpenCode 的 YOLO 不是一个独立的开关，而是通过 permission 配置实现的。在 opencode.json（项目级放在仓库根目录、全局级放在 ~/.config/opencode/opencode.json）里设置：
{
"permission": "allow"
}
这一行就把所有工具默认改成"无需确认直接执行"。如果想细粒度控制——比如允许大部分但禁止某些高危操作——可以用对象形式：
{
"permission": {
"*": "allow",
"edit": "ask",
"bash": { "rm -rf *": "deny" }
}
}
三种状态：allow 直接跑、ask 弹确认、deny 拦死。配置生效后 TUI 会显示 △ YOLO mode 提示，给你一个视觉锚点知道现在没护栏了。
opencode.json，主仓里依然走默认确认模式。
/clear。
AGENTS.md 是放在项目根目录的一份 Markdown 文档，OpenCode 启动时会自动读取，把里面的内容当成"项目背景"。可以理解为：给新来的实习生准备的入职手册。
它解决的问题：默认情况下 AI 进入你的项目相当于一个"什么都不知道、需要自己翻代码摸索的新人"，写 AGENTS.md 等于告诉它"项目是干嘛的、技术栈、关键命令、不能碰的地方"——后续所有对话都站在这个基础上。
示例模板（只是为了让大家直观感受 AGENTS.md 大概长什么样，不是最佳实践，每个项目应该根据实际情况自由裁剪、增补）：
# 项目概览
本项目是 XX 系统的 [前端/后端/算法] 模块，主要负责 ……
## 技术栈
- 语言：Java 17 / TypeScript 5.x / Python 3.11
- 框架：Spring Boot 3 / React 18 / FastAPI
- 构建：Maven / pnpm / poetry
- 测试：JUnit 5 / Vitest / pytest
## 关键目录
- `src/...` 业务代码
- `test/...` 测试代码
- `docs/` 设计文档
- `scripts/` 脚本
## 常用命令
- 跑测试：`mvn test`
- 启动本地服务：`npm run dev`
- 代码风格检查：`npm run lint`
## 编码规范
- 业务异常用 BusinessException，不直接抛 RuntimeException
- React 组件按 feature 组织，不按 type
- Python 算法模块要保留 `# pylint: disable=...` 的明确理由
## 注意事项（重要！）
- `legacy/` 目录正在迁移中，改之前先问我
- 数据库 schema 变更必须走 Flyway，不要直接改表
- 任何涉及 `payment` 包的改动都要加单元测试覆盖
很多人第一次用 OpenCode 就交一个功能开发任务，结果产出一团糟，从此放弃。这是最大的误用。
建议第一个任务：让它读你的项目，输出一份理解。先按 Shift+Tab 切到 Plan 模式（这一步它就动不了文件了，零风险），然后给它这样一道题：
读一下 src/order 这个模块，告诉我:
1. 它的对外接口是什么？入口在哪几个文件？
2. 主要依赖了哪些其他模块？
3. 哪些部分看起来有技术债 / 你觉得可读性差？
不要修改任何文件，只输出报告。
为什么从这种任务开始：
跑完这一题后，你大概会有 3 个意外发现：
练完"读"，再上"写"。第一次写代码的任务，建议挑这种：
派活时遵守 3 件事（这是第 3 章会展开的核心）：
跑完之后做 3 件事：
上手之后，你会反复用到三个动作：让它先 plan、把上下文喂厚、把测试当护栏。这一章把这三招拆开讲——它们是日常 90% 任务的核心配方。
直接对 AI 说"加一个用户登录功能"，等同于第一天上班的实习生什么都不问就上手改项目。永远先让它出方案，方案对了再让它写代码——多花 5 分钟讨论 plan，能省下更多的时间去回退。
第一段：让它出方案，不让它写代码
任务：给 /api/order/create 加幂等保护。
现在不要写代码。先输出一份实施方案：
1. 你对需求的理解（用一句话复述）
2. 准备做的具体步骤（编号列）
3. 涉及哪些文件 / 模块
4. 你看到的风险点 / 不确定的地方
第二段：你审过 plan，确认/调整后再放它去做
方案 OK，按这个执行。
模型再强，它没看到的东西它就是瞎编。"它应该能自己找到吧" 这种期待，是把任务搞砸的最常见原因。Prompt 写得多漂亮，都不如把正确的资料喂到它面前。
✗ 模糊：
给工单模块加个新接口
✓ 明确：
先读这 3 个文件再开始：
·src/main/java/com/x/order/OrderController.java
·src/main/java/com/x/order/OrderService.java
·docs/order-domain.md
读完告诉我你对现有架构的理解，我确认后再继续。
它不知道你昨天会上跟架构师吵了什么——把结论输出成文件，作为项目的一部分保存下来：
约束：
· 必须用 PostgreSQL，不要用 MySQL 语法
· 异常体系：业务异常用 BusinessException，不直接抛 RuntimeException
· 日志用 SLF4J，不用 System.out
· 前端组件用 shadcn/ui，不要引入新的 UI 库
不要碰：
·legacy/目录正在迁移
·payment/包的改动需要单独评审，本次不碰
· 不要修改任何*.proto文件
@文件路径 引用文件"麻烦改一下登录"——AI 改了 → "你这改得不对" → AI 又改 → "还是不对" → 你来回 10 轮疲惫不堪。
根因：你的验收标准在你脑子里，AI 看不见。
解药：所有任务的验收标准，能写成测试就写成测试。机器验收 0 歧义。
任务：实现 calculateDiscount(orderAmount, vipLevel) 函数。
执行顺序：
1. 先在 calculate_discount.test.ts 写测试用例（覆盖 vipLevel 0-3 + orderAmount 边界）
2. 让我审过测试 OK 后，再去实现
3. 实现完跑测试直到全绿
任务：修复 xxx，状态机在并发下错乱的 bug。
约束：
- 不要修改任何测试代码
- 跑完后必须 mvn test -Dtest=OrderStateMachineTest 全绿
- 修复方案在动手前先 plan 给我看
项目目前测试覆盖很差。这次任务：xxx
请你先写一个 acceptance test 作为这次改动的"验收闸门"，
能跑通才算成功。
上述的几个小技巧，靠的是你每次都记得——记得让它先 plan、记得喂上下文、记得把验收写成测试。Skill 是把这些动作沉淀成 AI 的"肌肉记忆"：写一次、放进目录里，之后符合触发条件就自动跑，不再依赖你的自律。
前一章我们讲了"日常的几个小技巧"（Plan / Context / 测试）。你可能已经发现一个问题：这些技巧每次都要你手动执行——每次都要记得让 AI 出 plan、每次都要喂资料、每次都要明确验收标准。
Skill 就是把这些"该做但容易忘的动作"打包成一个可复用、可自动触发的能力包。
可以理解为 Skill 是给 AI 装的专项技能。例如：
tdd skill：自动让 AI 走"先写测试 → 让我审 → 再写实现"的流程code-review skill：自动让 AI 用一份固定的 checklist 来 review diffresume-design skill：自动让 AI 用统一的版式生成简历Skill 的本质是一份带触发条件的指令包：当用户的请求匹配某种意图（"帮我写简历"），AI 自动应用这个 skill 里写好的工作流。它跟你直接在每次 prompt 里手写规则的区别是——它一次配置、永久受益。
OpenCode 的 skill 体系比 Claude Code 的 plugin 简单——本质就是一些带 YAML frontmatter 的 markdown 文件，放到约定的目录里就生效。
| 路径 | 作用域 |
|---|---|
~/.config/opencode/skills/ | 全局——你所有项目都能用 |
<项目根>/.opencode/skills/ | 项目级——只对当前项目生效，可以提交到 git 让团队共享 |
方式 1——直接放 markdown 文件：拿到 skill 的 .md 文件（开源仓库基本都是这种格式），扔到上面任一目录即可。
# 全局装一个 skill
mkdir -p ~/.config/opencode/skills
cp path/to/some-skill.md ~/.config/opencode/skills/
方式 2——通过 skills.sh 安装：Vercel 维护的 skill 注册中心，相当于 skill 界的 npm。在网站上能浏览、搜索社区 skill，按"全部 / 24h 热门 / 总热门"排序看安装量榜单，点进去能看到每个 skill 的详情和安装命令——找到想要的，复制一行就装：
npx skills add <owner/repo>
它支持 20+ 种 agent 工具（Claude Code、Cursor、Cline、Copilot…… 不只是 OpenCode）
/new 开新一段，输一句应该触发该 skill 的话——观察它是否按 skill 里写的工作流响应。如果没触发，最常见的原因是 frontmatter 的 description 写得太模糊，模型没匹配到意图。
它不是零散 skill 的拼盘，而是一套把软件工程最佳实践编码进 AI 工作流的系统。从需求澄清、架构设计、TDD 开发、代码审查到分支收尾，每个环节都有对应的 skill 把关。
| 阶段 | Skill | 作用 |
|---|---|---|
| 1 | brainstorming | 写代码前通过苏格拉底式提问帮你梳理真正需求 |
| 2 | using-git-worktrees | 在新分支创建隔离工作空间，避免污染主代码 |
| 3 | writing-plans | 把大任务拆成 2-5 分钟能完成的小步骤，含具体文件路径和验证标准 |
| 4 | subagent-driven-development | 为每个小任务派发子代理，分工完成并互相审查 |
| 5 | test-driven-development | 强制红-绿-重构循环：先写失败测试 → 写最小代码 → 看测试通过 |
| 6 | requesting-code-review | 对照计划审查产出，关键问题阻止继续 |
| 7 | finishing-a-development-branch | 验证测试、提供合并/PR/丢弃选项、清理工作树 |
编辑 opencode.json（项目级放仓库根目录，全局级放 ~/.config/opencode/opencode.json），把 superpowers 加进 plugin 数组：
{
"plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
}
重启 OpenCode，插件管理器会自动拉取并安装。完了之后随便起一段对话问它"tell me about your superpowers"，能正常回答就装好了。
superpowers 的命中频率很高，但它本身非常耗时——brainstorming、plan、TDD 循环、代码审查一套下来，即使是个小改动走这一套流程下来也要很久。建议装完后把触发方式改成手动，只在真正需要完整工程流程时再启用，至于怎么改，直接交给 OpenCode 就好：
你 review 一份代码、调试一个 bug、写一份 README——这些事老程序员有套路，新人或 AI 没有。Waza 把这些套路打包：
| Skill | 触发场景 | 它会做什么 |
|---|---|---|
/think | 复杂判断时 | 强制 AI 先列假设、列证据、列反对意见再出结论 |
/design | 写新功能前 | 走"目标 → 约束 → 方案 → 取舍"的设计走查 |
/check | 改完代码后 | 用 checklist 自审（边界、错误处理、命名…） |
/hunt | 查 bug 时 | 二分定位 + 写最小复现 |
/write | 写文档/注释时 | 走严格的"读者画像 → 信息密度 → 删冗余" |
/read | 读不熟的代码时 | 按"入口 → 数据流 → 边界" 的读法 |
/learn | 接触新技术时 | 强制走"5 个小实验 → 一份总结" |
/health | 项目健康度自检 | 跑出可读性/复杂度/重复度报告 |
/design skill 触发时的走查流程
/write skill 调用过程
/write skill 输出的成品亮点：每个 skill 只做一件事、触发条件明确，名字短好记。设计哲学是"克制"——给目标和约束，剩下交给 AI。
# OpenCode（全局安装到 ~/.config/opencode/skills/）
npx skills add tw93/Waza -a -g -y
让 AI 写文档/做 PPT 时，输出经常长得像后台 dashboard——版式杂乱、字号乱跳、配色刺眼。Kami 是一套版式约束系统，给 AI 一份"印刷品级别"的设计准则。
它能做什么：用统一的版式输出 6 类文档（一页纸 / 长文档 / 信件 / 作品集 / 简历 / 幻灯片），有专门的中英双语模板。统一墨蓝主色、衬线层级、留白节奏。
典型场景：你说"帮我写一份简历"或"输出一页纸的项目总结"——Kami 自动触发，不需要你说"用 Kami"。
# OpenCode（全局安装）
npx skills add tw93/Kami -a -g -y
知道有 superpowers/Waza/Kami 之后，你迟早会想"我能不能给我们项目写一个内部 skill"。
一个最小 skill 长这样（只是一份带元数据的 Markdown）：
---
name: backend-pr-checklist
description: 提交后端 PR 前的自检 checklist。当用户说"准备提 PR"或类似意图时触发。
---
# Backend PR Checklist
按以下顺序自检：
1. 单测是否覆盖关键路径？
2. 异常体系是否符合规范（BusinessException）？
3. 数据库变更是否走 Flyway？
4. 是否有 TODO 残留？
5. ……
把这种 markdown 文件放到 skill 目录（OpenCode 是 .opencode/skills/ 或 ~/.config/opencode/skills/，参考 4.2 节），就能像内置 skill 一样被触发。
第一个内部 skill 推荐选题（往团队里推动一下）：
挑了一组对建立"派 AI"工作直觉最有效的入门资料。Code Agent 生态变化很快，常翻常新。
照着走一遍，你就完整跑过一遍 Code Agent 的工作流——从装好工具，到完成一次"读项目 + 改 bug"的完整循环。
/init，生成 AGENTS.md 草稿/new 开新一段几个最常用的命令和快捷键，具体以 /help 为准。
| 操作 | 作用 |
|---|---|
/init | 让 OpenCode 扫一遍项目，自动生成一份 AGENTS.md 草稿 |
/new | 清空当前对话上下文，开新一段——任务结束就清，避免污染 |
/sessions | 列出 / 切换历史会话，能看到每段对话当时干了什么、改了什么 |
/undo | 撤销 AI 上一步对文件的改动——发现它把代码改坏了，第一反应是 /undo，比手动 git 还方便 |
/exit | 退出 |
@文件路径 | 在 prompt 里直接引用文件——输 @ 会自动补全文件名，比让它自己去找快得多 |
Shift + Tab | 在 Build 模式 ⇄ Plan 模式 之间切换 |
Esc | 中断当前任务——看到它跑偏了立刻按，别犹豫 |