你可以通过创建一个 AGENTS.md 文件，为 opencode 提供自定义指令（custom instructions）。这与 CLAUDE.md 或 Cursor 的 rules 类似。该文件包含的指令会被注入到 LLM 的 context 中，用于为你的特定项目定制它的行为。

Initialize（初始化）

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

该命令会扫描你的项目及其所有内容，以理解项目是做什么的，并基于扫描结果生成一个 AGENTS.md 文件。这有助于 opencode 更好地在项目中导航。

如果你已经存在一个 AGENTS.md 文件，该命令会尝试在原有基础上追加内容。

Example（示例）

你也可以手动创建该文件。下面是一个可以写入 AGENTS.md 的示例内容。

```markdown title=”AGENTS.md”

SST v3 Monorepo Project

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

Project Structure（项目结构）

  • packages/ - 包含所有 workspace packages（functions、core、web 等）
  • infra/ - 按 service 拆分的基础设施定义（storage.ts、api.ts、web.ts）
  • sst.config.ts - 主 SST 配置，使用 dynamic imports

Code Standards（代码规范）

  • 使用开启 strict mode 的 TypeScript
  • 共享代码放在 packages/core/ 中，并配置正确的 exports
  • Functions 放在 packages/functions/
  • Infrastructure 应拆分到 infra/ 中的逻辑文件

Monorepo Conventions（Monorepo 约定）

  • 使用 workspace 名称导入共享模块，例如：@my-app/core/example ```

这里添加的是项目级别的指令，这些内容会在团队中共享。

Types（类型）

opencode 支持从多个位置读取 AGENTS.md 文件，并用于不同用途。

Project（项目级）

前面提到的这种放在项目根目录下的 AGENTS.md，属于 project-specific rules。只有当你在该目录或其子目录中工作时，这些规则才会生效。

Global（全局级）

你也可以在 ~/.config/opencode/AGENTS.md 中配置 global rules，它会应用于所有 opencode session。

由于该文件不会提交到 Git，也不会在团队中共享，推荐在这里放置个人偏好的规则，让 LLM 按你的个人习惯工作。

Precedence（优先级）

当 opencode 启动时，它会按以下顺序查找规则：

  1. 从当前目录开始向上遍历查找 local files
  2. 查找 global file：~/.config/opencode/AGENTS.md

如果同时存在 global rules 和 project-specific rules，opencode 会将它们合并使用。

Custom Instructions（自定义指令）

你可以在 opencode.json 或全局配置文件 ~/.config/opencode/opencode.json 中指定额外的指令文件。这样你和团队就可以复用已有规则，而无需复制到 AGENTS.md 中。

示例：

```json title=”opencode.json” { “$schema”: “https://opencode.ai/config.json“, “instructions”: [“CONTRIBUTING.md”, “docs/guidelines.md”, “.cursor/rules/*.md”] }

  2. 你也可以使用 remote URLs，从 web 加载指令文件。
  4. ```json title="opencode.json"
  5. {
  6.   "$schema": "https://opencode.ai/config.json",
  7.   "instructions": ["https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"]
  8. }

remote instructions 会以 5 秒超时进行拉取。

所有 instruction files 会与 AGENTS.md 文件一起合并生效。

Referencing External Files（引用外部文件）

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

使用 opencode.json（推荐方式）

推荐在 opencode.json 中使用 instructions 字段：

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

  2. ---
  4. ### 在 AGENTS.md 中手动声明规则
  6. 你可以在 `AGENTS.md` 中通过明确指令，教会 opencode 如何读取外部文件。以下是一个实用示例：
  8. ```markdown title="AGENTS.md"
  9. # TypeScript Project Rules
  11. ## External File Loading（加载外部文件）
  13. CRITICAL：当你遇到文件引用（例如 @rules/general.md）时，请使用 Read tool 按需加载。只在与当前 SPECIFIC task 相关时才加载。
  15. Instructions：
  17. - 不要提前加载所有引用文件（Do NOT preemptively load），应根据实际需要进行 lazy loading  
  18. - 加载后的内容视为强制指令，可覆盖默认行为  
  19. - 必要时递归跟随引用  
  21. ## Development Guidelines（开发规范）
  23. TypeScript 代码风格与最佳实践：@docs/typescript-guidelines.md  
  24. React 组件架构与 hooks 模式：@docs/react-patterns.md  
  25. REST API 设计与错误处理：@docs/api-standards.md  
  26. 测试策略与覆盖率要求：@test/testing-guidelines.md  
  28. ## General Guidelines（通用规范）
  30. 以下文件应立即读取，因为它对所有工作流都适用：@rules/general-guidelines.md

这种方式可以帮助你：

  • 构建模块化、可复用的规则文件
  • 通过 symlinks 或 git submodules 在多个项目之间共享规则
  • 保持 AGENTS.md 简洁，同时引用更详细的规范文档
  • 确保 opencode 仅在当前任务需要时才加载相关文件