编写规则

OpenCode 的 Rules 是给 Agent 的项目说明和行为约束。它的核心入口是 AGENTS.md：告诉 Agent 这个项目怎么启动、怎么验证、哪些目录重要、哪些事情不能做。

先给结论：Rules 不是项目百科

规则文件不是越长越好。好的 AGENTS.md 只回答未来 Agent 会反复遇到的问题：

第一次怎么生成

官方提供 /init 命令。它会扫描仓库中的重要文件，必要时提出少量问题，然后创建或更新 AGENTS.md。

/init 重点关注这些内容：

• build、lint、test 命令。
• 命令顺序和必要的局部验证步骤。
• 文件名看不出来的架构和仓库结构。
• 项目特定约定、设置细节和运维坑。
• Cursor、Copilot、Claude Code 等已有规则来源。

如果仓库已经有 AGENTS.md，/init 会尝试原地改进，而不是盲目替换。

项目规则和全局规则怎么分

项目规则服务当前仓库，全局规则服务你自己的所有 OpenCode 会话。

不要把个人习惯写进项目规则，也不要把某个项目的命令写进全局规则。

规则读取优先级

OpenCode 启动时，会按规则来源找文件。可以把它理解成这条链：

flowchart LR
  CWD[当前目录] --> Up[向上查找本地规则]
  Up --> Local{找到本地规则?}
  Local -->|AGENTS.md 优先| Project[项目规则生效]
  Local -->|无 AGENTS.md<br/>有 CLAUDE.md| ClaudeProject[Claude 项目兼容]
  Local -->|没有| Global[读取全局规则]
  Global --> OpenCodeGlobal[~/.config/opencode/AGENTS.md]
  Global --> ClaudeGlobal[~/.claude/CLAUDE.md fallback]

同一位置同时有 AGENTS.md 和 CLAUDE.md 时，AGENTS.md 优先。全局规则里，~/.config/opencode/AGENTS.md 优先于 ~/.claude/CLAUDE.md。

Claude Code 兼容怎么理解

OpenCode 支持 Claude Code 的文件约定作为 fallback：

• 项目里没有 AGENTS.md 时，可以读取项目 CLAUDE.md。
• 没有 OpenCode 全局规则时，可以读取 ~/.claude/CLAUDE.md。
• .claude/skills 的兼容细节在 Agent Skills 页面继续看。

如果你不希望使用 Claude Code 兼容，可以用环境变量关闭：

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

迁移期可以利用 fallback，但不要长期维护两套互相冲突的规则。更稳的做法是选一个主入口，另一个只做兼容引用或保持同步。

外部指令怎么放

如果规则很多，不要把所有内容塞进 AGENTS.md。OpenCode 支持在 opencode.json 或全局配置里用 instructions 引用外部文件。

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

也可以引用远程 URL：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}

远程 instructions 会有 5 秒超时：拉不到就跳过，那次会话就没有这条规则。所以网络抖动、对方仓库挂掉、CDN 慢都会让 agent 行为不稳定。来源必须可信，且不要把生死攸关的硬约束放在远程——核心边界还是要进项目自己的 AGENTS.md。

外部文件引用要按需加载

官方文档提醒：OpenCode 不会自动解析 AGENTS.md 里的文件引用。你可以用两种方式管理外部规则：

如果是大型规范库，不要要求 Agent 一开始读完所有文件。规则应该帮助 Agent 少猜，而不是把上下文塞满。

一个健康的 AGENTS.md 长什么样

可以按这个骨架写：

# Project Instructions

## What This Project Is

One short paragraph describing the product and stack.

## Common Commands

- `pnpm run build`
- `pnpm run lint`
- `pnpm run test`

## Important Paths

- `src/app/`: routes and page entry points
- `src/components/`: shared UI components
- `content/docs/`: production documentation source

## Working Rules

- Do not edit generated files by hand.
- Keep content changes in the matching product directory.
- Run quality audits before build.

## Verification

1. Run the focused check for the changed area.
2. Run the project audit.
3. Build before deployment.

这不是固定模板，而是提醒你：规则文件要短、可执行、能指导下一步。

新手常见坑

• /init 后不审查就提交。
• AGENTS.md 写成完整项目文档，太长且没有优先级。
• 项目规则混入个人偏好。
• 全局规则写入某个项目的命令。
• 同时存在 AGENTS.md 和 CLAUDE.md，但团队不知道谁生效。
• 远程 instructions 来自不可信地址。
• 规则只写“不要做什么”，没有写验证顺序。

怎么判断规则健康

一个健康的规则文件应该满足：

• 新人读完能知道项目怎么启动、怎么验证。
• Agent 能知道哪些目录和命令最重要。
• 规则短而明确，没有复述 README。
• 团队共享规则在项目 AGENTS.md。
• 个人规则在全局文件。
• 外部文件按需引用，不一次性塞满上下文。

规则文件的目标是减少误操作，不是证明项目文档很完整。

接下来去哪

官方资料

• OpenCode Rules
• OpenCode configuration
• OpenCode Agent Skills