opencode icon indicating copy to clipboard operation
opencode copied to clipboard

docs: clarify that project and global AGENTS.md files are combined, not overridden

Open alanpog opened this issue 1 day ago • 1 comments

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:

  1. Local files by traversing up from the current directory (AGENTS.md, CLAUDE.md, or CONTEXT.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.

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.md will 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:

  1. Local category: first filename found wins (AGENTS.md > CLAUDE.md > CONTEXT.md)
  2. Global category: first filename found wins (~/.config/opencode/AGENTS.md > ~/.claude/CLAUDE.md)
  3. 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

alanpog avatar Jan 18 '26 20:01 alanpog