Use --system-prompt to Fully Replace Claude's Default Prompt
When you need complete control over how Claude behaves, --system-prompt lets you replace the entire default system prompt with your own. This is different from --append-system-prompt, which adds to the existing prompt.
claude --system-prompt "You are a senior Python reviewer. Only flag security issues and performance problems. Ignore style."
This is powerful for building specialised tools on top of Claude Code. You can turn it into a focused code reviewer, a documentation writer, or a migration assistant with zero extra baggage from the default prompt.
You can also load the prompt from a file, which is cleaner for longer instructions:
claude --system-prompt-file ./prompts/security-audit.txt
A few rules to keep in mind. --system-prompt and --system-prompt-file are mutually exclusive, so pick one. But you can combine either with the append flags for layered control:
# Replace the base prompt, then add project-specific rules on top
claude --system-prompt-file ./base-prompt.txt --append-system-prompt "Always use TypeScript strict mode"
This works in both interactive and print mode, making it ideal for CI pipelines where you want a completely custom agent persona.
When you need Claude to be something specific, don't add to the default prompt. Replace it.
Log in to leave a comment.
When Claude writes error messages, button labels, validation text, or onboarding flows, it defaults to generic developer-speak. Add a "Users" section to your CLAUDE.md describing who your actual users are — their technical level, industry jargon, and what they care about — so Claude writes copy that makes sense to THEM, not to developers.
Use the --agent flag with custom markdown files in .claude/agents/ to launch purpose-built Claude sessions with restricted tools and scoped system prompts.
Every project has traps — the billing module that silently fails if you forget to queue the job, the legacy table with column names that don't match the model, the config value that must be set before tests run. Document these gotchas in your CLAUDE.md so Claude avoids the same mistakes your team spent days debugging.