anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-22 18:25:32 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

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

New Issue
Open
opened 2026-02-16 18:05:03 -05:00 by yindo · 2 comments
yindo commented 2026-02-16 18:05:03 -05:00
Owner
Copy Link
Copy Source

Originally created by @alanpog on GitHub (Jan 18, 2026).

Originally assigned to: @jayair on GitHub.

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
Originally created by @alanpog on GitHub (Jan 18, 2026). Originally assigned to: @jayair on GitHub. The [Rules documentation](https://opencode.ai/docs/rules/) 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
yindo added the docs label 2026-02-16 18:05:03 -05:00
yindo commented 2026-02-16 18:05:03 -05:00
Author
Owner
Copy Link
Copy Source

@berenar commented on GitHub (Jan 18, 2026):

Agree, it's not clear

@berenar commented on GitHub (Jan 18, 2026): Agree, it's not clear
yindo commented 2026-02-16 18:05:03 -05:00
Author
Owner
Copy Link
Copy Source

@mrclrchtr commented on GitHub (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!

@mrclrchtr commented on GitHub (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!
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label docs
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#6721
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?