Skills Playground / Guides / System Prompt

Claude Code System Prompt & Custom Instructions

Learn how to customize Claude Code's behavior with system prompts, CLAUDE.md instructions, project rules, and settings. Control exactly how Claude writes code, follows conventions, and operates in your projects.

Updated Feb 2026 8 min read Intermediate

How Claude Code Instructions Work

When you start a Claude Code session, Claude receives a system prompt that tells it how to behave. This prompt combines two layers:

  1. Built-in instructions from Anthropic — defines core capabilities like file editing, code search, terminal commands, git operations, and safety guidelines
  2. Your custom instructions from CLAUDE.md — defines your project conventions, rules, commands, and preferences

You can't modify the built-in system prompt directly, but your CLAUDE.md instructions are appended to it and can override default behaviors. This means you have full control over how Claude interacts with your codebase.

Key insight

Claude Code's built-in prompt says: "CLAUDE.md instructions OVERRIDE any default behavior and you MUST follow them exactly as written." This gives your custom rules top priority.

The Instruction Hierarchy

Claude Code loads instructions from multiple sources. They are merged in this order (highest priority first):

1. Project CLAUDE.md
./CLAUDE.md in your project root — highest priority, project-specific rules
2. Directory CLAUDE.md
./src/CLAUDE.md, ./packages/api/CLAUDE.md — context-specific overrides
3. Global CLAUDE.md
~/.claude/CLAUDE.md — personal preferences across all projects
4. Built-in System Prompt
Anthropic's core instructions — tool usage, safety, capabilities
File Scope Commit to Git? Use For
./CLAUDE.md Project Yes (shared) Team conventions, build commands, architecture
./src/CLAUDE.md Directory Yes Module-specific patterns, API conventions
~/.claude/CLAUDE.md Global No (personal) Editor prefs, personal coding style, aliases
.claude/settings.json Project Yes Permissions, allowed/denied tools
.claude/settings.local.json Personal No Personal overrides, local tool permissions

Writing CLAUDE.md (Your Custom Instructions)

CLAUDE.md is a plain Markdown file. Every line you write costs context tokens, so keep it concise. Focus on information Claude can't infer from your code.

Essential Sections

CLAUDE.md
# Project This is a Next.js 15 app with TypeScript, Tailwind CSS, and Prisma ORM. Database: PostgreSQL on Supabase. ## Commands - Build: `pnpm build` - Test: `pnpm test` - Test single: `pnpm test -- --grep "test name"` - Lint: `pnpm lint --fix` - Dev: `pnpm dev` (port 3000) ## Conventions - Use functional components with hooks, no class components - Use server components by default, add "use client" only when needed - Name files: kebab-case for files, PascalCase for components - Tests go in `__tests__/` directories alongside source files - Use `zod` for all validation, never trust raw input ## Architecture - `src/app/` - Next.js app router pages and layouts - `src/components/` - Reusable UI components - `src/lib/` - Utility functions and shared logic - `src/server/` - Server-only code (API routes, DB queries) - `prisma/` - Database schema and migrations ## Rules - NEVER use `any` type. Use `unknown` and narrow with type guards. - NEVER commit .env files or secrets - Always use parameterized queries, never string concatenation for SQL - Run `pnpm lint` before suggesting a commit

What to Include

What to Leave Out

Keep it under 200 lines

Long CLAUDE.md files waste context tokens on every interaction. Be ruthless about what you include. If Claude can figure it out from the code, don't put it in CLAUDE.md.

CLAUDE.md Examples by Project Type

Python / FastAPI

CLAUDE.md
# Project FastAPI backend with SQLAlchemy ORM and PostgreSQL. Python 3.12, using uv for dependency management. ## Commands - Run: `uv run uvicorn app.main:app --reload` - Test: `uv run pytest -x -q` - Lint: `uv run ruff check --fix .` - Format: `uv run ruff format .` - Migrate: `uv run alembic upgrade head` ## Conventions - Use Pydantic models for all request/response schemas - Use dependency injection for DB sessions - Async endpoints only, use `async def` - Type hints on all function signatures - Tests use pytest fixtures, not setUp/tearDown

React Native / Expo

CLAUDE.md
# Project React Native app with Expo SDK 52, TypeScript, NativeWind. ## Commands - Dev: `npx expo start` - Test: `jest --watchAll=false` - Build: `eas build --platform ios --profile preview` ## Conventions - Use Expo Router for navigation (file-based routing in app/) - Prefer NativeWind (Tailwind) over StyleSheet - Use expo-secure-store for sensitive data, never AsyncStorage - Components in components/, screens are app/ route files

Rust / CLI Tool

CLAUDE.md
# Project Rust CLI tool using clap for argument parsing. Minimum supported Rust version: 1.75. ## Commands - Build: `cargo build` - Test: `cargo test` - Run: `cargo run -- --help` - Lint: `cargo clippy -- -D warnings` ## Conventions - Use thiserror for error types, anyhow for error propagation - Prefer &str over String in function parameters - Use #[derive(Debug, Clone)] on all public types - No unwrap() in library code, only in tests and examples

Global Settings & Rules

Your global CLAUDE.md at ~/.claude/CLAUDE.md applies to every project. Use it for personal preferences:

~/.claude/CLAUDE.md
## Preferences - Use bun instead of npm for JavaScript projects - Prefer single quotes in TypeScript - Don't auto-commit; always ask first - When writing tests, use describe/it pattern with clear test names ## Git - Write commit messages in conventional commit format - Don't use git add -A; always add files individually - Never force push to main
Global vs Project

