Skip to content
English
РусскийEnglish简体中文HindiEspañolPortuguês (BR)日本語FrançaisDeutsch한국어
Sign Up Free
Claude Code

CLAUDE.md in Claude Code: purpose and writing guide

Understand what CLAUDE.md does in Claude Code, what to include, what to avoid, and how it differs from hooks and MCP. Includes setup, examples, and fixes.

Quick answer

CLAUDE.md is a project instruction file that Claude Code can load as context. It is a good place for project structure, commands, coding conventions, testing expectations, security boundaries, and collaboration rules.

It is not an enforcement mechanism. Claude Code reads it as guidance. If a rule must run at a specific time, use hooks or tool configuration instead of relying only on CLAUDE.md.

A useful CLAUDE.md is short, specific, and maintained. Use it for project facts you would otherwise repeat in every session.

When this matters

  • Claude Code repeatedly asks about the same project structure or commands
  • Your team wants shared testing, style, or safety rules
  • You want to reduce repeated context and token usage
  • Claude Code keeps missing repository-specific conventions
  • You want other agents or teammates to onboard faster

Key concepts

ConceptMeaning
Project CLAUDE.mdShared project instructions, usually committed with the repository
Personal rulesUser-specific preferences that should not always be committed
Local rulesMachine-specific notes or temporary preferences
HooksCommands triggered around tool use; better for enforced behavior
MCPExternal tools and data sources; not a project rule file

Recommended content

Write CLAUDE.md as a compact project handbook:

  • What the project is and where important directories live
  • Common build, test, and formatting commands
  • Architecture boundaries to respect before editing
  • The fastest checks to run before finishing
  • Secrets, logs, or private config that must not be exposed
  • Documentation, test, naming, and error-handling conventions

Avoid long tutorials, temporary plans, and one-off task notes. If a rule only applies to one area, scope it more narrowly. If a behavior must be enforced, use hooks.

Common mistakes

  • Treating CLAUDE.md as a system prompt or hard permission layer.
  • Making it too long, which increases context cost and makes it harder to follow.
  • Appending old deployment notes, temporary TODOs, and outdated decisions forever.
  • Putting API Keys, tokens, cookies, or private config in the file.
  • Maintaining CLAUDE.md, AGENTS.md, and Cursor Rules with conflicting instructions.

About BetterToken

If a project uses BetterToken, CLAUDE.md can remind Claude Code that Claude Code uses the Anthropic-compatible https://bettertoken.ai, while Codex and external tools use the OpenAI-compatible https://bettertoken.ai/v1.

Do not put real API Keys in CLAUDE.md. Store them in local environment variables, local config files, or a protected secret system.

References