叶云梦天

OpenCode 自动提示词系统实战：用 auto_prompt.md 打造个性化 AI 编程工作流

引言

在日常使用 OpenCode 编程助手的场景中，我们经常发现一个问题：每次开启新的对话会话时，都需要手动输入一段固定的背景信息——项目背景、编码规范、个人偏好等。这些重复性的前置说明不仅浪费时间，还会因为某次遗漏导致 AI 的输出偏离预期。

OpenCode 提供了一套完善的提示词注入机制，而 auto_prompt.md 正是这套机制中最灵活的一环。它允许你将固定的上下文自动注入到每一个新会话中，让 AI 从一开始就"了解你的需求"，无需每次手动铺垫。

本文将深入讲解 OpenCode 的提示词体系、auto_prompt.md 的配置方法、以及如何结合 AGENTS.md 与 opencode.json 的 instructions 字段，构建一套完整的个性化 AI 编程工作流。

OpenCode 提示词层级体系

在深入 auto_prompt.md 之前，必须先理解 OpenCode 的提示词注入层级。OpenCode 在启动一个对话时，会从多个来源加载指令，按照一定顺序合并到 LLM 的上下文中。

第一层：系统内置提示词

OpenCode 自身带有一套系统级提示词，定义了 Agent 的基本行为范式——如何使用工具、如何规划任务、如何回复用户等。这部分对所有用户一致，不可修改。

第二层：AGENTS.md（项目规则）

AGENTS.md 是 OpenCode 的规则文件，放置在项目根目录下。它由 /init 命令生成，也可以手动编写。用于描述项目架构、技术栈、编码规范等团队共享的信息。

# 项目规则

这是一个 NestJS + TypeScript 的后端项目。

## 技术栈
- Node.js 20+
- NestJS 作为 HTTP 框架
- Prisma 作为 ORM
- PostgreSQL 作为数据库

## 编码规范
- 使用 strict 模式的 TypeScript
- 所有 API 需要 Swagger 文档注解
- 单元测试覆盖率要求 80% 以上

AGENTS.md 适合包含跨会话稳定的项目级信息，应该被提交到 Git 仓库，供整个团队共享。

第三层：opencode.json 的 instructions 字段

如果你有分散在多个文件中的规则（比如 .cursor/rules/、CONTRIBUTING.md），可以在 opencode.json 中通过 instructions 字段引用它们：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    ".cursor/rules/*.md",
    "docs/coding-style.md"
  ]
}

这些文件会被自动加载并注入到对话上下文中。它还支持远程 URL：

