Skip to content

docs: clarify rule file precedence #32875

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dannyward630 wants to merge 1 commit into
base: dev
Choose a base branch
from
+5 −3
Open

docs: clarify rule file precedence #32875

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions packages/web/src/content/docs/rules.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand Down
Loading