anthropics / anthropics/claude-code
[DOCS] `--setting-sources` docs do not say what each source value actually gates (CLAUDE.md, plugins, hooks, skills, agents, commands, `--settings`)
- Ngôn ngữ chính
- Python
- Star
- 145k
- Fork
- 23.1k
- Chỉ số merge pull request
- Chỉ số pull request đang chờ
Mô tả
### Documentation Type
Missing documentation (feature not documented)
### Documentation Location
https://code.claude.com/docs/en/cli-reference
### Section/Topic
The `--setting-sources` flag on the CLI reference, plus the settings, memory, hooks, plugins, MCP and headless pages that describe the things it filters.
### Current Documentation
The CLI reference describes the flag in one line:
> `--setting-sources` — Comma-separated list of setting sources to load (`user`, `project`, `local`)
The memory guide adds that `CLAUDE.local.md` is skipped without `local` and, since #78007, that project rules are skipped without `project`. That's all the docs say about what the flag reaches.
### What's Wrong or Missing?
The flag gates far more than the three `settings.json` files, and none of it is written down. I measured this on 2.1.261 (Windows, subscription OAuth) with content probes: a marker phrase in each file, then a headless `claude -p` asked whether the phrase is in its context, with tools forbidden. Command:
```
claude -p "" --setting-sources project,local --settings .claude/settings.agent.json
```
Dropped when `user` is omitted:
- `~/.claude/CLAUDE.md`
- `~/.claude/settings.json`
- every plugin, including the plugins' hooks and skills (a SessionStart hook from one plugin stopped injecting its context)
- `~/.claude/skills/`, `~/.claude/agents/`, `~/.claude/commands/`
Still loaded with `project,local`:
- the project `CLAUDE.md`
- `.claude/settings.json`, and its PreToolUse hooks still fire
- `.claude/settings.local.json`
- project `.mcp.json` servers
- auto-memory (`MEMORY.md`)
- `.claude/commands/`
- the `--settings` file
I only know this because I probed for it. Nobody reading the CLI reference could predict that omitting `user` removes plugins and their hooks, or that `--settings` survives the filter. #49860 asked for the flag to cover CLAUDE.md, skills, agents and commands in April; on 2.1.261 it apparently does, and the docs never caught up.
Two behaviours are worth documenting alongside, because they change the answer for anyone using the flag for isolation:
- #87590: with the project directory under `$HOME`, `~/.claude/CLAUDE.md` and `~/.claude/rules/*.md` still load under `--setting-sources project`, since the parent-directory walk reaches `~`. My project is outside the home directory, which is why the probe above came out clean. Until that's fixed, the doc should say the isolation depends on where the project lives.
- #86837: `CLAUDE_CONFIG_DIR` does not exclude `~/.claude/CLAUDE.md` either, so the flag is currently the only way to keep a headless run from inheriting an operator's user-level instructions without `--bare`, which also drops the project `CLAUDE.md`, hooks and MCP.
### Suggested Improvement
On the `--setting-sources` row in `cli-reference.md`, replace the one-liner with a table showing what each source value controls. The rows I'd expect are `settings.json`, `CLAUDE.md`, `.claude/rules/`, skills, agents, commands, hooks, plugins, `.mcp.json` and auto-memory. Say explicitly that `--settings` is not subject to the filter. Add the `$HOME` caveat from #87590 until it's fixed.
On `headless.md`, cross-link the flag from the section that recommends `--bare`, since `--setting-sources project,local` is the option for a scheduled run that needs the project's hooks and MCP servers but must not inherit the operator's interactive config.
### Impact
Medium - Makes feature difficult to understand
### Additional Context
My use case is a scheduled headless run that must take its configuration from the repository alone. Before adding the flag it inherited a 15 KB user-level `CLAUDE.md` written for interactive sessions, plus three plugins' SessionStart, UserPromptSubmit and Stop hooks. The behaviour I measured is exactly what I wanted, but I had to find it by experiment, and I can't tell from the docs whether any of it is intended and stable.
Version: 2.1.261.
Hướng dẫn đóng góp
Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này
Hướng nghiên cứu
Start with the CLI reference page for `--setting-sources`, especially `cli-reference.md`, and the `headless.md` section that recommends `--bare`. The issue lists the expected table rows and caveats to document, including that `--settings` is not filtered and the `$HOME` caveat from #87590. Done means the reference explains what each source gates and headless docs cross-link the flag.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- cli
- Lĩnh vực
- cli, documentation
- Loại issue
- Tài liệu
- Độ khó
- 2/5
- Thời gian dự kiến
- 1-3 giờ
- Mức độ hoạt động
- Sôi nổi
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức phù hợp với người mới
- 78/100