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`)

Đang mở Phù hợp với người mới
#92,254 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
area:cli area:docs documentation enhancement
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

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.