Claude Code Custom Instructions Guide

What are Claude Code custom instructions?

Custom instructions tell Claude Code how to work with your specific project. Without them, Claude reads your files and makes reasonable guesses about your conventions, stack, and preferences. With custom instructions, it knows exactly what you expect.

The primary mechanism for custom instructions in Claude Code is the CLAUDE.md file. This is a markdown file that Claude reads automatically at the start of every session. You write it once, and every session inherits your rules. No copy-pasting prompts. No repeating yourself.

If you haven't set up a CLAUDE.md file yet, our CLAUDE.md explainer covers the basics. This guide goes deeper: how to write instructions that actually improve Claude's output versus instructions that waste context and create confusion.

Where custom instructions live

Claude Code loads instructions from multiple locations, and understanding the hierarchy matters. Instructions closer to your current working directory take priority over global ones.

Location	Scope	Use for
./CLAUDE.md	Project root	Project architecture, conventions, build commands
./src/CLAUDE.md	Subdirectory	Module-specific rules (e.g., frontend vs backend)
~/.claude/CLAUDE.md	Global (all projects)	Your personal coding style, universal preferences
~/.claude/projects/.../CLAUDE.md	Project-scoped global	Per-project overrides that you don't want in the repo
~/.claude/projects/.../memory/MEMORY.md	Auto-memory	Claude's own learned observations about your project

The layered system is powerful. Put universal rules in global config. Put project-specific rules in the project root. Put sensitive information (API endpoints, internal URLs) in the project-scoped global file so it stays off your repo.

Project-level vs user-level: what goes where

A common mistake is putting everything in one file. That creates bloated instructions and forces Claude to parse irrelevant rules for every task.

Global (~/.claude/CLAUDE.md) should contain:

• Your preferred language (TypeScript over JavaScript, for example)
• Universal style rules (semicolons, single quotes, tab width)
• How you like responses formatted (concise vs detailed)
• Tools and CLIs you always use

Project root (./CLAUDE.md) should contain:

• Tech stack and architecture overview
• Build, test, and deploy commands
• Directory structure explanation
• Project-specific naming conventions
• Known gotchas that trip up new contributors

This separation means when you start a new project, your personal preferences carry over automatically while project rules stay where they belong.

What makes instructions effective

The difference between good and bad custom instructions comes down to specificity. Vague instructions create vague behavior. Specific instructions create consistent output.

Bad instructions (too vague)

# CLAUDE.md

Write clean code.
Follow best practices.
Use good naming conventions.
Make sure tests pass.

These instructions are useless. "Clean code" and "best practices" mean different things to every developer. Claude already tries to write clean code by default. You've burned context tokens on instructions that add zero information.

Good instructions (specific and actionable)

# CLAUDE.md

## Stack
- Next.js 15 (App Router), TypeScript strict mode, Tailwind CSS
- Database: PostgreSQL via Drizzle ORM (schema in `src/db/schema.ts`)
- Auth: NextAuth v5 with GitHub + Google providers

## Conventions
- Components: PascalCase, one component per file, colocate styles
- API routes: `src/app/api/[resource]/route.ts` pattern
- Use `zod` for all input validation, never trust raw request bodies
- Error handling: throw typed errors from `src/lib/errors.ts`, never return raw strings

## Commands
- `pnpm dev` to start dev server (port 3000)
- `pnpm test` to run Vitest suite
- `pnpm db:push` to apply schema changes (NOT db:migrate)
- `pnpm lint` before any commit

## Known issues
- The `payments` module uses Stripe webhooks that require `raw` body parsing. Don't add JSON middleware to `/api/webhooks/stripe`.
- Legacy auth tokens in `src/lib/legacy-auth.ts` are being phased out. New code should use NextAuth sessions exclusively.

This version gives Claude everything it needs: the exact stack, the exact commands, the exact patterns, and the exact traps to avoid. Every line adds information that changes Claude's behavior.

The five categories every CLAUDE.md should cover

After working with hundreds of Claude Code configurations, five categories consistently produce the best results.

1. Architecture overview

Tell Claude what your project is and how it's structured. Two to three sentences plus a directory tree is enough.

## Architecture
E-commerce platform. Next.js frontend with Express API backend in a monorepo.

- `apps/web/` - Next.js storefront
- `apps/api/` - Express REST API
- `packages/shared/` - Shared types and utilities
- `packages/db/` - Drizzle schema and migrations

Without this, Claude wastes time exploring your file structure to understand what it's working with. With it, Claude knows immediately where to look for frontend components versus API routes versus database logic.

2. Coding conventions

Rules that aren't obvious from reading the code. If your convention matches common defaults, you don't need to state it. Focus on what's unique.

## Conventions
- Named exports only (no default exports)
- Barrel files (`index.ts`) in every module directory
- React components use `interface` for props, not `type`
- All async functions must have explicit error handling (no unhandled rejections)
- Database queries go through repository pattern (`src/repositories/`)

3. Build and test commands

The exact commands Claude should run. Don't assume Claude knows your package manager or test runner.

## Commands
- `bun run dev` - start dev server
- `bun test` - run all tests
- `bun test:unit src/path` - run specific test file
- `bun run build` - production build (must pass before any PR)