{
  "instructions": [
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}

第四层：auto_prompt.md（自动提示词）

auto_prompt.md 是藏在 .opencode/ 目录下的一个特殊文件——它会在每一次新会话启动时被自动读取并注入到 LLM 的系统上下文中。

这是四个层级中最"个人化"的一层。它不像 AGENTS.md 那样要共享给团队，也不像 instructions 字段那样面向项目的结构化规则。auto_prompt.md 的核心价值在于：它让每一次对话都带上你的身份、当前任务背景和特定的输出要求。

auto_prompt.md 详解

它的位置

auto_prompt.md 必须放在工作区的 .opencode/ 目录下：

你的项目/
├── .opencode/
│   ├── auto_prompt.md   ← 自动提示词
│   ├── agents/          ← 自定义 Agent
│   ├── commands/        ← 自定义命令
│   └── skills/          ← 自定义技能
├── AGENTS.md            ← 项目规则
├── opencode.json        ← 项目配置
└── src/
    └── ...

它的作用机制

当你在项目目录下执行 opencode 启动一个新会话时，OpenCode 会：

加载系统内置提示词

读取 AGENTS.md（如果存在）

读取 opencode.json 中 instructions 指定的文件

读取 .opencode/auto_prompt.md 的内容

将以上所有内容合并后，作为完整上下文一起发送给 LLM

这意味着，无论你开启多少个会话、切换到哪个 Agent（Build/Plan），auto_prompt.md 的内容都会始终跟随。它不适合放入 AGENTS.md 的内容的最佳去处——那些与特定任务模式相关、频繁变动、或纯个人工作流的提示。

auto_prompt.md 实战案例

案例一：个人技术博客作者的工作流

假设你是一名技术博客作者，你的项目仓库同时存放着博客工具脚本和草稿。你希望每次打开 OpenCode 时，AI 都自动进入"博客写作助手"的角色。

你的 .opencode/auto_prompt.md 可以这样写：

你是一名中文技术博客作者，博客域名为 www.linweiqin.com。

## 博客背景
这是一个个人技术博客，主要分享编程实践、工具使用、开源项目等技术内容。
目标读者是开发者群体，注重实用性和可操作性。

## 选题优先级
第一优先：OpenCode（AI 编程助手）的相关内容
  - 如果 OpenCode 相关主题还没覆盖完，优先写 OpenCode
  - 可写方向：基础配置、模型提供商选择、高级技巧、自定义工具、MCP 服务器等
  - 参考官网 opencode.ai 的最新特性和功能

第二优先：其他技术内容
  - PHP/Laravel 开发实战
  - Go 语言开发
  - Docker/K8s 运维
  - 前端/JavaScript/CSS
  - 数据库/Redis/MySQL

## 写作要求
1. 文章长度至少 800 字，内容详实、有深度
2. 使用中文写作，专业术语可保留英文
3. 代码块使用标准 Markdown 格式

## 已发布文章列表（请避免重复主题）
...（文章列表）

这样一来，每次你在项目中启动 OpenCode，AI 就已经处于"博客写作助手"的状态，知道你的写作风格、选题偏好和已发布内容——你只需要说"写一篇关于 XXX 的文章"，而不需要每次重复那整套写作规范。

案例二：前后端分离项目的全栈开发者

你是一名全栈开发者，同时负责前端和后端开发。

## 项目背景
这是一个电商后台管理系统，前后端分离架构。

## 技术栈
- 前端：React + TypeScript + Ant Design
- 后端：Go + Gin + GORM
- 数据库：MySQL + Redis
- 部署：Docker + K8s

## 编码偏好
- API 接口统一使用 RESTful 风格，路径前缀 /api/v1
- 错误处理先查 error，遵循 Go 惯例
- 前端组件使用函数式组件 + Hooks
- 数据库迁移使用 golang-migrate

## 当前任务焦点
本周在开发商品管理模块，重点实现：
- SKU 组合管理
- 批量导入/导出
- 库存预警通知

这种配置让 AI 自动进入"电商全栈开发者"的角色，知道技术栈、编码习惯和当前开发重点。

案例三：代码审查模式

你是一个严格的代码审查者。

## 审查原则
1. 先理解整体设计意图，再检查实现细节
2. 关注安全性和性能，不纠结无关紧要的格式问题
3. 每条建议必须附带改进方案或代码示例

## 重点关注
- SQL 注入、XSS、CSRF 等安全问题
- N+1 查询问题
- 缺少输入校验
- 不当的错误处理（吞掉异常、nil 引用）
- 并发不安全的数据访问
- 大文件/大对象未及时释放

## 忽略
- 命名风格争议（除非明显误导）
- 注释格式（除非缺少关键说明）
- 测试覆盖率争议（除非核心逻辑无测试）

然后配合注释掉的 build 和启用的 plan Agent，你就有了一个专门的代码审查会话。

auto_prompt.md vs AGENTS.md：何时用什么

这是很多用户感到困惑的地方。简单来说：

| 维度 | AGENTS.md | auto_prompt.md |
|------|-----------|----------------|
| 位置 | 项目根目录 | .opencode/auto_prompt.md |
| 提交到 Git | ✅ 应该 | ❌ 通常不提交 |
| 共享范围 | 全团队 | 个人 |
| 内容性质 | 项目架构、规范 | 当前任务、个人偏好 |
| 变动频率 | 低，项目级的元信息 | 高，可按需随时调整 |
| 典型内容 | 技术栈、目录结构、编码规范 | 角色设定、任务目标、输出格式要求 |

一个实用的判断标准：如果一段提示词会让你在团队 standup 上跟同事交流，就放 AGENTS.md；如果只是你自己的习惯和当前关注点，放 auto_prompt.md。

进阶技巧

1. 动态切换任务上下文

你的 auto_prompt.md 不需要是静态的。可以按开发阶段手动调整：

<!-- 新功能开发阶段 -->
## 当前阶段：功能开发
- 专注于实现功能，测试先写后补
- 优先保证接口正确，性能优化放第二阶段

<!-- 重构阶段 -->
## 当前阶段：代码重构
- 严格保持外部行为不变
- 每次改动后运行完整测试套件

2. 结合 Agent 使用

auto_prompt.md 是所有会话共享的。如果你想让不同 Agent 有不同的行为，应该使用 Agent 的 prompt 字段：

{
  "agent": {
    "code-reviewer": {
      "mode": "subagent",
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

auto_prompt.md 负责"你是谁"，Agent prompt 负责"具体做什么"。

3. 配合 Skill 系统

OpenCode 的 Skill 系统允许定义可复用的工作流。auto_prompt.md 中可以告诉 AI 何时应该调用某个 Skill：

## 可用技能
当你需要将文章发布到博客时，使用 blog-publish 技能，
按照 SKILL.md 中定义的完整流程执行：查询已有文章、推荐主题、编写内容、发布。

4. 保持简洁，避免上下文膨胀

这是一个常见陷阱：把 auto_prompt.md 写得又长又全，导致有效上下文被压缩。记住几个原则：

只写本次会话需要的信息。半年前的旧任务描述不要留着。
使用要点而非段落。AI 更擅长理解结构化的要点。
定期清理。完成当前阶段的任务后，更新 auto_prompt.md 中的"当前任务焦点"。

完整工作流示例

下面是一个完整的配置示例，展示 AGENTS.md、opencode.json 和 auto_prompt.md 如何协同工作。

AGENTS.md（项目根目录）

# ShopTrade 商城系统

基于微服务架构的电商平台。

## 目录结构
- `services/` - 微服务（user, product, order, payment）
- `gateway/` - API 网关
- `proto/` - gRPC 协议定义
- `deploy/` - K8s 部署配置

## 技术栈
- Go 1.22 + gRPC
- PostgreSQL + Redis
- Docker + Kubernetes

## 开发约定
- 使用 `make proto` 生成 protobuf 代码
- 使用 `make test` 运行所有测试
- 提交前执行 `make lint`

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "instructions": [".cursor/rules/*.md"]
}

.opencode/auto_prompt.md

你是一名 Go 后端开发工程师，负责 ShopTrade 商城系统的订单服务模块。

## 当前任务
本周在实现订单退款流程，核心需求：
1. 用户申请退款 → 商家审核 → 原路退款
2. 支持部分退款和全额退款
3. 退款状态需要实时通知用户

## 个人偏好
- 服务间通信优先 gRPC，异步场景用消息队列
- 错误处理遵循 Go 惯例：先查 error，用 fmt.Errorf 包裹
- 每个公开函数必须有 godoc 注释
- 金额计算用 decimal 类型，禁止用 float64

总结

auto_prompt.md 是 OpenCode 提示词体系中那个容易被忽视但极其实用的"螺丝钉"。它解决了三个核心痛点：

消除重复输入：不需要每个会话都说一遍"我是谁、我在做什么、我的偏好是什么"。

任务聚焦：把当前开发阶段的焦点写进 auto_prompt.md，AI 的输出会更贴近实际需求。

个人化定制：在团队共享的 AGENTS.md 之外，保留一块"私人的自留地"。

配合 AGENTS.md 和 opencode.json 的 instructions 字段，你可以构建一套分层的提示词体系：

项目共享层：AGENTS.md + instructions 字段 → 团队同频
个人定制层：auto_prompt.md → 每次会话自动注入
Agent 专属层：Agent prompt → 特定任务的指令

掌握了这套体系，你会发现 OpenCode 不再是一个"每次都要从头调教的助手"，而是一个真正懂你的 AI 编程搭档。

OpenCode 自动提示词系统实战：用 auto_prompt.md 打造个性化 AI 编程工作流

OpenCode 自动提示词系统实战：用 auto_prompt.md 打造个性化 AI 编程工作流

引言

OpenCode 提示词层级体系

第一层：系统内置提示词

第二层：AGENTS.md（项目规则）

第三层：opencode.json 的 instructions 字段

第四层：auto_prompt.md（自动提示词）

auto_prompt.md 详解

它的位置

它的作用机制

auto_prompt.md 实战案例

案例一：个人技术博客作者的工作流

案例二：前后端分离项目的全栈开发者

案例三：代码审查模式

auto_prompt.md vs AGENTS.md：何时用什么

进阶技巧

1. 动态切换任务上下文

2. 结合 Agent 使用

3. 配合 Skill 系统

4. 保持简洁，避免上下文膨胀

完整工作流示例

AGENTS.md（项目根目录）

opencode.json

.opencode/auto_prompt.md

总结

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客