You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 807acb5
Browse filesBrowse the repository at this point in the historyBrowse files
docs: clarify rule file loading behavior and precedence
- Document subdirectory rule files (loaded dynamically on file read,
not at startup)
- Explain the upward walk from file location to project root
- Fix misleading "first matching file wins" phrasing: clarify it
applies to filename variants (AGENTS.md vs CLAUDE.md), not across
directories or categories
- Note that project-level and global rules are combined, not overridden
Fixesanomalyco#9282
Copy file name to clipboardExpand all lines: packages/web/src/content/docs/rules.mdx
+30-6Lines changed: 30 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -58,7 +58,28 @@ opencode also supports reading the `AGENTS.md` file from multiple locations. And
58
58
59
59
### Project
60
60
61
-
Place an `AGENTS.md` in your project root for project-specific rules. These only apply when you are working in this directory or its sub-directories.
61
+
Place an `AGENTS.md` in your project root for project-specific rules. This file is loaded into the system prompt on every LLM turn.
62
+
63
+
If your project root is inside a git worktree (e.g. a package in a monorepo), opencode also walks upward from the project root to the worktree root, collecting any rule files it finds along the way.
64
+
65
+
### Subdirectories
66
+
67
+
You can also place `AGENTS.md` files in subdirectories. These are **not** loaded at startup. Instead, they are loaded dynamically when opencode reads a file in that directory or any of its children.
68
+
69
+
For example, given this layout:
70
+
71
+
```
72
+
AGENTS.md
73
+
packages/api/AGENTS.md
74
+
packages/api/routes/AGENTS.md
75
+
```
76
+
77
+
When opencode reads a file in `packages/api/routes/`, it walks upward from that directory toward (but not including) the project root, loading rule files closest-first:
78
+
79
+
1.`packages/api/routes/AGENTS.md`
80
+
2.`packages/api/AGENTS.md`
81
+
82
+
The root `AGENTS.md` is already in the system prompt, so it is not loaded again. Each subdirectory rule file is loaded at most once. If the conversation's context window is compacted, tracking resets and previously loaded files may be reloaded.
62
83
63
84
### Global
64
85
@@ -86,13 +107,16 @@ export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills
86
107
87
108
## Precedence
88
109
89
-
When opencode starts, it looks for rule files in this order:
110
+
In each directory, `AGENTS.md` takes precedence over `CLAUDE.md`. If both exist in the same directory, only `AGENTS.md` is used.
111
+
112
+
For project-level rules (root and upward to worktree), the file name choice applies globally: if any `AGENTS.md` is found in the upward walk, all `AGENTS.md` files from every level are collected and `CLAUDE.md` is ignored entirely. Only if no `AGENTS.md` exists at any level does opencode fall back to `CLAUDE.md`.
113
+
114
+
For subdirectory rules (loaded on file read), the choice is made per directory: each directory independently uses whichever file name exists, preferring `AGENTS.md`.
90
115
91
-
1.**Local files** by traversing up from the current directory (`AGENTS.md`, `CLAUDE.md`)
92
-
2.**Global file** at `~/.config/opencode/AGENTS.md`
93
-
3.**Claude Code file** at `~/.claude/CLAUDE.md` (unless disabled)
116
+
For global rules, opencode checks in order and uses the first one found:
94
117
95
-
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`.
0 commit comments