Skip to main content

​
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 LLMEasy

If a project uses LLMEasy, CLAUDE.md can remind Claude Code that Claude Code uses the Anthropic-compatible https://www.llmeasy.ru, while Codex and external tools use the OpenAI-compatible https://www.llmeasy.ru/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