From e9d76fd00fd2a5802cbf1d3a56a0300525dd7600 Mon Sep 17 00:00:00 2001 From: dannyward630 Date: Thu, 18 Jun 2026 19:59:40 +0200 Subject: [PATCH] docs: clarify rule file precedence --- packages/web/src/content/docs/rules.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/packages/web/src/content/docs/rules.mdx b/packages/web/src/content/docs/rules.mdx index 6db5d45b1d3a..6009adb0072f 100644 --- a/packages/web/src/content/docs/rules.mdx +++ b/packages/web/src/content/docs/rules.mdx @@ -94,13 +94,15 @@ export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills ## Precedence -When opencode starts, it looks for rule files in this order: +When opencode starts, it loads matching rule files from the project and global categories: -1. **Local files** by traversing up from the current directory (`AGENTS.md`, `CLAUDE.md`) +1. **Project files** by traversing up from the current directory (`AGENTS.md`, `CLAUDE.md`) 2. **Global file** at `~/.config/opencode/AGENTS.md` 3. **Claude Code file** at `~/.claude/CLAUDE.md` (unless disabled) -The first matching file wins in each category. For example, if you have both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` is used. Similarly, `~/.config/opencode/AGENTS.md` takes precedence over `~/.claude/CLAUDE.md`. +The first matching file wins only within each category. For example, if a project has both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` is used for that project category. Similarly, `~/.config/opencode/AGENTS.md` takes precedence over `~/.claude/CLAUDE.md` for the global category. + +Project and global rules are combined. A project `AGENTS.md` does not disable your global `AGENTS.md`; both are loaded when both exist. ---