Skip to content
OpenCode 中文文档
HomeDocs

规则

为 OpenCode 设置自定义指令。

你可以通过创建一个 AGENTS.md 文件来向 OpenCode 提供自定义指令。这类似于 CLAUDE.md 或 Cursor 的规则。它包含了将被包含在 LLM 上下文中的指令，以针对你的特定项目定制其行为。

初始化

要创建一个新的 AGENTS.md 文件，你可以在 OpenCode 中运行 /init 命令。

这将扫描你的项目及其所有内容，以了解项目的内容并生成一个 AGENTS.md 文件。这有助于 OpenCode 更好地导航项目。

如果你已经有一个现有的 AGENTS.md 文件，这将尝试向其中添加内容。

示例

你也可以手动创建此文件。以下是一些你可以放入 AGENTS.md 文件中的示例。

AGENTS.md
# SST v3 Monorepo 项目


这是一个使用 TypeScript 的 SST v3 monorepo。该项目使用 bun workspaces 进行包管理。


## 项目结构


- `packages/` - 包含所有工作区包（functions, core, web 等）
- `infra/` - 按服务拆分的底层设施定义 (storage.ts, api.ts, web.ts)
- `sst.config.ts` - 带有动态导入的主 SST 配置


## 代码标准


- 使用启用严格模式的 TypeScript
- 共享代码放在 `packages/core/` 中，并带有适当的导出配置
- 函数放在 `packages/functions/` 中
- 底层设施应拆分为 `infra/` 中逻辑清晰的文件


## Monorepo 约定


- 使用工作区名称导入共享模块：`@my-app/core/example`

我们在这里添加了项目特定的指令，这些指令将会在你的团队中共享。

类型

OpenCode 还支持从多个位置读取 AGENTS.md 文件，这服务于不同的目的。

项目级

我们在上面看到的，将 AGENTS.md 放置在项目根目录中的是项目特定的规则。这些规则仅在你在此目录或其子目录中工作时生效。

全局级

你也可以在 ~/.config/opencode/AGENTS.md 文件中设置全局规则。这将应用于所有的 OpenCode 会话。

由于这不会提交到 Git 或与你的团队共享，我们建议使用它来指定 LLM 应遵循的任何个人规则。

优先级

当 OpenCode 启动时，它会查找：

  1. 从当前目录向上遍历的 本地文件
  2. 检查 ~/.config/opencode/AGENTS.md 的 全局文件

如果你同时拥有全局和项目特定的规则，OpenCode 将它们合并在一起。

自定义指令

你可以在 opencode.json 或全局的 ~/.config/opencode/opencode.json 中指定自定义指令文件。这允许你和你的团队重用现有的规则，而无需将它们复制到 AGENTS.md 中。

示例：

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

所有指令文件都会与你的 AGENTS.md 文件合并。

引用外部文件

虽然 OpenCode 不会自动解析 AGENTS.md 中的文件引用，但你可以通过两种方式实现类似的功能：

使用 opencode.json

推荐的方法是使用 opencode.json 中的 instructions 字段：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["docs/development-standards.md", "test/testing-guidelines.md", "packages/*/AGENTS.md"]
}

在 AGENTS.md 中手动指示

你可以通过在 AGENTS.md 中提供明确的指令来教 OpenCode 读取外部文件。这是一个实际的例子：

AGENTS.md
# TypeScript 项目规则


## 外部文件加载


关键：当你遇到文件引用（例如 @rules/general.md）时，请使用你的 Read 工具根据需要加载它。它们与当前特定的任务相关。


指令：


- 不要预先加载所有引用 - 根据实际需要使用延迟加载
- 加载后，将内容视为覆盖默认值的强制性指令
- 在需要时递归遵循引用


## 开发指南


关于 TypeScript 代码风格和最佳实践：@docs/typescript-guidelines.md
关于 React 组件架构和 hooks 模式：@docs/react-patterns.md
关于 REST API 设计和错误处理：@docs/api-standards.md
关于测试策略和覆盖率要求：@test/testing-guidelines.md


## 通用指南


立即阅读以下文件，因为它与所有工作流程相关：@rules/general-guidelines.md。

这种方法允许你：

  • 创建模块化、可重用的规则文件
  • 通过符号链接或 git 子模块跨项目共享规则
  • 保持 AGENTS.md 简洁，同时引用详细的指南
  • 确保 OpenCode 仅在特定任务需要时才加载文件

忽略文件

你可以使用 .opencodeignore 文件来指定 OpenCode 应该忽略的文件。这类似于 .gitignore。

这将防止 OpenCode 扫描或索引这些文件，这对于大型目录或生成的文件非常有用。