Repository navigation
docs: clarify that project and global AGENTS.md files are combined, not overridden #9282
Closed as not planned
Description
The Rules documentation has an ambiguous "Precedence" section that can mislead users.
Current text
When opencode starts, it looks for rule files in this order:
- Local files by traversing up from the current directory (
AGENTS.md,CLAUDE.md, orCONTEXT.md)- Global file at
~/.config/opencode/AGENTS.md- Claude Code file at
~/.claude/CLAUDE.md(unless disabled)The first matching file wins in each category.
Problem
The phrase "first matching file wins" suggests only one file is loaded total. Combined with the "Global" section saying users can put "personal rules" there, users may believe:
- Having a project-level
AGENTS.mdwill override their global one - They need to choose between project or global rules
Actual behavior
Looking at packages/opencode/src/session/system.ts, both local AND global files are loaded and combined:
- Local category: first filename found wins (
AGENTS.md>CLAUDE.md>CONTEXT.md) - Global category: first filename found wins (
~/.config/opencode/AGENTS.md>~/.claude/CLAUDE.md) - Both categories are combined — files are concatenated with newlines in the system prompt
Suggested fix
Clarify that:
- "First wins" applies to filename variants within each category, not across categories
- Both project-level and global rules are loaded together
- The order in the prompt is: project rules first, then global rules
Reacted by Bernat Pericàs, Marcel Richter, Nick S, Ilya Rusyanov, Rodrigo Chavez, Leanid Shutau, Matěj Pešl, mariussuflea, rwwrwr, Ali Can Sag and 2 more
Metadata
Metadata
Assignees
Labels
No labels
Activity
berenar commentedon Jan 18, 2026
Agree, it's not clear
mrclrchtr commentedon Jan 25, 2026
Yes, please update the docs - I also can't figure out exactly whether the CLAUDE.md pattern from claude code is used with “loading subdir CLAUDE.md files when working with files in the directory”. That would be super interesting!
docs: clarify rule file loading behavior and precedence
jstasiak commentedon Feb 19, 2026
#14330 addresses this problem.
ggbondg commentedon Mar 18, 2026
agree +1, if conflict, project rules should override the global rule.
github-actions commentedon Jul 6, 2026
To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.
xmontero commentedon Aug 5, 2026
I can't get why this has been marked as "not planned".
a) Shoudn't the documentation reflect the actual behaviour?
b) Is the public documentation also versioned in git?
c) May we open an issue on the documentation repo if it exists, link to there and change the tag from "not planned" to "see there in the other place"?
PD:
xref'd here #9287 (comment)