规则

为 opencode 设置自定义指令。

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

# 初始化#

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

提示： 你应该将项目的 AGENTS.md 文件提交到 Git。

这将扫描你的项目及其所有内容，以了解项目是关于什么的，并生成包含这些信息的 AGENTS.md 文件。这有助于 opencode 更好地导航项目。

如果你有现有的 AGENTS.md 文件，这将尝试添加到它。

# 示例#

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

markdown
1<!-- AGENTS.md -->
2# SST v3 Monorepo 项目
3
4这是一个使用 TypeScript 的 SST v3 monorepo。项目使用 bun workspaces 进行包管理。
5
6## 项目结构
7
8- `packages/` - 包含所有工作区包（functions、core、web 等）
9- `infra/` - 按服务拆分的基础设施定义（storage.ts、api.ts、web.ts）
10- `sst.config.ts` - 带有动态导入的主 SST 配置
11
12## 代码标准
13
14- 使用启用严格模式的 TypeScript
15- 共享代码放在 `packages/core/` 中，带有适当的导出配置
16- 函数放在 `packages/functions/` 中
17- 基础设施应该按逻辑文件拆分到 `infra/` 中
18
19## Monorepo 约定
20
21- 使用工作区名称导入共享模块：`@my-app/core/example`

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

# 类型#

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

## 项目#

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

## 全局#

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

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

# 优先级#

所以当 opencode 启动时，它会查找：

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

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

# 自定义指令#

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

示例：

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

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

# 引用外部文件#

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

## 使用 opencode.json#

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

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "instructions": [
4    "docs/development-standards.md",
5    "test/testing-guidelines.md",
6    "packages/*/AGENTS.md"
7  ]
8}

## 在 AGENTS.md 中的手动指令#

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

markdown
1<!-- AGENTS.md -->
2# TypeScript 项目规则
3
4## 外部文件加载
5
6关键：当你遇到文件引用（例如 @rules/general.md）时，使用 Read 工具按需加载它。它们与特定任务相关。
7
8指令：
9- 不要预先加载所有引用 - 根据实际需要使用延迟加载
10- 加载后，将内容视为覆盖默认值的强制指令
11- 需要时递归跟踪引用
12
13## 开发指南
14
15TypeScript 代码风格和最佳实践：@docs/typescript-guidelines.md
16React 组件架构和 hooks 模式：@docs/react-patterns.md
17REST API 设计和错误处理：@docs/api-standards.md
18测试策略和覆盖率要求：@test/testing-guidelines.md
19
20## 通用指南
21
22立即阅读以下文件，因为它与所有工作流相关：@rules/general-guidelines.md。

这种方法允许你：

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

提示： 对于 monorepos 或具有共享标准的项目，使用带有 glob 模式的 opencode.json（如 packages/*/AGENTS.md）比手动指令更易维护。

规则

相关文档