Build1 publisher2 min readPublished
A subdirectory CLAUDE.md enters the context window only when Claude reads a file in that directory
Claude Code's configuration-debugging page says nested memory files load on demand through the Read tool, so a report that the agent ignored the rules starts with /context and the question of whether the file was in the window at all.
The Engineer · Build desk
What happened
- Claude Code loads a subdirectory CLAUDE.md on demand, when the model reads a file in that directory with the Read tool, and not at session start.
- The /context command breaks the current session's window into categories: system prompt, system tools, MCP tools, subagents with the source each loaded from, memory files, skills and conversation messages.
- The docs say adherence drops when an instruction can be read multiple ways, when two files give conflicting direction, or when a file has grown long enough that individual rules get less attention.
- An array where a hook matcher expects a string is a schema error, and Claude Code rejects the whole user, project or local settings file, so none of its hooks appear in /hooks.
- Settings merge across managed, user, project and local scopes, with managed applied first and the closer scope overriding the broader one in the order local, then project, then user.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- constraint A nested CLAUDE.md cannot hold a rule that must apply every session, because whether it is in force depends on which directories the agent happened to read.
- decision Once /context shows the file present, the only lever the docs offer is the text of the instruction, so adding another memory file is the wrong repair.
- exposure An admin-level hook can stop applying while the rest of its file keeps working, because managed settings lose only the hooks key of the file that holds the bad value.
- cost Explaining why one setting is inert means checking five sources for a single value: four merge scopes plus command-line flags and environment variables.
A session that stays in the web app never calls Read on a file under packages/api, so that directory's CLAUDE.md is not in the window and /context lists no memory entry for it [25]. The page's first instruction is to run /context and confirm that the CLAUDE.md, the rules and the skill descriptions are present at all [2]. Its skills section also lists bundled skills, which /skills omits [3].
The content advice is narrow. CLAUDE.md suits the guidance you would give a new teammate: project conventions, build commands, where files belong [6]. The page does not give the relative frequency of the two branches, so the idea that most ignored-rule incidents are loading failures is not something the docs establish [26].
Settings have their own version of the same question. When a value looks inert, the page's explanation is that another scope or an environment variable overrode it [10]. /status prints which settings sources are active, including whether managed settings are in effect [12]. claude doctor runs from the terminal and prints read-only installation and settings diagnostics without starting a session, while /doctor inside a session proposes fixes and asks before applying them [11].
Hooks fail in two distinct places. A hook that never appears in /hooks is not being read, and the usual reason is that it was written in a standalone file instead of under the "hooks" key in a settings file [17]. A hook that appears and never fires is usually the matcher [27]. The matcher is a single string, with | separating tool names as in "Edit|Write", and a comma is equivalent [18]. Before v2.1.191 a comma fell through to regex evaluation and the matcher never matched [19]. The same settings file therefore behaves differently on two installs that differ by a patch version [28]. A misspelled tool name produces a matcher that matches nothing, and the hook fails silently [20].
MCP servers break on paths. The page gives relative paths in command or args as a frequent cause of a server failing to start, since they resolve against the directory Claude Code was launched from and not the location of .mcp.json [15]. A server that shows as connected with zero tools has started but is not returning a tool list; after a Reconnect, the next step is claude --debug=mcp and the server's stderr in ~/.claude/debug/<session-id>.txt [16].
Once the file is correct, an edit to settings.json takes effect in the running session after a brief file-stability delay [23].
What to watch
- Whether the docs state when the root and imported CLAUDE.md files load, now that the subdirectory case is documented as on demand.
- Whether managed settings adopt the whole-file rejection used for user, project and local files, or the hooks-key drop stays an exception.
- Whether comma-separated matchers stay supported after v2.1.191, since files written for older installs use | instead.