💡 一句话总结:创建一个规则文件,AI 每次发消息都会读取,不用重复说"用中文回复"。
📝 课程笔记#

学完你能做什么#
你现在的困境#
什么时候用这一招#
🎒 开始前的准备#
核心思路#
什么是"规则文件"?#
规则文件就是一个 Markdown 文件,里面写着你希望 AI 遵守的规则。OpenCode 会自动读取这个文件,把内容加到系统提示词里。规则是热加载的!#
规则文件修改后立即生效,不需要重启 OpenCode,也不需要新建会话!
OpenCode 在每次发送消息时都会重新读取规则文件。这意味着:| 操作 | 是否需要 |
|---|
| 修改规则后重启 OpenCode | ❌ 不需要 |
| 修改规则后新建会话 | ❌ 不需要 |
| 修改规则后发下一条消息 | ✅ 这就够了 |
实际效果:你让 AI 帮你更新了规则文件后,直接发下一条消息,新规则就会生效。三种作用域#
OpenCode 支持三种作用域的规则,满足不同场景:| 作用域 | 位置 | 适用场景 |
|---|
| 全局规则 | ~/.config/opencode/AGENTS.md | 所有项目通用的偏好 |
| 项目规则 | 项目根目录 AGENTS.md | 项目特定的规范 |
| 配置文件 | opencode.json 的 instructions 字段 | 引用多个规则文件 |
::: info 🤔 为什么叫 AGENTS.md?
OpenCode 同时支持 AGENTS.md 和 CLAUDE.md(兼容 Claude Code)。推荐用 AGENTS.md,这是 OpenCode 的标准名称。
:::规则加载顺序#
规则按以下顺序加载,后加载的会补充(不是覆盖)前面的:1. 全局 ~/.config/opencode/AGENTS.md
2. 全局 ~/.claude/CLAUDE.md(兼容模式)
3. 项目目录向上查找 AGENTS.md / CLAUDE.md
4. 配置文件 instructions 指定的文件
跟我做#
不用离开 OpenCode!直接让 AI 帮你创建规则文件,这是最简单的方式。
第 1 步:让 AI 帮你创建全局规则#
为什么
既然已经在用 OpenCode,直接让 AI 帮你写文件最方便。帮我创建全局规则文件 ~/.config/opencode/AGENTS.md,内容是:
始终使用简体中文回复
你应该看到:AI 会帮你创建目录和文件,并写入规则。::: details 📦 AI 会做什么?
AI 会执行类似这样的操作:1.
检查 ~/.config/opencode/ 目录是否存在
第 2 步:验证规则生效#
因为规则是热加载的,AI 帮你创建文件后,下一条消息就会遵守新规则。不需要新建会话!
问 AI:"你现在遵守哪些规则?"它会列出系统提示词里的规则。
第 3 步:完善你的规则#
帮我更新全局规则文件 ~/.config/opencode/AGENTS.md,改成:
## 语言和风格
- 始终使用简体中文回复
- 直接回答问题,不要客套话
- 代码注释也用中文
## 代码规范
- 使用 2 空格缩进
- 变量名用驼峰命名(camelCase)
- 函数名用动词开头(如 getUserById)
## 工作习惯
- 修改代码前先阅读相关文件
- 不确定时先问,不要猜测
- 每次只做最小必要的修改
第 4 步:(可选)创建项目规则#
帮我在项目根目录创建 AGENTS.md,内容是:
# 项目规则
## 技术栈
- 前端:React + TypeScript
- 后端:NestJS
- 数据库:PostgreSQL
## 代码规范
- 使用项目的 ESLint 配置
- 组件文件用 PascalCase 命名
- API 路由用 kebab-case
你应该看到:在这个项目里,AI 会同时遵守全局规则和项目规则。第 5 步:(可选)用 /init 自动生成项目规则#
为什么
如果你不知道该写什么规则,让 AI 分析项目自 动生成。你应该看到:AI 会分析你的项目结构、技术栈、代码风格,自动生成一份 AGENTS.md。::: info 🤔 /init 生成的内容
AI 会分析:已有的 Cursor/Copilot 规则(如果有)
生成的规则大约 150 行,涵盖项目最重要的规范。
:::
实用规则示例#
以下是一些实战中验证有效的规则,可以直接复制使用:通用开发规则#
代码质量规则#
工作流程规则#
高级用法:配置文件引用#
如果你的规则分散在多个文件,可以用配置文件统一引用:
{
"instructions": [
"CONTRIBUTING.md",
"docs/coding-standards.md",
".cursor/rules/*.md",
"~/my-rules/common.md"
]
}
绝对路径:~/my-rules/common.md
Glob 模式:.cursor/rules/*.md
URL:https://example.com/rules.md
通过 instructions 引用规则文件的路径列表是在会话启动时加载的。如果你在 opencode.json 中新增或修改了 instructions 条目,需要开启新会话才能生效。但已加载路径的文件内容是热加载的——修改规则文件本身,下一条消息就会生效。
如果你之前用过 Cursor,可以直接引用 .cursor/rules/*.md,规则直接复用。
检查点 ✅#
踩坑提醒#
| 现象 | 原因 | 解决 |
|---|
| 规则没生效 | 文件路径错误 | 确认是 ~/.config/opencode/AGENTS.md,不是 ~/.opencode/ |
| 部分规则被忽略 | 规则太长,被截断 | 精简规则,只保留重要的 |
| 规则冲突 | 全局和项目规则矛盾 | 项目规则写得更具体,覆盖全局 |
| 中文乱码 | 文件编码不是 UTF-8 | 用 UTF-8 编码保存文件 |
本课小结#
1.
直接让 AI 写规则:在 OpenCode 里说"帮我创建规则文件",最简单
2.
规则是热加载的:修改后立即生效,不需要重启或新建会话
3.
三种作用域:全局(~/.config/opencode/)、项目(项目根目录)、配置文件
想要更多?#
下一课预告#
附录:源码参考#
点击展开查看源码位置
SessionPrompt.prompt() 在每次用户发消息时调用
调用链:prompt() → loop() → processor.process() → SystemPrompt.custom()
SystemPrompt.custom() 每次都重新读取文件,没有缓存
CLAUDE.md - 兼容 Claude Code
1.
$OPENCODE_CONFIG_DIR/AGENTS.md(如设置了环境变量)
2.
~/.config/opencode/AGENTS.md
项目规则查找:从当前目录向上逐级查找,直到找到文件或到达根目录。