Open Code 文档

主题

首页文档搜索

OpenCode 规则编写实战教程：让 AI 助手稳定遵循你的项目约定 ​

📚 分类: OpenCode 规则配置 ⏱️ 预计耗时: 30 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode 的终端环境

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 理解 OpenCode 中 AGENTS.md 文件的核心作用
  • [ ] 区分并正确配置“项目规则”和“全局规则”
  • [ ] 掌握 Claude Code 规则文件的兼容用法
  • [ ] 学会使用外部文件 instructions 来组织复杂规则
  • [ ] 独立编写一个健康、高效的 AGENTS.md 文件

最终效果 ​

你将能够为自己的项目创建一个结构清晰、内容精炼的 AGENTS.md 文件。当 AI 助手（Agent）在此项目中工作时，它将自动读取该文件，并严格按照你设定的规则行事，比如使用正确的命令、不修改特定目录的文件等。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求版本验证命令
OpenCode任意版本opencode --version
一个 Git 项目任意版本用于放置规则文件

1. 准备一个示例项目 ​

为了练习，我们创建一个简单的项目。

bash
# 创建一个新目录并进入
$ mkdir my-awesome-project && cd my-awesome-project

# 初始化一个简单的 Node.js 项目（或使用你的任何项目）
$ npm init -y

✅ 验证：你的项目目录下应出现 package.json 文件。

第 1 步：理解规则的核心入口 —— AGENTS.md ​

🎯 目标：理解 AGENTS.md 是什么，以及它应该（和不应该）包含什么内容。

📝 操作：

规则是给 AI Agent 的行为说明书。它的核心入口是 AGENTS.md 文件，放在项目根目录下。它的目标是回答 Agent 在项目中反复遇到的问题，而不是成为项目百科。

🤔 为什么要这样做？ Agent 每次进入项目都需要知道如何构建、测试和遵守约定。AGENTS.md 提供了一个快速、可靠的参考点，避免 Agent 重复猜测或产生错误行为。

应该写 vs 不应该写：

应该写不应该写
build / lint / test 等命令真实的 API Key、密码、Token
关键目录的职责和入口文件一次性任务的目标
包管理器（npm, yarn, pnpm）和运行方式README.md 已经讲清的背景知识
修改边界（哪些文件不能动）和禁止操作过时的历史决策和争论
验证顺序和常见错误个人编码风格偏好
需要按需读取的外部规范整个团队的完整手册

✅ 验证： 现在你可以在脑海中形成一个判断标准：未来 10 次任务都应该遵守的内容，才值得写进规则。 只对当前任务有效的要求，留在对话里。

💡 提示：OpenCode 官方提供 /init 命令，可以扫描你的项目并自动生成 AGENTS.md 草稿。你可以尝试在你的项目根目录下运行 opencode /init，然后查看它生成的内容。

第 2 步：区分项目规则与全局规则 ​

🎯 目标：理解两种规则的作用域，并知道它们应该放在哪里。

📝 操作：

规则分为“项目规则”和“全局规则”，两者服务于不同的场景。

类型路径是否适合提交到 Git适合放什么
项目规则AGENTS.md (项目根目录)是团队共享的项目命令、目录约定、验证顺序
全局规则~/.config/opencode/AGENTS.md否个人偏好、个人常用工具习惯

🤔 为什么要这样区分？

  • 项目规则是团队协作的基础，必须和代码一起管理，确保所有开发者（以及他们的AI助手）行为一致。
  • 全局规则是你的个人配置，不应该强加给团队，也不应该把某个特定项目的命令写进去。

✅ 验证： 在你的项目根目录下创建 AGENTS.md 文件（如果还没有）。在 ~/.config/opencode/ 目录下检查是否有 AGENTS.md 文件（如果没有，可以手动创建）。

⚠️ 常见错误：

  • ❌ 在项目 AGENTS.md 里写你的个人编辑器快捷键。
  • ❌ 在全局 AGENTS.md 里写某个项目的专属 deploy 命令。

第 3 步：了解规则读取的优先级 ​

🎯 目标：掌握 OpenCode 如何查找和应用规则，包括对 Claude Code 的兼容。

📝 操作：

OpenCode 启动时，会按照以下优先级查找规则文件：

  1. 项目目录 → 向上查找 AGENTS.md。
  2. 找到 AGENTS.md → 项目规则生效。
  3. 未找到 AGENTS.md → 查找 CLAUDE.md（Claude Code 的规则文件）。
  4. 找到 CLAUDE.md → Claude 项目兼容规则生效。
  5. 未找到任何本地规则 → 读取全局规则。
  6. 全局规则 → 优先读取 ~/.config/opencode/AGENTS.md。
  7. 未找到 OpenCode 全局规则 → 读取 ~/.claude/CLAUDE.md（Claude 全局兼容）。

💡 关键点：

  • 同一目录下，AGENTS.md 的优先级高于 CLAUDE.md。
  • 全局规则中，OpenCode 的规则文件优先级高于 Claude 的。

✅ 验证： 你可以通过创建一个 CLAUDE.md 文件来测试这个兼容性。创建一个简单的 CLAUDE.md 文件，内容为 # Claude Rules。然后运行 OpenCode，观察它是否会读取到这个文件（前提是你没有 AGENTS.md）。

⚠️ 关闭 Claude Code 兼容： 如果你不希望使用 Claude 兼容功能，可以设置以下环境变量：

bash
export OPENCODE_DISABLE_CLAUDE_CODE=1
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1

第 4 步：使用外部文件管理复杂规则 (instructions) ​

