Claude Code's AGENTS.md plugin defers to any CLAUDE.md in the project path

The plugin hands back a list. On `prompt.context` the engine gives a hook the instruction files behind `claudeMd`, each one as path, kind, content and an optional parent, in load order across the kinds `managed`, `user`, `project`, `local` and `memory`. The hook answers with that list changed ^[11]. The engine renders the answered files with its own preamble and framing and announces them by name ^[12]. For an agent that omits project instructions, which includes Explore, Plan and a custom agent with `omitClaudeMd`, it keeps only the managed files ^[12]. So an `AGENTS.md` the plugin adds as a project file is, to everything downstream, a project instruction file: same place in the context, same omission rules ^[13]. The default is a fallback, and it is judged across the whole project path. A project with no instruction files of its own gets its `AGENTS.md` files loaded exactly where and how `CLAUDE.md` would be ^[3]. "Of its own" is read off what the engine already loaded. One `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in any directory from the root down to the working directory leaves the whole project to the engine, and the plugin stays out ^[4]. The organization's managed file, a person's `~/.claude/CLAUDE.md`, a `.claude/rules` file and an added directory's `CLAUDE.md` all sit outside that check, because the nested walk misses them too ^[5]. With none of those present, every `AGENTS.md` and `.claude/AGENTS.md` on the path joins what the engine renders. A `Read` under a subdirectory attaches that directory's `AGENTS.md` unless a `CLAUDE.md` there claims it ^[6]. A team that wants one instruction file per repo has two routes. Delete the `CLAUDE.md` files from the root down to where people work. Or set `claude-md-and-agents-md`, which loads every `AGENTS.md` beside `CLAUDE.md` up and down the tree and skips anything `CLAUDE.md` already `@`-imports or links to, compared by path and then by content ^[7]. Of the four values, two load `AGENTS.md` at all ^[1]. `claude-md` leaves the engine reading `CLAUDE.md` as it does today ^[2]. `managed-only` drops the project's checked-in and private files along with the person's own, keeping the organization's managed `CLAUDE.md` and the engine's memory ^[8]. The choice lives in settings. The option is set in user settings at `~/.claude/settings.json`, through `--settings`, or in managed settings, and a project's `.claude/settings.json` is not read for plugin options ^[16]. In the app it is the `/config` row "Project instructions", a picker over the four values with each described there ^[15]. A repo can check in `AGENTS.md`; whether a given workstation reads it is decided by that workstation's settings or by whoever ships managed settings ^[16]. A person can also turn the built-in off from `/plugin`, after which the engine reads `CLAUDE.md` alone ^[19]. An organization's prepended plugin on `prompt.context` sits above this one and decides the files ^[14]. And `managed-only` removes a team's checked-in instructions from the context without anyone editing the repo ^[8]. The migration has one quiet failure mode. The option was first keyed `projectInstructions`, with the values `claude`, `agents-fallback`, `both` and `none` ^[22]. A value still stored there is honoured for now while `instructionFiles` is at its default. It maps `none` to `managed-only`, `claude` to `claude-md`, `agents-fallback` to the fallback default and `both` to the merge mode ^[23]. Any other value under the old key is read as `claude-md`. It adds nothing ^[24]. A provisioning script carrying a stale value therefore leaves `AGENTS.md` unread. The notice is one line: the first `session.start` of a load says in the transcript how the option was read ^[25]. Setting `instructionFiles` to anything but its default stops the old key being read, and the transcript says to remove it ^[26].