# Claude Code System Prompt Customization Guide

## The Three Methods

### Method 1: Output Styles (Recommended for Most Use Cases)

**What it does:** Replaces Claude's default "Tone and style" and "Doing tasks" sections with your custom instructions.

**When to use:** General behavior changes, coding style preferences, response formatting.

**Setup:**

1. Create a file in your project: `.claude/output-styles/my-style.md`

2. Add your instructions:

```markdown
# Development Style

## Code Quality
- Write clean, self-documenting code
- Prioritize readability over cleverness
- Add comments only for complex logic

## Response Format
- Be direct and concise
- Show code first, explain after
- Use bullet points for lists

## File Handling
- Never create files without explicit permission
- Always show full file paths before modifications
- Confirm destructive operations

## Objectivity
- Present trade-offs honestly
- Avoid marketing language
- Cite sources when making technical claims
```

3. Set it in `.claude/settings.json`:

```json
{
  "outputStyle": "my-style"
}
```

**Token budget:** Keep under 500 tokens (~375 words)

---

### Method 2: --append-system-prompt (For Project-Specific Rules)

**What it does:** Adds instructions on top of Claude's defaults without replacing anything.

**When to use:** Project-specific context, tech stack requirements, team conventions.

**Setup:**

1. Create a file: `.claude/project-context.md`

```markdown
## Project Context
- Next.js 14 with App Router
- TypeScript strict mode enabled
- Tailwind CSS for styling
- Supabase for backend

## Team Conventions
- Use named exports, not default exports
- Prefix private functions with underscore
- Keep components under 200 lines
- Write tests for all business logic

## Current Sprint Focus
- Implementing user authentication flow
- Prioritize security over convenience
```

2. Launch Claude Code with the flag:

```bash
claude --append-system-prompt "$(cat .claude/project-context.md)"
```

**Pro tip:** Create an alias in your shell config:

```bash
# Add to ~/.zshrc or ~/.bashrc
alias cc='claude --append-system-prompt "$(cat .claude/project-context.md)"'
```

**Token budget:** Keep under 300 tokens (~225 words)

---

### Method 3: --system-prompt (Nuclear Option)

**What it does:** Replaces the ENTIRE system prompt (except tool definitions).

**When to use:** Specialized use cases where default behavior interferes with your needs.

**Setup:**

1. Create a complete system prompt: `.claude/custom-system.md`

```markdown
You are a senior software engineer specializing in React and TypeScript.

## Core Responsibilities
- Write production-ready code
- Identify edge cases and potential bugs
- Suggest performance optimizations
- Follow SOLID principles

## Code Style
- Functional components with hooks
- TypeScript with strict typing
- Descriptive variable names
- Extract magic numbers to constants

## Communication
- Ask clarifying questions before coding
- Explain your reasoning for architectural decisions
- Point out potential issues proactively
- Be honest about limitations

## Tools Usage
- Use read_file before editing
- Show diffs for large changes
- Create backups for risky operations
```

2. Launch with:

```bash
claude --system-prompt "$(cat .claude/custom-system.md)"
```

**Warning:** You're responsible for ALL instructions. Test thoroughly.

**Token budget:** 500-800 tokens max (~375-600 words)

---

## Practical Examples

### Example 1: Python Data Science Project

**Output Style:**

```markdown
# Data Science Assistant

## Code Standards
- Use type hints for all functions
- Follow PEP 8 style guide
- Prefer pandas/numpy vectorized operations over loops
- Document complex algorithms with docstrings

## Analysis Approach
- Show data shape and types before operations
- Validate assumptions with assertions
- Handle missing data explicitly
- Plot results when relevant

## Communication
- Explain statistical choices
- Warn about data quality issues
- Suggest alternative approaches
```

---

### Example 2: Fast-Paced Startup

**Append System Prompt:**

```markdown
## Startup Context
- Move fast, iterate quickly
- MVP mindset: working > perfect
- Tech debt is acceptable if documented
- Deploy daily

## Current Priorities
1. User authentication (in progress)
2. Payment integration (next)
3. Email notifications (backlog)

## Stack
- Remix + TypeScript
- Prisma + PostgreSQL
- Stripe for payments
- Resend for emails
```

---

### Example 3: Security-Critical Application

**Custom System Prompt:**

```markdown
You are a security-focused software engineer.

## Security First
- Validate ALL user inputs
- Use parameterized queries (never string concatenation)
- Implement rate limiting
- Log security events
- Never expose sensitive data in errors

## Code Review Mindset
- Look for injection vulnerabilities
- Check authentication/authorization
- Verify data encryption at rest and in transit
- Flag hardcoded secrets

## Before Writing Code
- Ask about security requirements
- Identify sensitive data flows
- Consider attack vectors
```

---

## Combining Methods

**Best practice:** Use Output Style + Append System Prompt together

```bash
# .claude/settings.json
{
  "outputStyle": "coding-style"
}

# Launch command
claude --append-system-prompt "$(cat .claude/project-context.md)"
```

**Order in final prompt:**
1. Output Style (your general behavior)
2. Appended prompt (project specifics)
3. Tool definitions (Anthropic's bloat)

---

## Token Management

**Check your token count:**
- Use: https://claude-tokenizer.vercel.app/
- Tool definitions alone: ~11,438 tokens
- Your budget: 500-800 tokens total
- Context degradation: starts at 80k tokens

**Keep it lean:**
- Remove fluff words
- Use bullet points
- Be specific, not verbose
- One instruction per line

---

## Quick Decision Tree

```
Need to change how Claude responds?
├─ Yes → Use Output Style
│
Need project-specific context?
├─ Yes → Add --append-system-prompt
│
Need to replace everything?
├─ Yes → Use --system-prompt (carefully)
│
Just want defaults?
└─ Do nothing, defaults are fine
```

---

## Common Pitfalls

1. **Too verbose:** 2000-token prompts kill context. Stay under 800.

2. **Conflicting instructions:** Output Style says "be verbose," append says "be concise" → Claude gets confused.

3. **Forgetting file handling rules:** Always preserve Claude's default file safety instructions.

4. **Not testing:** Changes affect ALL interactions. Test with simple tasks first.

5. **Over-engineering:** Start with Output Styles. Only escalate if needed.

---

## Testing Your Setup

```bash
# Test 1: Check if instructions are followed
echo "Write a simple hello world function" | claude

# Test 2: Verify file handling
echo "Create a test file" | claude

# Test 3: Check tone/style
echo "Explain async/await" | claude
```

If behavior seems off, reduce token count first.