🎯 目标：学会使用 opencode.json 中的 instructions 字段来引用外部规则文件，保持 AGENTS.md 的简洁。

📝 操作：

当规则很多时，不要全部塞进 AGENTS.md。你可以在项目根目录的 opencode.json 文件中，通过 instructions 字段引用外部文件。

1. 创建一个外部规则文件

创建一个 docs/development-standards.md 文件，内容如下：

markdown
# 开发标准

- 所有组件必须使用 TypeScript 编写。
- 单元测试覆盖率必须达到 80% 以上。

2. 编辑 opencode.json

在项目根目录创建或编辑 opencode.json 文件：

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

💡 提示：

  • instructions 也支持引用远程 URL，例如："https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"。
  • 但是，远程文件有 5 秒超时限制，如果拉取失败，Agent 将不会应用这些规则。核心约束必须放在项目本地的 AGENTS.md 中。

✅ 验证： 保存文件后，Agent 在下次启动时就会自动加载这些外部规则文件。

⚠️ 常见错误：

  • ❌ 把包含敏感信息的文件添加到 instructions 中。
  • ❌ 依赖远程 instructions 来执行关键的安全约束。

第 5 步：编写一个健康的 AGENTS.md ​

🎯 目标：根据模板，为你的项目编写一个精炼、可执行的 AGENTS.md 文件。

📝 操作：

在你的项目根目录下，创建或编辑 AGENTS.md 文件，内容如下：

markdown
# Project Instructions

## What This Project Is

一个使用 Next.js 构建的博客系统，用于发布技术文章。

## Common Commands

- `pnpm run dev` : 启动开发服务器
- `pnpm run build` : 构建生产版本
- `pnpm run lint` : 运行代码检查
- `pnpm run test` : 运行单元测试

## Important Paths

- `src/app/` : 路由和页面入口
- `src/components/` : 共享 UI 组件
- `content/posts/` : Markdown 文章源文件

## Working Rules

- 不要手动编辑 `public/` 目录下的生成文件。
- 所有内容变更必须放在对应的产品目录下。
- 在 `build` 之前，必须先运行 `pnpm run lint` 和 `pnpm run test`。

🤔 为什么要这样写？

  • 短：只包含 Agent 最需要知道的信息。
  • 可执行：每个条目都是明确的指令或路径。
  • 能指导下一步：Agent 知道先做什么（lint），再做什么（test），最后做什么（build）。

✅ 验证： 保存文件后，你可以让 Agent 执行一个任务（例如“帮我创建一个新的文章”），观察它是否会按照 Important Paths 中的 content/posts/ 目录来操作。

进阶技巧（可选） ​

  1. 利用 /init 命令：在项目根目录运行 opencode /init，让 AI 自动扫描并生成 AGENTS.md 草稿。生成后必须人工审查，检查命令是否真实、路径是否准确、是否泄露了敏感信息。

  2. 使用通配符引用：在 instructions 中，你可以使用通配符 * 来匹配多个文件，例如 .cursor/rules/*.md 会引用 .cursor/rules/ 目录下的所有 Markdown 文件。

常见问题 (FAQ) ​

Q1: 运行 /init 后，生成的 AGENTS.md 太长了怎么办？A: 这是常见问题。你需要进行人工裁剪，只保留最核心的命令、路径和规则。将长篇的规范文档移到外部文件，并通过 instructions 引用。

Q2: 我同时有 AGENTS.md 和 CLAUDE.md，团队不知道哪个生效，怎么办？A: 选择其中一个作为主入口（推荐 AGENTS.md），在另一个文件中添加引用说明，例如：“本项目的核心规则请参考 AGENTS.md”。避免长期维护两套互相冲突的规则。

Q3: 规则只写了“不要做什么”，没有写验证顺序，怎么办？A: 这是一个常见误区。好的规则应该告诉 Agent 先做什么，再做什么。例如，在 Working Rules 中明确写出：“在 build 之前，必须先运行 pnpm run lint 和 pnpm run test。”

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 核心入口：AGENTS.md 是给 Agent 的行为说明书，要短、可执行。
  2. 规则分层：项目规则（AGENTS.md）服务团队，全局规则（~/.config/opencode/AGENTS.md）服务个人。
  3. 优先级：项目规则 > 全局规则，AGENTS.md > CLAUDE.md。
  4. 外部管理：使用 opencode.json 的 instructions 字段管理复杂规则，保持核心文件简洁。
  5. 健康标准：一个健康的规则文件能让新人快速上手，让 Agent 稳定工作。

下一步 ​

如果你想继续深入，建议学习：

  • 📖 [使用 Agent Skills](链接到相关的 Agent Skills 教程)：规则是长期约束，可复用的流程应该沉淀为 Skill。
  • 📖 配置、Rules 与自定义命令：更完整地理解 config、rules、instructions 和 commands 之间的关系。

💡 练习任务：为你手头正在进行的项目编写一个 AGENTS.md 文件，并邀请一个同事来审查，看看他是否能根据你的规则文件快速了解项目。这是巩固知识的最佳方式。

yaml

## 相关文档

- [OpenCode 工具系统实战教程：从内置到扩展](/docs/gao-ji-pei-zhi/opencode-gong-ju-xi-tong-shi-zhan-jiao-cheng-cong-nei-zhi-dao-kuo-zhan.html)
- [Opencode 智能体 (Agent) 与 AGENTS.md 实战教程](/docs/gao-ji-pei-zhi/opencode-zhi-neng-ti-agent-yu-agents-md-shi-zhan-jiao-cheng.html)

Open Code 文档社区

© 2026 Open Code. All rights reserved.