Back to Learn
Concepts
7 min read

Claude Rules vs System Prompts: What's the Difference?

clauderules.net

Three Layers of Claude Instructions

Claude receives instructions from multiple sources, each with different scope and precedence:

API System PromptApplication-wide

Set by application developers via the Anthropic API. Shapes Claude's persona and capabilities for that application.

User Rules (~/CLAUDE.md)User-wide

Your personal global rules. Apply to every Claude Code session across all projects.

Project CLAUDE.mdProject-wide

Project-specific rules committed to the repository. Apply to all team members working on that project.

Subdirectory CLAUDE.mdDirectory-scoped

Module or feature-specific rules. Apply when Claude navigates into that directory.

System Prompts: Application-Level Control

System prompts are set by developers building products on top of Claude via the API. If you're using Claude.ai, claude.ai sets the system prompt. If you're using a third-party Claude app, that app controls it.

As a Claude Code user, you don't write system prompts — you write CLAUDE.md files. The distinction matters because:

  • System prompts take precedence over user rules
  • You cannot override a system prompt via CLAUDE.md
  • System prompts are typically not visible to end users

User Rules: Your Personal Defaults

The file at ~/.claude/CLAUDE.md (or the platform equivalent) applies to all your Claude Code sessions regardless of project.

Good candidates for user-level rules:

  • Your preferred response format (concise vs. verbose)
  • Languages and tools you always use
  • Personal quirks ("I prefer tabs over spaces")
  • Communication style preferences
~/.claude/CLAUDE.md
# My Global Rules

## Communication Style
- Be direct. Skip preambles like "Certainly!" or "Of course!"
- When showing code changes, show only the changed lines, not the full file
- Ask one clarifying question at a time, not a list

## My Preferred Tools
- Shell: zsh with Oh My Zsh
- Editor: VS Code with vim keybindings
- Package manager: npm (not yarn or bun)

## Code Style Defaults
- TypeScript strict mode always
- Prefer functional programming patterns
- Use early returns to reduce nesting

Project CLAUDE.md: Team Shared Context

Project CLAUDE.md files are the most important type for professional development. They encode team conventions that every developer on the project should follow, making Claude a consistent team member rather than a personal assistant.

A useful mental model: your user CLAUDE.md is like your personal dotfiles. Your project CLAUDE.md is like the team's engineering handbook — it applies to everyone, and everyone can contribute to it.

Precedence and Conflicts

When rules conflict, Claude generally follows this precedence (high to low):

  1. API system prompt
  2. Explicit instructions in the conversation
  3. Subdirectory CLAUDE.md (most specific)
  4. Project root CLAUDE.md
  5. User global CLAUDE.md

When writing rules, be explicit about intent: "This overrides the global preference for X in this project."

Frequently asked questions

What is the difference between CLAUDE.md and a system prompt?+

A system prompt is set by application developers via the Anthropic API and shapes Claude's persona for that application — you cannot override it from your own files. CLAUDE.md, by contrast, is a Markdown file you write yourself that Claude Code reads at the start of every session. System prompts are application-wide and typically invisible to end users; CLAUDE.md rules are project- or user-scoped and live in your repository or home directory. As a Claude Code user you don't write system prompts — you write CLAUDE.md files.

Can a CLAUDE.md file override an API system prompt?+

No. System prompts take precedence over user rules in the instruction hierarchy. If you're using Claude Code or Claude Desktop, the application sets the system prompt and your CLAUDE.md cannot override it. CLAUDE.md applies on top of the system prompt — it adds project- or user-specific context but cannot countermand application-level instructions. The full precedence order from high to low is: API system prompt, explicit instructions in the conversation, subdirectory CLAUDE.md, project root CLAUDE.md, then user global CLAUDE.md.

Where does my user-level CLAUDE.md file live?+

Your personal global rules file lives at ~/.claude/CLAUDE.md (or the platform equivalent). It applies to every Claude Code session you run, regardless of which project you're in. Good candidates for this file include your preferred response format (concise vs. verbose), languages and tools you always use, personal stylistic quirks like tabs vs. spaces, and communication-style preferences. Think of it as your personal dotfiles for Claude — it travels with you across projects rather than being committed to a specific repository.

What happens when rules from different sources conflict?+

Claude follows a fixed precedence order from highest to lowest: the API system prompt, explicit instructions in the current conversation, the most-specific subdirectory CLAUDE.md, the project root CLAUDE.md, and finally your user global CLAUDE.md. More-specific rules override more-general ones. When writing rules that intentionally override a higher-level preference, be explicit about it — for example, write "This project overrides the global preference for X" so that intent is clear to future readers and to Claude itself.

Should I put team-shared conventions in user CLAUDE.md or project CLAUDE.md?+

Project CLAUDE.md is the right place for any rule the whole team should follow. Project files are committed to the repository, so every developer and CI environment gets the same Claude behavior automatically. User CLAUDE.md is for your personal defaults — communication style, your preferred shell, your editor — things that aren't tied to a specific project. A useful mental model: user CLAUDE.md is like your dotfiles, project CLAUDE.md is like the team's engineering handbook that everyone contributes to.

Do system prompts apply to Claude Code sessions?+

Yes. Claude Code itself sets a system prompt that defines how Claude behaves as a coding assistant. You don't see it directly and you can't edit it, but it is the top of the instruction hierarchy and constrains everything below. Your CLAUDE.md sits below the Claude Code system prompt — it adds project context, conventions, and constraints, but cannot redefine Claude's fundamental role. This is why CLAUDE.md is useful for "how to work in this codebase" instructions rather than for changing Claude's identity.

Get the Claude Code Starter Pack

Top CLAUDE.md rules for Next.js, TypeScript, Python, Go, and React — delivered free to your inbox.

Back to all articles