OpenCode 自动提示词完全指南：用 auto_prompt.md 让 AI 助手"自带记忆"

OpenCode 自动提示词完全指南：用 auto_prompt.md 让 AI 助手"自带记忆"

引言

在日常使用 OpenCode 的过程中，你是否遇到过这样的场景：每开启一个新会话，都要手动告诉 AI 你的项目背景、代码规范、常用命令？或者你希望 OpenCode 在工作区中自动遵循某些特定规则，而不必每次都重复输入相同的提示词？

OpenCode 的自动提示词（Auto Prompt）功能正是为解决这一痛点而设计。通过在项目或全局目录下创建一个 auto_prompt.md 文件，你可以让 OpenCode 在每次对话开始时自动加载预设的上下文信息，让 AI 真正做到"自带记忆"，省去重复沟通的成本。

什么是 auto_prompt.md？

auto_prompt.md 是 OpenCode 提供的一个自动注入文档。当你在项目根目录的 .opencode/ 文件夹下放置该文件后，OpenCode 会在启动会话时读取其内容，并将其作为系统级别的上下文注入到 AI 模型的对话历史中。

简单来说，auto_prompt.md 中写下的每一个字，都会在每次对话中被 AI 读取并遵循，无需你手动重复输入。

核心特性

• 项目级别作用域：放在 .opencode/auto_prompt.md 下，仅对当前项目生效
• 全局级别作用域：放在 ~/.config/opencode/auto_prompt.md 下，对所有项目生效
• 自动加载：每次新建会话或打开已有会话时自动注入
• Markdown 格式：使用标准 Markdown 编写，支持标题、列表、代码块等

创建和配置 auto_prompt.md

第一步：创建文件

在项目根目录下创建 .opencode/ 目录（如果不存在），然后在其中新建 auto_prompt.md 文件：

mkdir -p .opencode
touch .opencode/auto_prompt.md

第二步：编写内容

根据你的项目需求填充内容。下面是一个典型的示例：

你是一名资深后端开发工程师，主要职责是维护和改进本项目的 API 服务。

## 项目背景
本项目是一个基于 Go 语言的微服务系统，使用 Gin 框架，数据库为 PostgreSQL。
部署在 Kubernetes 集群上，CI/CD 使用 GitHub Actions。

## 编码规范
- 函数命名使用骆驼式（camelCase）
- 错误处理必须显式，禁止忽略 error 返回值
- 所有导出函数必须有文档注释
- 使用 context.Context 传递请求上下文

## 常用命令
- 启动服务：`go run cmd/server/main.go`
- 运行测试：`go test ./...`
- 代码检查：`golangci-lint run`
- 数据库迁移：`go run cmd/migrate/main.go`

## 注意事项
- config.yaml 中的密钥信息已脱敏，不要修改
- proto 文件由 protoc 自动生成，禁止手动编辑
- 日志统一使用 logrus，不要引入其他日志库

第三步：验证

保存文件后，打开一个新的 OpenCode 会话。AI 会在对话开始时自动获取这些信息，并在回答中遵循你设定的规则。

自动提示词的工作原理

了解工作原理有助于你更好地利用这个功能：

会话初始化阶段：当 OpenCode 启动一个新会话或加载已有会话时，会扫描配置目录

文件读取：读取 .opencode/auto_prompt.md 的内容

内容注入：将文件内容作为系统提示词（system prompt）的一部分，追加到 AI 模型的上下文窗口中

持续生效：在整个对话过程中，AI 都会记住并遵循 auto_prompt.md 中的指令

需要注意的是，auto_prompt.md 的注入优先级在项目配置和全局配置之间有所不同：

用户当前消息 > auto_prompt.md（项目级） > auto_prompt.md（全局级） > opencode.json 配置

当项目级和全局级同时存在时，项目级的内容会追加在全局级之后，两者不会互相覆盖。

实战场景

场景一：多语言项目的编码规范统一

假设你同时维护一个包含 TypeScript 前端和 Go 后端的项目：

你是一名全栈工程师，需要同时处理前端和后端代码。

## 前端规范（TypeScript/React）
- 组件使用函数式声明，使用 FC<Props> 类型标注
- 样式使用 CSS Modules，文件命名 *.module.css
- 异步请求统一使用项目封装的 useRequest hook
- 测试使用 Vitest + React Testing Library

