Use --append-system-prompt to Add Extra Instructions Without Replacing Your Defaults
The --system-prompt flag is powerful but blunt — it replaces all default instructions, including your CLAUDE.md. When you just want to add a temporary instruction without losing your project context, use --append-system-prompt instead.
# Add a constraint while keeping all your CLAUDE.md rules
claude --append-system-prompt "Focus only on performance. Flag any N+1 queries, unnecessary loops, or missing indexes."
# Add a security focus for a review session
claude --append-system-prompt "Scrutinize every change for security issues: injection, XSS, auth bypass, data exposure."
Your CLAUDE.md conventions, project architecture, build commands — everything stays loaded. The appended prompt just adds an extra layer on top.
This is especially useful in CI where different jobs need different focus areas but all share the same project context:
# CI: security-focused review
claude -p \
--append-system-prompt "You are a security reviewer. Only flag security concerns." \
"Review the changes in this PR"
# CI: performance-focused review
claude -p \
--append-system-prompt "You are a performance reviewer. Only flag performance concerns." \
"Review the changes in this PR"
Same project, same CLAUDE.md, different lens each time.
Some practical uses:
- Temporary constraints — "don't modify any test files this session"
- Role focus — "act as a database expert for this session"
- Output format — "always respond with code first, explanation after"
- Review angles — add a specific lens without losing project conventions
- Pair programming — "explain your reasoning before each change so I can learn"
The key difference: --system-prompt starts from scratch, --append-system-prompt builds on what's already there.
Keep your CLAUDE.md as the foundation and --append-system-prompt as the situational layer on top.
via Claude Code
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.