Skip to content
OpenCode
首页文档

规则

为 opencode 设置自定义指令。

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

初始化

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

这将扫描您的项目及其所有内容，以了解项目概况，并生成一个包含这些信息的 AGENTS.md 文件。这有助于 opencode 更好地导航项目。

如果您已有一个现有的 AGENTS.md 文件，此命令将尝试对其进行补充。

示例

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

AGENTS.md
# SST v3 单体仓库项目


这是一个使用 TypeScript 的 SST v3 单体仓库项目。项目使用 bun workspaces 进行包管理。




## 项目结构


- `packages/` - 包含所有工作区包（函数、核心、web 等）
- `infra/` - 按服务拆分的基础设施定义（storage.ts, api.ts, web.ts）
- `sst.config.ts` - 主 SST 配置，使用动态导入




## 代码标准


- 使用启用严格模式的 TypeScript
- 共享代码放在 `packages/core/` 中，并配置正确的导出
- 函数放在 `packages/functions/` 中
- 基础设施应拆分为 `infra/` 中的逻辑文件




## 单体仓库约定


- 使用工作区名称导入共享模块：`@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），请根据需要，使用你的读取工具来加载它。这些引用仅与当前具体任务相关。

操作说明：

  • 不要预先加载所有引用 - 请根据实际需要进行延迟加载
  • 加载后，将内容视为必须遵循的指令，它将覆盖默认设置
  • 需要时，请递归地遵循引用

开发指南

关于 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 仅在特定任务需要时才加载文件


:::tip
对于使用共享标准的 monorepo 或项目，在 `opencode.json` 中使用 glob 模式（如 `packages/*/AGENTS.md`）比手动指令更易于维护。
:::