Claude Code --append-system-prompt: Usage, examples and best practices

The Claude Code --append-system-prompt flag adds custom instructions without replacing the default system prompt. Use it to give the Claude Code CLI additional guidance about coding standards, testing, or response formats during a specific session. These instructions guide the session launched by that command; they do not permanently configure future launches. Below are patterns for interactive work, one-off requests, and reusable instructions, plus guidance on choosing between prompt files and CLAUDE.md.

What does --append-system-prompt do?

--append-system-prompt supplies additional runtime instructions while retaining Claude Code’s default system prompt. The official Claude Code CLI reference describes it as an append operation, not a replacement. It lets you request task-specific behavior without writing a complete system prompt, though it does not mechanically guarantee that every instruction will be strictly followed.

Conceptually:

• Default instructions remain rather than being replaced.
• Additional guidance is supplied through the flag.
• The resulting invocation uses that guidance.

For example, temporary TypeScript guidance can steer new code toward a chosen language. It does not mechanically prevent other file types.

Basic syntax:

claude --append-system-prompt "<additional instructions>"

claude --append-system-prompt "Always use TypeScript"

Replace the placeholder with your intended instruction. Quote text containing spaces according to your shell.

How to use --append-system-prompt

Keep the behavioral instruction separate from the work you want performed:

1. Start with claude.
2. Add --append-system-prompt.
3. Quote the instruction.
4. Optionally supply a task request.
5. Repeat the flag on future launches, directly or through a configured wrapper.

The following are Bash/zsh examples. Check local availability first:

claude --version
claude --help

Start an interactive session

claude --append-system-prompt "Preserve existing repository conventions."

This launches an interactive session with additional guidance. Its session scope concerns only that launch, not a permanent installation setting.

Start with an initial request

claude --append-system-prompt "Add tests for changed behavior." \
  "Fix the validation bug in the organization-invite flow."

The appended text is the behavioral rule. The positional text is the initial task. Use a concrete request that matches your repository context.

Use it in non-interactive mode

claude -p \
  --append-system-prompt "Prioritize authorization risks and cite file paths." \
  "Review the authentication module for security issues."

-p is short for --print: Claude processes the request and exits rather than opening an ongoing interactive conversation. Print mode is not inherently read-only.

Shell quoting differs across environments. Double quotes can still allow shell expansion, including $variables and command substitutions. A saved instruction file also needs explicit loading; saving it alone does not activate it.

Practical --append-system-prompt examples

These illustrative examples turn coding preferences into observable instructions; choose rules that fit the repository and inspect the resulting work.

Set a programming language or framework preference

claude --append-system-prompt "Always use TypeScript"

Use this temporary coding standard when new code belongs in a TypeScript project. Avoid imposing it on a mixed-language repository without narrowing its scope. Note that the instruction does not mechanically prevent Claude from creating other file types.

Require tests for behavior changes

claude --append-system-prompt "Add or update tests for changed behavior. Report which tests ran and their results."

This connects implementation changes to regression coverage and makes the final report easier to review. Always check both the test changes and execution results; a claim that tests passed is not independent verification.

Prioritize security review

claude --append-system-prompt "Prioritize authentication, authorization, and input-handling risks. Cite affected files and explain each finding."

Use this when reviewing organization membership, account access, or permission changes in a B2B SaaS repository. Prompted review supplements - not replaces - security scanners and human code review.

Keep final responses concise

claude --append-system-prompt "Keep final responses concise. Summarize changes, tests, and unresolved risks."

This gives reviewers a predictable summary structure without requesting a lengthy narrative. It does not guarantee lower token usage or latency.

Preserve existing repository conventions

claude --append-system-prompt "Preserve existing architecture, naming conventions, and dependency choices unless the requested change requires otherwise."

Use this to discourage unnecessary rewrites during focused maintenance. The exception matters: some tasks legitimately require architectural changes or new dependencies.

--append-system-prompt vs. other Claude Code options

Choose prompt configuration by purpose: temporary guidance, reusable runtime instructions, or maintained project knowledge.

The official Claude Code CLI reference distinguishes append and replacement flags. Its file-backed prompt options are documented for print mode; verify support in your installed release. The official Claude Code memory documentation explains location-based loading for CLAUDE.md.

Quick selection rule:

• Short temporary rule → inline append.
• Longer reusable runtime rules → supported append-file option.
• Shared maintained project guidance → CLAUDE.md.
• Intentional replacement of default guidance → replacement option.

Long inline strings become difficult to quote, compare, and review. A file makes editing easier, but must still be loaded explicitly:

claude -p --append-system-prompt-file ./review-rules.txt \
  "Review the organization-invite implementation."

CLAUDE.md does not replace the system prompt. Likewise, replacement flags should not be described as disabling permissions or safety controls: replacing prompt text is a different operation.

Common mistakes and limitations

