04 · 配置、Rules 与自定义命令

OpenCode 的长期价值不在“这次回答得不错”，而在“这次沉淀下来的经验，下次能自动生效”。配置、Rules 和 Commands 就是三种沉淀方式。

这一篇先把三者分清：配置决定 OpenCode 怎么运行，Rules 决定 agent 在项目里应该遵守什么，自定义命令把重复流程变成 /xxx 入口。分不清这三者，后面 agents、skills、plugins 会越写越乱。

沉淀层级图

从一次性提示词到运行时扩展，维护成本会逐层上升。先用最低层解决问题。

flowchart LR
  Prompt["一次性提示词"] --> Rules["Rules / AGENTS.md<br/>长期项目约束"]
  Rules --> Config["Config<br/>模型 / 权限 / share / formatter"]
  Rules --> Commands["Commands<br/>重复流程入口"]
  Commands --> Agents["Agents<br/>角色和权限边界"]
  Agents --> Skills["Skills<br/>跨项目流程包"]
  Skills --> Plugins["Plugins / custom tools<br/>运行时或工具扩展"]

  style Rules fill:#dbeafe,stroke:#3b82f6
  style Commands fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style Plugins fill:#fee2e2,stroke:#ef4444

同一条提醒说了三次，才值得沉淀；沉淀前先判断它是运行策略、长期约束，还是重复流程。

1. 三者先分工

先用一句话拆开：

Config      机器怎么运行
Rules       Agent 在这个项目里怎么做事
Commands    重复任务怎么一键触发

2. Config 管运行，不管任务

OpenCode 支持 JSON / JSONC 配置。官方文档说明配置会按多个来源合并，后面的配置覆盖前面的冲突项，但非冲突项会保留。

你最常用的配置位置：

项目级 opencode.json 的优先级高于全局配置，适合放团队共识。但不要把 API key、token、cookie 写进去。

一个项目级配置的思路示例：

{
  "$schema": "https://opencode.ai/config.json",

  // 模型号请按官方当前推荐 + `/models` 命令为准，不要把"今天最强"硬编码到团队配置里
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",

  "permission": {
    "*": "ask",
    "read": "allow",
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow",
      "rm *": "deny",
      "git push*": "deny"
    }
  },
  "share": "manual",
  "instructions": ["CONTRIBUTING.md", "docs/development.md"]
}

这段配置的重点不是推荐你原样复制，而是展示分层：模型、权限、分享和额外 instructions 都属于“运行时策略”，不属于某一次任务。具体可用模型号会随 provider 上新和淘汰漂移，团队配置里写一个当前还在的、稳定可用的模型即可，但要把"看 官方 models 页" 这条核验路径写进 README 或 AGENTS.md，让下一个接手的人知道怎么自己更新。

3. Rules 不是百科，是项目约束

OpenCode 的 Rules 文档核心是 AGENTS.md。你可以用 /init 创建或更新它。官方建议把项目级 AGENTS.md 提交到 Git，因为它是团队共享的 agent 项目说明。

适合写进 AGENTS.md 的内容：

• 项目技术栈和目录结构。
• build、lint、test 命令。
• 包管理器约定，例如只用 pnpm 或只用 bun。
• 修改前必须阅读的项目文档。
• 禁止修改的目录和文件。
• 错误处理、命名、测试、发布边界。
• 已有 Cursor / Copilot / Claude Code 规则的引用方式。

不适合写进去的内容：

• 一次性任务目标。
• 真实 API key 或内部账号。
• 长篇项目百科。
• 已经过期的历史争论。
• 可以通过文件结构自动看出来的废话。

4. AGENTS.md 和 CLAUDE.md 的关系

OpenCode 支持 AGENTS.md，也兼容 Claude Code 的 CLAUDE.md 约定。官方 Rules 文档说明：

• 项目规则优先读当前目录向上查找的 AGENTS.md / CLAUDE.md。
• 如果同一位置同时有 AGENTS.md 和 CLAUDE.md，AGENTS.md 优先。
• 全局规则优先使用 ~/.config/opencode/AGENTS.md，再兼容 ~/.claude/CLAUDE.md。
• OpenCode 还会兼容 .claude/skills/ 当成 Skills 来源（详见 05 篇）。

这对从 Claude Code 迁移的人很重要。不要同时维护两份不同规则。更稳的做法是选一个主入口，再让另一个兼容引用或保持一致。

