OpenCode 提示词工程完全指南：用高质量指令释放 AI 编程助手的全部潜能

OpenCode 提示词工程完全指南：用高质量指令释放 AI 编程助手的全部潜能

引言

在 AI 编程助手的日常使用中，很多开发者会陷入一个误区：认为 AI 的能力完全取决于底层大模型，只要选对了模型就能解决一切问题。但实际经验告诉我们，提示词的质量往往比模型的选择更能决定输出结果。同样的 Claude、GPT 或 Gemini 模型，在不同的提示词指导下，产出质量可能天差地别。

OpenCode 作为一款开源的 AI 编程助手，提供了丰富的上下文注入机制和灵活的 Agent 系统。但很多用户只停留在最基础的用法——直接输入需求让 AI 去执行，却忽略了 OpenCode 其实是一个高度可编程的 AI 交互平台。本文将从提示词工程的角度，系统性地讲解如何通过高质量指令让 OpenCode 更精准地理解你的意图，从而大幅提升编码效率。

OpenCode 的提示词处理机制

要写好提示词，首先要理解 OpenCode 是如何接收和处理指令的。当你在 OpenCode 中输入一条消息时，它会被组合成一个包含多层级指令的系统提示词（System Prompt），最终发送给 LLM。这个系统提示词的构成如下：

系统层级指令（OpenCode 内置）
  ├── AGENTS.md 项目指令
  ├── opencode.json 中 instructions 字段引用的文件
  ├── 全局 AGENTS.md（~/.config/opencode/AGENTS.md）
  ├── 会话上下文（历史消息）
  └── 你的当前输入（User Prompt）

理解这个层级结构至关重要。你的每一次输入都是在与一个已经加载了大量上下文的 AI 对话。因此，你的提示词不需要重复 AGENTS.md 中已有的信息，而应该专注于当前任务的具体指令。

核心提示词结构：任务模板

经过大量实践，我总结出一个适用于 OpenCode 编程任务的高效提示词模板：

## 任务目标
[用一句话明确描述要完成的任务]

## 具体需求
- [需求点 1：明确、具体、可验证]
- [需求点 2：包含约束条件]
- [需求点 3：指明代偿方案或优先级]

## 参考文件
- @src/xxx.ts 中的 xxx 函数（参考其实现模式）
- @docs/yyy.md（遵循其中的规范）

## 验收标准
1. [标准 1：行为层面]
2. [标准 2：代码质量层面]
3. [标准 3：性能或安全层面]

这个模板之所以有效，是因为它精准地填补了 AI 最常见的三个信息缺口：做什么（任务目标）、怎么做（具体需求 + 参考）、做到什么程度算好（验收标准）。

实战示例

以下是使用上述模板的实际对话：

## 任务目标
为 /api/users 路由添加分页查询功能

## 具体需求
- 支持 page 和 pageSize 参数，默认 page=1, pageSize=20
- 返回格式：{ data: User[], total: number, page: number, pageSize: number }
- 当 pageSize 超过 100 时自动限制为 100
- 使用 Prisma 进行数据库查询，不引入额外分页库

## 参考文件
- @src/api/posts.ts 中已完成的分页实现，保持风格一致
- @prisma/schema.prisma 了解 User 模型结构

## 验收标准
1. 请求 /api/users?page=2&pageSize=10 正确返回第 2 页数据
2. 请求 /api/users?pageSize=200 返回 pageSize=100 的数据
3. 总记录数 total 正确反映未分页前的总数

利用 @ 引用注入精准上下文

OpenCode 最强大的功能之一就是 @ 引用机制。它能让你将文件、目录甚至是整个参考仓库注入到当前对话的上下文中。用好 @ 引用，你就不再需要手动粘贴代码或描述已有实现。

文件级引用

将这个组件的样式改成 @src/components/Button.tsx 那样的风格

目录级引用

参考 @src/utils/ 下的工具函数，为新 API 编写类似的错误处理

参考仓库引用

如果你在 opencode.json 中配置了 references：

{
  "references": {
    "design-system": {
      "path": "../shared-design-system",
      "description": "组件库和设计规范"
    }
  }
}

那么就可以在提示词中直接引用：

使用 @design-system 中的 Button 组件替换现有的原生按钮

@ 引用的最佳实践

精确引用，而非广泛引用：只引用与当前任务直接相关的文件，避免一次性加载过多无关代码，这既节省 token 也减少干扰

引用时附带说明：告诉 AI 你引用这个文件的目的，例如"参考 @auth.ts 中的错误处理模式"

利用目录路径做语义分组：@src/api/ 比 @src/ 更精准

AGENTS.md：项目级别的系统提示词

AGENTS.md 是你项目中最具杠杆效应的提示词工程工具。它相当于给 AI 一份项目"手册"，每次对话都会自动加载。一个精心编写的 AGENTS.md 能让后续所有交互都更加精准。

应该包含什么

# 项目名称
[项目的一句话描述]

## 技术栈
- 框架：Next.js 14 (App Router)
- 语言：TypeScript strict mode
- 数据库：PostgreSQL + Prisma ORM
- 样式：Tailwind CSS
- 测试：Vitest + Testing Library

## 项目结构
- `src/app/` - Next.js App Router 路由
- `src/components/` - 可复用 UI 组件
- `src/lib/` - 业务逻辑和工具函数
- `src/api/` - API 路由处理