A rejected argument is a configuration problem; an accepted instruction that Claude overlooks is a compliance problem. Check the invocation before rewriting the prompt.

Mistakes to avoid

1. Replacing unnecessarily: Choose append unless replacing default guidance is intentional.
2. Assuming persistence: Pass instructions again or use an explicitly configured launcher.
3. Writing vague rules: Replace “write good tests” with observable coverage requirements.
4. Keeping long instructions inline: Use a supported file-backed option and execution mode.
5. Ignoring shell-sensitive characters: Apply shell quoting and escaping for your actual environment.
6. Creating prompt conflicts: Reconcile task instructions, CLAUDE.md and other guidance.
7. Treating prompts as enforcement: Use tests, permissions, validation or appropriately configured blocking controls.
8. Assuming repeated flags accumulate: Check documentation and installed behavior; do not assume values concatenate.

If a file option is rejected, inspect claude --help and its documented mode restrictions. Do not treat saving a file as persistent configuration.

What the flag does not do

Limitations: It does not permanently change the installation, replace the default system prompt, or guarantee compliance. It cannot substitute for tests, permissions, policy checks, or review.

Deterministic enforcement requires mechanical controls. Those controls enforce only what they actually check; passing a test suite does not establish complete correctness.

Best practices and a reusable prompt template

Maintainable instructions are short enough to review and specific enough to evaluate. Use this checklist:

1. Keep instructions short.
2. Specify observable behavior.
3. Group related rules.
4. Store longer prompts in version-controlled files.
5. Keep shared project guidance visible.
6. Test on a low-risk task.
7. Recheck behavior after CLI updates.

Reusable template:

Follow these additional instructions:
- Use [language or framework] for new code.
- Preserve existing architecture and naming conventions.
- Add or update tests for changed behavior.
- Identify risky assumptions before making changes.
- Keep the final response concise.

Replace [language or framework], then explicitly pass the resulting text or load its file using a supported option. Placing an arbitrary file in the repository does not activate an append-file instruction.

Treat this template as a starting point, not a universal standard. For a small validation fix, inspect whether Claude preserved naming, updated relevant tests, and identified unresolved assumptions. Record the CLI version alongside observations.

Frequently asked questions

What does the --append-system-prompt flag do in Claude Code?

The --append-system-prompt flag allows you to add custom instructions to the end of Claude Code’s default system prompt. It retains the native agent harness - including tool definitions and safety policies - while injecting your specific behavioral guidelines for the duration of that session.

Does --append-system-prompt replace the default system prompt?

No, it does not. Unlike the --system-prompt flag, which completely substitutes the entire prompt, the append flag preserves the built-in system instructions. This ensures that essential agent capabilities, such as file-handling logic and tool execution, remain active and functional during your task.

How do I use a text file for my system prompt instructions?

You can use the --append-system-prompt-file <path> flag to load instructions from a local file. This is useful for managing complex or multi-line directives without needing to escape shell characters manually. Ensure you only use one append-file flag, as multiple instances will overwrite each other.

Can I customize subagent behavior separately from the parent agent?

Yes, as of Claude Code v2.1, you can use the --append-subagent-system-prompt or --append-subagent-system-prompt-file flags. These instructions are applied specifically to the background agents spawned during your session, which is particularly useful for controlling how delegated tasks, such as exploration or planning, are executed.

Why does my appended instruction seem to be ignored?

The Claude Code CLI parser typically honors only the last instance of an append flag provided in a single command. If you provide multiple flags, the last one will overwrite the previous ones. Additionally, verify that your instruction is quoted correctly to ensure the shell passes the string as a single argument.

Should I use --append-system-prompt or CLAUDE.md?

Use --append-system-prompt for ephemeral, session-specific or CI/CD script requirements where you need an immediate behavioral nudge. Use CLAUDE.md for long-term project conventions, architectural patterns, and repository-wide rules that you want to persist across all sessions for a specific project.

Does the appended prompt guarantee compliance with my instructions?

No. While appended instructions guide the model's behavior, they do not provide mechanical enforcement. For mission-critical requirements like security constraints or specific test execution, always complement your prompt instructions with appropriate repository tests, policy checks, or manual human review.

Read more:

• Claude Code CLAUDE.md guide: Best practices and 3 templates
• Claude Code slash commands: Essential shortcuts for CLI flow
• Claude Code Figma MCP setup: Remote vs desktop guide

Conclusion

Use Claude Code’s --append-system-prompt for short, invocation-specific instructions that supplement the default system prompt. Move longer runtime guidance into an explicitly loaded prompt file when your installed version and execution mode support it. Put maintained repository conventions in CLAUDE.md rather than repeatedly copying them into commands.

Start with one observable instruction, such as adding tests for changed behavior. Run a low-risk task, inspect the diff, and verify the reported tests. Appended guidance can make expectations clearer, but compliance still needs review. Copy the template above, adapt it to your repository, and confirm local CLI support before making it part of a shared workflow.