## 后端规范（Go）
- handler -> service -> repository 三层架构
- 统一使用 github.com/pkg/errors 包装错误
- API 响应格式遵循项目内部 apiresp 包规范
- 单元测试覆盖率不低于 80%

场景二：自动化写作工作流

如果你像我一样用 OpenCode 来辅助写作或维护博客，可以这样配置：

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

## 写作要求
1. 文章长度至少 800 字，内容详实、有深度
2. 使用中文写作，专业术语可保留英文
3. 代码块使用标准 Markdown 格式
4. 包含实际可运行的命令或代码示例
5. 结构清晰：有引言、正文分节、总结

这样一来，每次让 OpenCode 写文章时，它会自动遵循你的写作风格和格式要求。

场景三：运维脚本开发规范

对于 DevOps 工程师或 SRE 团队，可以预设脚本规范：

你是一名 DevOps 工程师，负责编写和维护自动化脚本。

## 脚本规范
- 使用 Bash，shebang 统一为 #!/usr/bin/env bash
- 必须包含 set -euo pipefail
- 错误处理使用 trap 捕获
- 所有脚本必须有 --help 参数
- 使用 shellcheck 进行静态检查

场景四：代码审查辅助

让 OpenCode 在审查代码时自动应用团队规范：

你是一名代码审查员。

## 审查重点
- SQL 查询是否使用了参数绑定，是否存在注入风险
- 是否有未处理的错误返回
- 是否有硬编码的密钥或配置
- 循环中是否有不必要的数据库调用（N+1 问题）
- API 接口是否有合适的限流和超时设置

高级技巧

1. 分层配置：项目级 + 全局级

在全局级 auto_prompt.md（~/.config/opencode/）中放置通用规范——如代码风格、命名约定——而在项目级 auto_prompt.md 中放置项目特有信息——如技术栈、目录结构、常用命令。这样可以避免在每个项目中重复编写相同的内容。

2. 结合 Skills 系统

如果你的项目使用了 OpenCode 的 Skills 系统，可以在 auto_prompt.md 中说明：

本项目定义了以下自定义技能（Skills），请在需要时加载：
- blog-publish：将文章发布到博客
- deploy-staging：部署到测试环境

3. 利用变量和占位符

虽然 auto_prompt.md 不直接支持动态变量，但你可以通过清晰的标记让 AI 理解上下文：

当前项目根目录：/home/user/projects/backend
配置文件位置：.opencode/opencode.json
主要入口文件：cmd/server/main.go

4. 及时更新

项目在演进，auto_prompt.md 也应该随之更新。建议在以下时机检查和更新：

• 新增或移除依赖
• 调整代码规范
• 切换部署方式
• 团队新成员加入

5. 控制长度

虽然 OpenCode 支持很长的上下文窗口，但过长的 auto_prompt.md 会消耗大量 token，可能影响后续对话的可用空间。建议控制在 500-1500 字之间，聚焦最重要的信息。

与其他配置方式的对比

| 特性 | auto_prompt.md | opencode.json | 每次手动输入 |
|------|---------------|---------------|-------------|
| 自动加载 | ✅ | ✅ | ❌ |
| 格式化灵活性 | ✅ Markdown | 部分（JSON 限制） | ✅ |
| 结构化配置 | 低 | ✅ 高 | 无 |
| 适合场景 | 项目背景、编码规范 | 模型设置、权限、工具 | 临时指令 |

简而言之：opencode.json 适合结构化配置（选择模型、设置权限、定义技能），而 auto_prompt.md 适合自然语言描述（项目背景、编码规范、工作流说明）。两者协同使用，各司其职。

总结

auto_prompt.md 是 OpenCode 中一个简单却极为实用的功能。它让你可以将重复性的人工提示工作标准化、自动化，让 AI 助手在每一次对话开始时就已经"了解"你的项目背景和编码习惯。

关键要点回顾：

• 在 .opencode/auto_prompt.md 中编写项目专属的上下文信息
• 支持项目级和全局级双层配置
• 使用 Markdown 格式，内容灵活
• 结合 opencode.json 的结构化配置，形成完整的项目设定
• 保持内容精简，聚焦核心信息

还在每次对话时手动粘贴项目背景吗？不妨现在就创建一个 auto_prompt.md，让 OpenCode 自动记住这一切。