agents-md-unread-variant

What it catches#

AGENTS.override.md, AGENTS.local.md or .agents/*.md is read by some agents only, or by none.

An AGENTS.override.md, AGENTS.local.md or .agents/*.md file. Codex reads AGENTS.override.md in place of AGENTS.md; Claude Code never reads any of these. The note says which agents load the file, so nobody assumes it applies everywhere.

Why it matters#

Codex reads AGENTS.override.md in place of AGENTS.md; Claude Code never reads these variants, and neither reads AGENTS.local.md or .agents/*.md. The note says which agents load the file.

AGENTS.md
AGENTS.override.md   # "Skip the integration tests this week"

AGENTS.md            # one file every agent reads

How to fix#

Merge the content into AGENTS.md if every agent should follow it. Use an override only as a short-lived local file, and delete it when the reason is gone. A variant that a loaded file points at on purpose is not reported: for AGENTS.local.md or a file under .agents/, mention it by name in a loaded file (better, import it); for AGENTS.override.md, import it from a CLAUDE.md with @AGENTS.override.md.

Suppress or configure#

For one finding, put a comment on the line above it. The reason after -- is optional but worth writing:

<!-- asitis-disable-next-line agents-md-unread-variant -- why this one is fine -->

For a whole file:

<!-- asitis-disable-file agents-md-unread-variant -- why this file is an exception -->

For every file, turn it off or change its severity in .asitisrc.json:

{ "rules": { "agents-md-unread-variant": "off" } }

A .asitisrc.json overrides entry limits a change to some paths, and a baseline (asitis lint --format json --write-baseline) accepts today's findings so only new ones fail the build.

Source#

Codex docs: AGENTS.md, read on 14 October 2026.