如果你想完全关掉对 Claude Code 文件的兼容，OpenCode 提供了三个环境变量，按需选粒度：

export OPENCODE_DISABLE_CLAUDE_CODE=1          # 一刀切：禁所有 .claude 兼容
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1   # 只禁 ~/.claude/CLAUDE.md
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1   # 只禁 .claude/skills

5. Instructions 适合复用已有规范

如果项目已经有 CONTRIBUTING.md、docs/development.md、.cursor/rules/*.mdc，不要复制一份到 AGENTS.md。OpenCode 支持在 config 里用 instructions 引用这些文件：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/development-standards.md",
    ".cursor/rules/*.mdc",
    // 也支持 https URL，5 秒超时拉取
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}

这样做的好处是减少重复维护，跨项目共享规则也容易（团队公共规则放一个 git 仓库，多项目通过 raw URL 引用）。但引用要克制：不要一次性塞 20 个规则文件。规则越多，模型越容易抓不住真正关键的约束。远程 URL 引用还要承担拉取失败和被改动的风险——OpenCode 给的超时是 5 秒，如果远程不可达，那次会话就会少这条规则。

6. Commands 把重复流程做成入口

当一个提示词反复用三次以上，就可以考虑做成 command。

官方 Commands 文档支持两种方式：

• 在 opencode.json 里写 command 配置。
• 创建 markdown command 文件，例如 .opencode/commands/review-diff.md。

项目里更推荐 markdown 文件，因为更易读、易 review、易版本化。

---
description: Review current git diff for bugs and regressions
agent: build
---

请审查当前 git diff：

1. 先读取当前 diff，不要修改文件。
2. 优先找 bug、行为回归、安全风险和缺失测试。
3. 输出按严重程度排序。
4. 如果没有问题，明确说没有发现阻断问题。

文件名就是命令名：

/review-diff

frontmatter 里的 agent 字段指向 OpenCode 内置或你自己定义的 agent（如默认 build / plan，或自定义的 review / security-audit）。如果不写 agent 就沿用当前会话的 agent。详见 05 篇。

Command 的价值不是少打几个字，而是把任务边界、检查顺序和输出格式固定下来。

7. Command 参数、文件和 shell 输出

OpenCode command 支持 $ARGUMENTS、$1、$2 这类参数，也支持在 prompt 中引用文件和注入 shell 输出。

例子：

---
description: Explain one module with risks
---

请解释 $ARGUMENTS 这个模块：

1. 先阅读相关入口文件。
2. 说明它解决什么问题。
3. 画出调用链。
4. 列出最可能出错的 3 个点。

运行：

/explain-module src/auth

再比如把 git diff 注入 command：

---
description: Review current diff
---

当前改动如下：

!`git diff --stat`
!`git diff`

请只做审查，不要修改文件。

frontmatter 还有两个有用但容易被忽略的选项：

例如让一条体量大的代码审查走 subagent + 更强模型：

---
description: Deep audit of recent changes
agent: build
model: anthropic/claude-opus-4-5
subtask: true
---

请深度审查最近 50 个 commit：
...

8. 推荐沉淀顺序

不要第一天就配置满。更稳的顺序是：

普通提示词
  ↓  同一提醒出现 3 次
AGENTS.md / instructions
  ↓  同一流程出现 3 次
.opencode/commands/*.md
  ↓  需要不同角色和权限
agents
  ↓  跨项目复用能力
skills
  ↓  需要运行时扩展
plugins / custom tools

每往下一层，维护成本都更高。OpenCode 的开放配置不是为了堆满所有目录，而是让真实经验逐步沉淀。

9. 新手常见坑

10. 怎么验收

你可以用 5 个问题检查这一层是否过关：

• 每一条 AGENTS.md 规则是否未来多次任务都需要？
• 项目配置里是否没有真实密钥？
• 能否用一个 command 稳定完成重复任务？
• 规则、配置、命令是否各司其职，没有互相污染？
• 删除某条 rule 或 command 时，是否知道会影响哪些流程？

接下来去哪

官方资料

• Config：https://opencode.ai/docs/config
• Rules：https://opencode.ai/docs/rules
• Commands：https://opencode.ai/docs/commands
• Permissions：https://opencode.ai/docs/permissions