Why OpenCode ignores your AGENTS.md, and how to prove what loaded

AGENTS.md is a Markdown file, in your repository or your OpenCode config folder, with instructions OpenCode reads before it starts work, so a rule does not have to be repeated in every prompt. It is also the only instruction file OpenCode 2.x looks for; 1.x falls back to a CLAUDE.md when no AGENTS.md is on the path, which is why a file that worked before an upgrade can stop loading.

There are two different failures behind "OpenCode ignores my AGENTS.md". The file never reached the prompt, or it reached the prompt and the model did not follow it.

Run opencode --version first. A 1.x version is V1, a 2.x version is V2, and the two lines load instructions differently.

Checked against OpenCode's documentation on 27 October 2026.

Status, 27 October 2026: V2 dropped the CLAUDE.md fallback, and a V2 regression made the instructions array inert from 2.0.16 through at least 2.0.28 (#51341, closed as completed 14 October 2026). V1 still reads CLAUDE.md and CONTEXT.md.

What V2 loads#

V2 recognizes AGENTS.md only and does not read CLAUDE.md as a fallback.

At session start it assembles instructions in this order:

1. The global file at $CONFIG_DIR/AGENTS.md. opencode debug paths config prints the real config directory.
2. Every AGENTS.md from the workspace toward the home directory, nearest first. Outside the home directory, it stops at the project root.
3. Files listed in the instructions array, in order.

For ~/code/my-project/packages/web, that is:

~/.config/opencode/AGENTS.md
~/code/my-project/packages/web/AGENTS.md
~/code/my-project/packages/AGENTS.md
~/code/my-project/AGENTS.md

V2 combines the files without resolving conflicts, so put a rule where it belongs rather than relying on order.

If the workspace is outside the project root, only the global file loads. OPENCODE_DISABLE_PROJECT_CONFIG=1 skips project discovery but keeps the global file.

V2 also loads AGENTS.md files below the workspace when the agent reads a file or lists a directory there, nearest first. A repeat read does not normally inject them again; after compaction (older turns replaced by a summary) or a revert, it can. A nested file edited after it loaded needs a new session.

V2 watches global and upward-discovered files and adds an update before the next request. Removing them all says the previous instructions no longer apply.

The instructions array takes relative paths, globs, ~/, absolute paths, and HTTP(S) URLs. Relative entries search from workspace to project root. URLs are fetched at config load with a five-second timeout; missing or unreachable entries are skipped or keep their last copy.

What V1 loads#

The global file is $CONFIG_DIR/AGENTS.md. If it does not exist, V1 falls back to ~/.claude/CLAUDE.md. OPENCODE_CONFIG_DIR replaces the config directory, so a profile directory with its own AGENTS.md is the global file for that run. Older builds ignored that profile file when the default global file existed; the fix landed on 4 February 2026 (#11534).

For the project, V1 walks from the workspace up to the worktree root (the checkout root Git tracks). It looks for AGENTS.md first. If any exists on that path, it loads all of them and stops looking for other filenames. If there is no AGENTS.md, it loads CLAUDE.md files; if there is no CLAUDE.md, it loads the deprecated CONTEXT.md.

The rules page's "first matching file wins in each category" means filename types, not one file total. At startup, a project with a root AGENTS.md and a subdirectory CLAUDE.md will not load the subdirectory file as part of the project-level set, because the AGENTS.md category won the walk. It can still be attached when the agent reads a file under that subdirectory (see below). The docs do not spell this out; the V1.19.4 source does.

After the project files, V1 adds local instructions entries and fetches HTTP(S) entries with the same timeout. V1 also attaches nearby instruction files when the agent reads a file, though the rules page does not describe it. Treat nested behaviour as version-specific and verify it.

Why the rule never arrived#

• The rule is in the wrong file, or the file is in the wrong place. V2 does not read CLAUDE.md; rename it or add its path to instructions. At startup, V1 will not add CLAUDE.md files if any AGENTS.md exists on the project path; a nested read can still attach one. The global file can move with OPENCODE_CONFIG_DIR, XDG_CONFIG_HOME, a wrapper, or a second install, so compare opencode debug paths config with the file you edited, in the same shell that starts OpenCode.
• The workspace is outside the project root. In V2 only the global file loads. Start inside the project, or add the file to instructions with an absolute path.
• Early V2: the rule is in instructions. The array was inert in 2.0.16 and still reported in 2.0.28; the issue closed on 14 October 2026. Update, or keep the rule in AGENTS.md.
• The nested file was never on a read path, or was edited after it loaded. A sibling subtree the agent never touches does not load. A file that already loaded does not notice later edits; start a new session. Files at or above the workspace are watched and do update.
• A remote instructions URL failed. A URL that works in a browser can still fail from the OpenCode machine after the five-second timeout.

A file that loaded and still gets ignored is not a loading problem. Make the rule concrete and testable, put it near the work it governs, and use a permission rule for anything that must be blocked every time.

Prove what reached the model#

Do not ask the model whether it read the file. Models describe their context from memory and from the shape of the conversation, and a confident answer is not evidence. A 2026 thread on a supposed global-file failure was resolved when a logger showed both files in the prompt (#22020). Another was closed as not planned; its useful record is a user's raw prompt dump showing no instruction block, not a model's answer (#11532).

V2: read the instruction record#

V2 stores each session's instruction files in a local database. List the recorded paths, not the contents:

opencode session list --max-count 500

sqlite3 -readonly "$(opencode debug paths db)" "
select json_extract(j.value, '$.path')
from instruction_state s
join instruction_blob b
  on b.hash = json_extract(s.current_values, '$.\"core/instructions\"')
join json_each(b.value) j
where s.session_id = 'ses_your_session_id';"

Substitute the ID from the first command. One path per line: empty means no instruction files; your path means the file reached the session.

This was run on OpenCode 2.1.4. The table names are internal and the blob holds file text, so print paths only. opencode debug config lists the config documents OpenCode loaded, which confirms your project config and its instructions entry.

Both lines: inspect the prompt#

The rendered instruction block starts with the literal line Instructions from: <path or URL>, followed by the file text. That prefix is in the V1.19.4 source and in V2's instruction renderer.

Put a logging proxy or a small local plugin between OpenCode and the model provider, run one request, and search the captured system prompt for Instructions from:. If the path is there, the file loaded; if not, the problem is discovery.

V1 has no command that lists loaded instruction files; a 2026 request was closed as a duplicate (#9502). Use the proxy or plugin.

If it loaded and still gets ignored#

An AGENTS.md rule is context, not configuration. Nothing in the file can stop a tool call; only a matching permission rule can.

For guidance rather than blocking:

• Write the rule as something you can check: the command to run, the file to leave alone, the order of two steps.
• Keep one topic per file and put it near the code it governs. A long global file competes with the project files for attention.
• If a rule held at the start and faded after a long session, that is a context problem. The compaction guide covers what survives and how to re-anchor.

For rules that must hold every time, use a permission rule. Reserve AGENTS.md for guidance the model can exercise judgement about.

Where to go next#

• Why OpenCode permission rules don't fire — the rules that actually block a tool call.
• Where did my OpenCode session go? — if the rule disappeared with the session.
• Context compaction — if the rule faded mid-task.
• One AGENTS.md for every coding agent — native reads, imports and symlinks, and the duplicate that drifts.
• OpenCode guides — the rest of the set.