opencode
opencode copied to clipboard
docs: clarify that project and global AGENTS.md files are combined, not overridden
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