This matters because Claude uses the Bash tool to run commands. Wrong commands mean wasted time and confusing errors.

4. Behavioral rules

Things Claude should always or never do. These are your hard constraints.

## Rules
- Never modify `.env` or `.env.local` files
- Always run `bun test` after editing any file in `src/lib/`
- When creating new API routes, always add corresponding test file
- Never use `any` type - use `unknown` and narrow instead
- Commit messages follow Conventional Commits format

For even stronger enforcement of rules like these, combine them with Claude Code hooks that block violations at the tool level rather than relying on instructions alone.

5. Known gotchas

Things that will trip Claude up if it doesn't know about them. These save the most time per line of instruction.

## Gotchas
- The `auth` middleware in `src/middleware.ts` runs on ALL routes including API routes. Don't add redundant auth checks in API handlers.
- `prisma generate` must run after any schema change before tests will pass.
- The `legacy/` directory is frozen. Read from it but never modify it.
- Port 3001 is used by the API in dev mode. Don't start anything else on 3001.

Every gotcha you document is a debugging session you prevent. These are the highest-value lines in your entire CLAUDE.md.

Subdirectory instructions for large projects

For monorepos and large codebases, a single root CLAUDE.md gets unwieldy. Subdirectory CLAUDE.md files let you scope instructions to specific parts of the project.

project/
  CLAUDE.md              # Shared conventions, monorepo structure
  apps/
    web/
      CLAUDE.md          # Next.js-specific rules, component patterns
    api/
      CLAUDE.md          # Express-specific rules, middleware conventions
  packages/
    db/
      CLAUDE.md          # Schema conventions, migration rules

When Claude works in apps/web/, it reads both the root CLAUDE.md and the apps/web/CLAUDE.md. The subdirectory file can override root rules for that specific context. This keeps each instruction set focused and prevents the root file from becoming a 500-line monster.

Common mistakes to avoid

Restating defaults. "Use consistent indentation" or "follow TypeScript best practices" adds nothing. Claude already does this. Only state rules that diverge from common conventions.

Including implementation details. Your CLAUDE.md is for conventions and constraints, not for explaining how your code works. Claude reads your actual code for that. Don't duplicate your codebase in your instructions.

Making it too long. Every token in CLAUDE.md consumes context window space. A 200-line CLAUDE.md file is already pushing it. Audit your instructions quarterly and remove anything Claude consistently follows without being told.

Forgetting to update it. A CLAUDE.md that references a deprecated API or an old directory structure actively misleads Claude. Treat it like documentation that needs maintenance. If you change your stack, update the instructions.

Mixing project rules with personal preferences. If you commit CLAUDE.md to your repo (recommended for teams), keep personal preferences in your global config. Your teammates shouldn't have to work around your font size opinions.

Using custom instructions with memory

Custom instructions in CLAUDE.md are static. You write them, and they stay the same until you change them. Claude Code's memory system adds a dynamic layer on top.

The auto-memory file at ~/.claude/projects/.../memory/MEMORY.md is where Claude stores observations it learns during sessions. "This project uses pnpm, not npm." "The user prefers verbose error messages." "Tests in the integration/ folder need a running database."

The combination is powerful: CLAUDE.md sets your intentional rules, and memory captures the patterns Claude discovers through usage. Over time, Claude gets better at your project without you manually updating anything.

Configuring Claude Code beyond CLAUDE.md

CLAUDE.md handles behavioral instructions, but Claude Code has additional configuration surfaces worth knowing:

• .claude/settings.json controls hooks, permissions, and tool configurations
• .claude/commands/ stores slash commands for repeatable workflows
• .claude/skills/ provides domain knowledge Claude loads on demand

Together with CLAUDE.md, these form a complete Claude Code system prompt that shapes every interaction. The complete setup guide walks through configuring all of these.

FAQ

How long should my CLAUDE.md file be?

Keep it under 200 lines. Every line consumes context window tokens, which reduces the space available for your actual conversation. Focus on rules that change Claude's behavior. If removing a line wouldn't change how Claude works with your project, remove it.

Can I use CLAUDE.md to set the Claude Code system prompt?

CLAUDE.md instructions are appended to Claude Code's built-in system prompt. You cannot replace the system prompt entirely, but your CLAUDE.md instructions effectively override default behaviors for your project. Think of it as configuring Claude Code, not reprogramming it.

Should I commit CLAUDE.md to my git repository?

Yes, for team projects. It ensures every developer (and every Claude Code session) follows the same conventions. Keep sensitive information like internal URLs or API keys in the project-scoped global file (~/.claude/projects/.../CLAUDE.md) instead, which stays local to your machine.

Start with five lines, then grow

You don't need a perfect CLAUDE.md on day one. Start with five lines: your stack, your test command, your most important convention, your most common gotcha, and one behavioral rule. Run a few sessions. Notice where Claude makes wrong assumptions. Add an instruction for each one.

The best custom instructions aren't written in one sitting. They're accumulated through real usage, one frustration at a time.

Want a production-ready Claude Code configuration out of the box? Claudify ships with optimized CLAUDE.md templates, pre-built hooks, skills, and memory architecture for professional development workflows.