Project CLAUDE.md overrides global CLAUDE.md when they conflict. Use global for personal style preferences and project for team conventions.

settings.json (Permissions & Controls)

The .claude/settings.json file controls which tools Claude Code can use without asking permission:

.claude/settings.json
{ "permissions": { "allow": [ "Bash(npm run lint)", "Bash(npm run test*)", "Bash(npm run build)", "Read", "Glob", "Grep" ], "deny": [ "Bash(rm *)", "Bash(git push --force*)", "Bash(curl *)" ] } }
Permission Description
allow Tools that run without asking. Use glob patterns: Bash(npm run *)
deny Tools that are always blocked, even if Claude thinks they're needed

For personal overrides that shouldn't be committed to the repo, use .claude/settings.local.json with the same format.

Skills as Specialized System Prompts

Claude Code skills are essentially reusable system prompt fragments. Each skill has a SKILL.md file that works like a focused CLAUDE.md for a specific task:

skills/tdd-expert/SKILL.md
--- name: TDD Expert description: Write tests first, then implementation --- You are a strict Test-Driven Development expert. ALWAYS follow the Red-Green-Refactor cycle: 1. Write a failing test FIRST 2. Write minimum code to pass 3. Refactor only when green 4. One test at a time NEVER write implementation without a failing test.

Skills are activated when relevant to the conversation. Browse the Skills Directory to find pre-built skills, or create your own.

Advanced Instruction Techniques

Conditional Rules

Use directory-specific CLAUDE.md files to apply different rules to different parts of your codebase:

src/api/CLAUDE.md
## API Layer Rules - All endpoints must validate input with zod schemas - Always return proper HTTP status codes (not just 200) - Log all errors to Sentry with structured metadata - Rate limit all public endpoints
src/components/CLAUDE.md
## Component Rules - Use React Server Components by default - All components must have TypeScript prop interfaces - Include aria labels for interactive elements - Use CSS modules, not inline styles

Override Default Behaviors

Claude Code has built-in behaviors you can override with explicit instructions:

CLAUDE.md (overrides)
## Overrides - When I say "commit", use this format: `type(scope): message` - When I say "test", run `bun test` not `npm test` - When creating files, use .tsx extension, never .jsx - When importing, use `@/` path alias, never relative paths deeper than 2 levels - NEVER add comments to code unless I explicitly ask - NEVER add docstrings or JSDoc unless I ask - NEVER refactor code you weren't asked to change

Template Variables

Reference dynamic values in your instructions that Claude can resolve from context:

CLAUDE.md
## Deployment - Staging URL: https://staging.myapp.com - Production URL: https://myapp.com - Deploy with: `git push origin main` (triggers CI/CD) - Database migrations run automatically on deploy When fixing bugs, check the staging environment first at the staging URL.

Embedding External References

Keep CLAUDE.md lean by pointing to external docs:

CLAUDE.md
## References - API docs: see docs/api.md - Database schema: see prisma/schema.prisma - Component patterns: see docs/components.md - For environment setup: see CONTRIBUTING.md

Troubleshooting

Claude isn't following my instructions

Context is too large

Instructions conflict between files

When project CLAUDE.md says one thing and global CLAUDE.md says another, the project file wins. For directory CLAUDE.md files, the most specific (deepest) directory wins.

Frequently Asked Questions

Can I see the full system prompt Claude Code uses?

The built-in system prompt is visible in the Claude Code open-source repository on GitHub. Your CLAUDE.md is appended to it. Use /doctor inside Claude Code to see what configuration files are being loaded.

How often is CLAUDE.md reloaded?

CLAUDE.md is loaded at the start of each session. If you edit it during a session, start a new session for changes to take effect. The file is not hot-reloaded within an active session.

Can I use CLAUDE.md to restrict what Claude can do?

CLAUDE.md can set behavioral rules (like "never use any type"), but for hard permission controls, use .claude/settings.json. The deny list in settings.json provides enforcement that can't be overridden by conversation.

What's the difference between CLAUDE.md and a skill?

CLAUDE.md provides always-on instructions for your project. Skills are activatable instructions for specific tasks. Think of CLAUDE.md as your project's constitution and skills as specialized experts you call in when needed. See Skills vs MCP for a deeper comparison.

Should CLAUDE.md be committed to git?

Yes, commit ./CLAUDE.md and .claude/settings.json so the whole team benefits. Personal preferences go in ~/.claude/CLAUDE.md (global, not committed) and .claude/settings.local.json (personal, gitignored).

Related Guides

Memory Guide CLAUDE.md, auto memory, and context management Install Guide Step-by-step setup for macOS, Linux & Windows Hooks Guide Automate workflows with event-driven hooks Plugins Guide Extend Claude Code with custom plugins Best Practices Tips for effective AI-assisted development Skills vs MCP Choose the right extension mechanism Cheat Sheet Quick reference for commands and shortcuts Agents Guide Build autonomous coding agents Slash Commands Create custom commands for workflows Claude Code vs Cursor Detailed feature comparison Browse Skills Discover ready-to-use Claude Code skills MCP Directory Find MCP servers to extend Claude Code GitHub Guide Pull requests, Actions & git workflows Pricing Guide Cost, API rates & subscription plans Docker Guide Containers, dev containers & sandboxed environments Permissions Guide Sandbox, security & access controls SDK Guide Build custom AI agents programmatically CLI Reference Master every command, flag, and shortcut