## 代码约定
- 使用 named export，不使用 default export
- 异步组件在文件名后加 .server.tsx 后缀
- API 错误统一返回 { error: string, code: number } 格式
- 所有公开函数必须有 JSDoc 注释

## 常用命令
- 开发：npm run dev
- 测试：npm run test
- 类型检查：npm run typecheck
- 代码检查：npm run lint

应该避免什么

• 过于冗长：AGENTS.md 不是开发文档，应该控制在 50-100 行以内
• 存放过时信息：过时的指令比没有指令更糟糕，会让 AI 持续犯错
• 描述显而易见的常识：不需要写"JavaScript 是编程语言"这类信息

Plan 模式 vs Build 模式：两种推理策略

OpenCode 的 Plan 模式和 Build 模式本质上是两种不同的提示词策略。理解它们的区别，可以帮助你针对不同任务选择合适的交互方式。

Plan 模式：先思考后执行

适合复杂任务、重构、架构决策。Plan 模式下 AI 被限制不能修改文件，只能分析和建议。

[切换到 Plan 模式]
我需要重构用户认证模块，将当前的 session-based 认证改为 JWT-based。
请先分析当前 @src/auth/ 下的所有文件，给出：
1. 当前架构的问题
2. 迁移方案和步骤
3. 需要修改的文件清单
4. 潜在的兼容性风险

Plan 模式的价值在于：它让你在投入代码改动之前，先看到 AI 对问题的理解程度。如果方案不对，你可以立即纠正，避免了写出一堆错误的代码后再返工。

Build 模式：直接执行

适合明确了方案的执行阶段。当你已经通过 Plan 模式确认了方向，或者任务本身足够简单明确时，直接切换到 Build 模式执行。

[切换回 Build 模式]
方案已确认，开始执行步骤 1-3。先实现 JWT token 的生成和验证工具函数，
然后改造 login 和 register 路由。

混合使用的最佳实践

1. Plan：分析问题、设计方案
2. 迭代：反馈修正方案（如果需要）
3. Build：按方案逐步执行
4. 验证：执行测试和类型检查

这套工作流程能显著降低大型任务的出错率。

多步骤任务分解

当任务比较复杂时，一次性给出所有需求往往会导致 AI 遗漏细节或输出质量下降。正确的做法是将任务分解为多个子任务，逐步推进。

错误示范

给我实现一个完整的电商系统，包括用户管理、商品管理、订单系统、支付集成。

这种提示词的问题在于：信息密度过高，AI 容易在实现后半部分时忘记前半部分的约束。

正确示范

第一步：实现商品 CRUD 的 API 路由
第二步：实现用户认证和权限中间件
第三步：实现订单创建和状态流转

每次只聚焦一个子任务，但每个子任务内部仍然使用前文提到的任务模板。这样 AI 可以在每个步骤中保持高度专注。

利用 /init 命令建立初始上下文

当你进入一个新项目时，运行 /init 命令是最快的提示词工程起点。它会自动分析项目结构，生成量身定制的 AGENTS.md。

# 在项目根目录运行
opencode
# 然后在 TUI 中输入
/init

/init 会自动检测：

• 项目使用的语言和框架
• 构建、测试、lint 命令
• 项目目录结构
• 已有的配置文件和技术栈信息

生成之后，建议人工审阅和完善。AI 自动生成的内容可能缺少一些只有项目成员才了解的潜规则和业务约定。

图片作为提示词输入

OpenCode 支持拖拽图片到终端中作为提示词的一部分。这是一个被严重低估的功能。在许多场景下，一张图片胜过千言万语：

• UI 实现：拖拽设计稿，让 AI 根据视觉设计编写前端代码
• Bug 复现：截图错误信息，让 AI 直接看到异常堆栈
• 架构图：手绘系统架构图，让 AI 理解模块间的关系

[拖拽设计稿图片]
参考这张设计稿，实现用户个人资料编辑页面的 UI 组件。
注意：表单布局、颜色、间距和字体都要与设计稿保持一致。

从反馈中迭代：让 AI 越用越懂你

提示词工程不是一次性的事情。与 AI 协作是一个持续迭代的过程。OpenCode 的会话上下文机制让 AI 能够"记住"你在当前会话中的偏好和修正。

纠正反馈

当 AI 的输出不符合预期时，不要直接否定，而是给出具体的纠正方向：

这个实现方向是对的，但有两个问题：
1. 错误处理应该返回统一格式 { error: string } 而不是直接 throw
2. 数据库查询需要添加事务保证原子性
请修正这两个问题，其他保持不变。

示例驱动

如果需要 AI 遵循某种特定的代码风格，提供正反示例非常有效：

请参考以下示例的风格来实现新功能：

好的示例（请模仿）：
@src/examples/good-pattern.ts

不好的示例（请避免）：
@src/examples/bad-pattern.ts

总结

提示词工程是使用 OpenCode 的核心技能。本文从理解 OpenCode 的提示词处理机制开始，介绍了任务模板、@ 引用注入、AGENTS.md 编写、Plan/Build 模式选择、任务分解、图片输入和反馈迭代等关键技术。

掌握这些技巧后，你会发现同样的模型、同样的工具，产出的代码质量和开发效率会有质的飞跃。值得记住的是：向 AI 提问的能力，正在成为软件开发者的核心竞争力和生产力倍增器。花时间打磨你的提示词，就是对开发效率最好的投资。