[DOCS] `--setting-sources` docs do not state that omitting `project` skips nested `.claude/rules/*.md`

Status Fixed / completed
Maintainer reply None cached
Activity 1 comment · opened Jul 16, 2026 · closed Aug 17, 2026

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/cli-reference

Section/Topic

The --setting-sources flag description and the memory guide's rules loading behavior.

Current Documentation

The CLI reference documents:

--setting-sources — Comma-separated list of setting sources to load (user, project, local)

The memory guide ties additional-directory rules to setting sources only for local:

CLAUDE.local.md is skipped if you exclude local from --setting-sources.

The Agent SDK features page lists project rules under the "project" source, including .claude/rules/*.md in parent directories, but the CLI flag entry does not spell out that nested project rules are part of the project source.

What's Wrong or Missing?

Claude Code v2.1.211 fixed nested .claude/rules/*.md files loading even when setting sources exclude project settings. Operators who run claude --setting-sources user (or SDK settingSources without "project") expect project CLAUDE.md, project settings.json, project hooks, skills, and all project-scoped .claude/rules/*.md (including nested subdirectories) to stay unloaded. That expectation is not documented on the CLI flag or in the memory guide.

Suggested Improvement

Expand the --setting-sources row in cli-reference.md:

Omitting project disables project settings.json, project hooks, project skills, project CLAUDE.md, and .claude/rules/*.md under the project (including nested rule files discovered recursively). User and local sources are unaffected.

Add a matching note to memory.md in "Organize rules with .claude/rules/" and cross-link to the Agent SDK settingSources table.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/cli-reference | 116 | --setting-sources flag |
| https://code.claude.com/docs/en/memory | 169–181 | Rules and setting sources |
| https://code.claude.com/docs/en/agent-sdk/claude-code-features | 72–109 | settingSources and rules load locations |

Total scope: 3 pages affected

Version: v2.1.211 fix; document the intended exclusion semantics.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