Docs: Clarify how `CLAUDE.md` and `--append-system-prompt` influence Claude's instructions

Title: Docs: Clarify how CLAUDE.md and --append-system-prompt influence Claude's instructions

Labels: documentation, enhancement, clarification

Description

The documentation for Claude Code provides several ways to customize its behavior, but the distinction between how CLAUDE.md files and the --append-system-prompt flag influence Claude's core instructions could be clearer. Centralizing this information would help users build a more accurate mental model for prompt customization.

The Point of Confusion

The Settings documentation page correctly states that both CLAUDE.md and --append-system-prompt can be used to add custom instructions.

Current Text: "Use CLAUDE.md files or --append-system-prompt to add custom instructions to Claude Code's behavior."

While true, this statement is ambiguous. It implies they might work the same way, but they operate via two distinct and important mechanisms.

The Correct Mechanism (Found Elsewhere)

The Output Styles documentation page contains a crucial clarification that is easy to miss:

"CLAUDE.md adds the contents as a user message following Claude Code’s default system prompt. --append-system-prompt appends the content to the system prompt."

This is a critical distinction:

• --append-system-prompt modifies the system prompt, which sets the agent's core personality and rules.
• CLAUDE.md provides instructions as the first user message, which sets the context for the immediate conversation.

Suggestion

To prevent user confusion and improve the documentation's discoverability, I recommend moving the detailed explanation from the output-styles page to the settings page, as it is the more logical and primary location for this information.

Proposed Change

Enhance the "System prompt availability" section on the settings page to be more explicit:

Proposed Text: <Note> Unlike for claude.ai, we do not publish Claude Code's internal system prompt. However, you can significantly influence Claude's behavior using two primary methods: --append-system-prompt: This flag appends your content directly to the end of the base system prompt. This is useful for adding high-level, persistent rules that should govern all of Claude's behavior. CLAUDE.md files: The content of these files is provided as the first user message in a conversation, immediately following the system prompt. This is ideal for providing project-specific context, conventions, and task-level instructions. </Note>

This change would make the documentation much clearer, helping users understand precisely how to provide custom instructions for different use cases and leading to better, more predictable results.