How do I write a CLAUDE.md file that keeps Claude Code consistent across a large codebase, and what belongs there versus

A CLAUDE.md file acts as the "system prompt" for your codebase. It sets the behavior, style, and constraints for Claude Code, ensuring consistency as the project scales.

How to write a CLAUDE.md

Think of this file as a brief, authoritative manual. Keep it high-level and focus on rules that apply globally.

Structure it clearly using headings:

1. Project Overview: A one-sentence summary of what the project does.
2. Tech Stack: Explicitly state the primary languages and frameworks.
3. Core Principles: Rules you want followed every time (e.g., "Always prefer functional programming patterns," or "Never introduce external dependencies without a ticket").
4. Testing Strategy: Rules for writing tests (e.g., "All new features must include a unit test," or "We follow TDD").
5. Coding Standards: Key formatting or naming conventions that aren't strictly enforced by linters.

Example snippet:

Coding Standards

• Use TypeScript with strict: true.
• Prefer explicit interfaces over type aliases for public APIs.
• Always add JSDoc comments to exported functions.

---

CLAUDE.md vs. Custom Slash Commands

The boundary between these two comes down to Behavior (Global) vs. Task (Actionable).

Put it in CLAUDE.md if:

• It’s a Rule: Something Claude should do (or avoid) in every interaction.
• It’s Contextual: High-level project information that helps Claude understand the "why" behind your code.
• It’s Global: Applies to every file and every developer working on the repo.
• Examples: "Always use Tailwind for styling," "Our database schema is in /prisma," or "Do not use any types."

Put it in Custom Slash Commands if:

• It’s a Workflow: A repeatable sequence of steps you perform often.
• It’s Conditional: Things you only need sometimes, rather than every time Claude modifies a file.
• It’s Scoped: Tasks that involve specific, multi-step orchestration (e.g., scaffolding a new component or running a specific complex test suite).
• Examples: /new-component (scaffolds files), /check-security (runs a specific linting/security scan), or /refactor-api (applies a specific set of refactoring patterns).

Summary

• CLAUDE.md creates the environment and the standards.
• Slash commands execute the workflows and shortcuts.

If you find yourself repeating the same instructions in every chat, add them to CLAUDE.md. If you find yourself manually directing Claude through the same 5-step process every day, create a custom slash command.