Skip to content

Commit 807acb5

Browse files
committed
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 Fixes anomalyco#9282
1 parent 8b99648 commit 807acb5

1 file changed

Lines changed: 30 additions & 6 deletions

File tree

‎packages/web/src/content/docs/rules.mdx‎

Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,28 @@ opencode also supports reading the `AGENTS.md` file from multiple locations. And
5858

5959
### Project
6060

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.
6283

6384
### Global
6485

@@ -86,13 +107,16 @@ export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills
86107

87108
## Precedence
88109

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`.
90115

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:
94117

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`.
118+
1. `~/.config/opencode/AGENTS.md`
119+
2. `~/.claude/CLAUDE.md` (unless disabled)
96120

97121
---
98122

0 commit comments

Comments
 (0)