CLAUDE.md is Anthropic's project config file for Claude Code, now two years old with settled best practices for agent memory and context.
CLAUDE.md, Anthropic's project-specific configuration file for Claude Code, turned two years old in 2026 with a settled consensus on best practices. The file stores persistent instructions and context that optimizes the agent for complex, multi-step development tasks.
Key facts
- CLAUDE.md turned two years old in 2026.
- It provides persistent instructions for Claude Code.
- Best practices consensus emerged in 2026.
- Claude Code competes with Cursor and GitHub Copilot.
- Anthropic has not published an official CLAUDE.md spec.
CLAUDE.md is a configuration file that sits at the root of a project and provides Claude Code with persistent instructions, project context, and memory. Unlike ephemeral chat prompts, CLAUDE.md persists across sessions, enabling the agent to maintain consistent behavior across multiple coding steps [According to Claude.md Explained].
The file is part of Anthropic's broader strategy to make agentic coding tools more reliable. Claude Code, the terminal-based agent released in 2025, competes with Cursor and GitHub Copilot. CLAUDE.md serves as the memory layer that differentiates Claude Code from stateless alternatives — it remembers project conventions, dependencies, and architectural decisions without requiring the user to re-explain them each session.
How CLAUDE.md Works
The file uses a simple markdown format. Users write natural-language instructions covering coding style, testing preferences, dependency management, and architectural notes. Claude Code reads CLAUDE.md at the start of each session and uses it to ground all subsequent actions. The file supports variables and conditional logic, though Anthropic has not published formal schema documentation.
Two-Year Evolution
CLAUDE.md reached two years as a widely-used artifact in 2026. The community has converged on a set of best practices: keep instructions concise (under 200 lines), use explicit examples rather than abstract rules, and update the file as project conventions evolve [Per the knowledge graph]. This consensus marks a maturation of the agentic coding ecosystem, where configuration management has become as important as model capability.
Limitations
The source material is a beginner's guide and does not disclose adoption metrics, file size limits, or performance benchmarks comparing CLAUDE.md-equipped agents against baseline Claude Code. Anthropic has not published an official specification or changelog for the file format, leaving users to rely on community documentation.
What to watch
Watch for Anthropic to publish an official CLAUDE.md specification and schema, which would standardize the format and potentially enable cross-agent compatibility. Also track whether adoption metrics appear in Anthropic's next developer blog post.
[Updated 13 May via reddit_claude]
A critical billing flaw has emerged: Claude Code silently prioritizes an ANTHROPIC_API_KEY found in a project's .env file over Max subscription OAuth credentials, with no warning or opt-out. One user reported losing $187 in auto-recharge charges before discovering the switch. Anthropic confirmed to support that this is "intentional functionality" for authentication flexibility, but API credits consumed are non-refundable. Users can prevent this by clearing the environment variable before launching Claude Code [per Reddit PSA].
Originally published on gentic.news
Top comments (0)