Short answer: CLAUDE.md is the persistent context file that Anthropic’s developer tool Claude Code reads at the start of every session. By 2026 it supports four scopes (managed / project / user / local) and an imports syntax (
@path/to/file) for pulling in other files. The auto memory introduced in v2.1.59 lets Claude accumulate knowledge into aMEMORY.mdon its own; together the two give the project a two-layer memory. Between November 2025 and January 2026, Andrej Karpathy moved 80% of his coding routine to agent-driven coding, calling it “the biggest workflow shift in roughly 20 years of programming.” In April 2026 he published the idea file gist and redefined CLAUDE.md as the schema spine of a personal knowledge architecture made ofraw/(sources),wiki/(LLM-maintained knowledge base) andCLAUDE.md(schema). This guide unpacks every one of those innovations and what an effective CLAUDE.md looks like in 2026.
In this era of AI-fused software development, what you tell the AI and how you tell it decides how much real productivity you get back. Since March 2026, Anthropic’s official documentation moved to its new home (code.claude.com/docs/en/memory) and CLAUDE.md remains Claude Code’s most critical concept, while complementary layers — auto memory, path-scoped rules, imports, subagent memory — formed around it. Karpathy’s posts over the last six months pushed this mechanism beyond a plain config file and into the central knowledge architecture of AI-era software.
Andrej Karpathy: From Software 2.0 to the Idea File
Andrej Karpathy (b. October 23, 1986, Bratislava) is one of modern AI’s ten most influential engineers. He completed his computer science PhD at Stanford under Fei-Fei Li in 2016. Three stops shape the spine of his career: he was a founding researcher at OpenAI (2015–2017), then Tesla’s Director of AI (2017–2022) running the Autopilot Vision team, briefly rejoined OpenAI in 2023, and in 2024 founded Eureka Labs. His YouTube channel — home to the marathon “Let’s build GPT from scratch” lectures — has crossed 2 million subscribers.
Reading Karpathy as a pure technical researcher misses the point. He is also the designer of AI’s creative vocabulary. In Software 2.0 (2017) he argued that programs are increasingly “written” not by developers but by neural networks learning weights. Provocative in 2017, the sector’s shared reality in 2026. Vibe coding — building software by chatting with AI rather than typing it directly — is the term he popularised in early 2025. Agentic coding describes long-horizon task automation with autonomous models like Claude Code, Codex CLI, Aider and Cline.
The most recent break came between November 2025 and January 2026. In that window Karpathy moved 80% of his routine from manual coding to agent-driven coding and called it “the biggest workflow shift in roughly 20 years of programming.” Claude Code and its memory file — CLAUDE.md — sat at the centre of that shift. In April 2026 he pushed the topic a step further with the “idea file” concept: a new personal knowledge architecture based on sharing ideas, not code. In his words: “You just share the idea, then the other person’s agent customizes & builds it for your specific needs.”
📺 The starting point for this article is Karpathy’s keynote “Software Is Changing (Again)” at Y Combinator AI Startup School 2024. Vibe coding and agentic coding are summarised most clearly in that talk.
What Is CLAUDE.md and How Does It Fit With Auto Memory?
CLAUDE.md is the persistent instruction file you write and edit; Claude Code reads it at the start of every session. Anthropic’s docs put it plainly: “Instructions you write to give Claude persistent context.” In 2026 a second memory layer was added: auto memory. The split between them: you write CLAUDE.md (rules, architecture); Claude writes auto memory (insights it has inferred from your past corrections and preferences). Auto memory shipped with Claude Code v2.1.59 and persists at ~/.claude/projects/<project>/memory/MEMORY.md. At the start of each chat, the first 200 lines (or 25KB) of MEMORY.md get injected into context.
| Feature | CLAUDE.md | Auto memory |
|---|---|---|
| Author | You | Claude |
| Content type | Instructions and rules | Inferred learnings and patterns |
| Scope | Project, user or organisation | Per worktree |
| Loading | Fully each session | First 200 lines / 25KB each session |
| Main use | Code standards, architecture, workflow | Build commands, debug findings, preferences |
CLAUDE.md itself gained a richer structure in 2026. Four scopes are supported: organisation-wide managed policy files distributed by IT/DevOps (macOS at /Library/Application Support/ClaudeCode/CLAUDE.md, Linux at /etc/claude-code/CLAUDE.md, Windows at C:Program FilesClaudeCodeCLAUDE.md); team-specific project files (./CLAUDE.md or ./.claude/CLAUDE.md); user files covering all your projects (~/.claude/CLAUDE.md); and local files for project-only personal notes that go into .gitignore (./CLAUDE.local.md). More specific scopes override broader ones.
Loading mechanics widened too. Starting from the working directory, Claude walks upward to the filesystem root scanning every directory for CLAUDE.md and CLAUDE.local.md; all matches are pulled into context. CLAUDE.md files in subdirectories are not loaded at launch — they load on-demand when Claude reads a file in that directory. If you bring in extra directories with --add-dir, set the CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 environment variable to load their CLAUDE.md files too. After a compaction (/compact) the project-root CLAUDE.md is reloaded automatically; nested files come back with the next relevant read.
2026 New Features: Imports, .claude/rules/, AGENTS.md Interop
To stop CLAUDE.md from ballooning into one giant file, Anthropic standardised the @path/to/import syntax. It pulls other markdown files into CLAUDE.md; relative and absolute paths both work; recursion is allowed up to 5 hops deep. Typical usage:
See @README for project overview and @package.json for available npm commands.
# Additional Instructions
- git workflow @docs/git-instructions.md
- personal preferences @~/.claude/my-project-instructions.md
The second major addition is the .claude/rules/ folder and its path-scoped rules. Instead of cramming every instruction into one CLAUDE.md, split rules into topic-specific markdown files with YAML frontmatter that activates them only when Claude touches matching paths:
---
paths:
- "src/api/**/*.ts"
- "lib/**/*.{ts,tsx}"
---
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments
Rules files with no path frontmatter load every time; ones with it activate only when Claude is working in matching files. This is critical for monorepos where different teams maintain their own rule sets. The claudeMdExcludes setting also lets you selectively disable ancestor-directory CLAUDE.md files.
The third addition is AGENTS.md interoperability. Cursor, Codex, Aider and other agents read AGENTS.md; Claude Code only reads CLAUDE.md. The standard way to resolve the conflict now:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
Same instruction set shared across all your agent tools; the short Claude-specific section adds the extras. On the slash-command side: /init drafts the file, /memory lists currently loaded files and lets you edit them, and the InstructionsLoaded hook lets you debug what loaded when. Setting CLAUDE_CODE_NEW_INIT=1 turns /init into an interactive multi-phase flow: a subagent inspects the repo, asks you about gaps, and proposes a reviewable file before writing.
Karpathy’s Idea File Approach (April 2026)
On 3 April 2026, Karpathy proposed a new sharing format on X and then in a GitHub gist: the “idea file”. Classic open source is built on sharing code; an idea file shares the idea, and the other side’s agent rebuilds it for their environment. The reasoning was simple: in 2026 — with agent models strong enough — copying intent is more efficient than copying code pixel-by-pixel.
The concrete shape is a three-layer structure. Layer one is the raw/ folder: papers, articles, images, datasets land here. The LLM reads but never modifies this folder — sources are immutable and verifiable. Layer two is the wiki/ folder: LLM-produced summary pages, concept pages and entity pages live here, cross-referenced and growing cumulatively instead of being re-derived per query. Layer three is the CLAUDE.md file (alternatively AGENTS.md or OPENCODE.md), which defines the schema of the whole system and how it’s maintained.
The system runs three operations. Ingest: when a new source lands in raw/, the LLM reads it and simultaneously updates 10–15 wiki pages, keeps an index and an activity log. Query: questions go through the structure; valuable answers get filed back as new pages so knowledge compounds. Lint: periodic health checks surface contradictions, orphan pages, missing concepts and suggested reviews. Karpathy ties this to Vannevar Bush’s 1945 Memex concept; Bush’s unsolved “who maintains it?” question is finally answered by LLMs.
This architecture diverges from classic RAG (Retrieval-Augmented Generation) on one core point. RAG goes back to sources and synthesises on every query; the idea file approach compiles knowledge once and keeps it fresh, rather than re-deriving each time. In Karpathy’s words: “The knowledge is compiled once and then kept current, not re-derived on every query.” CLAUDE.md is the schema file that turns a generic chatbot into a disciplined wiki maintainer.
How to Write an Effective CLAUDE.md (2026 Standards)
Four principles from Anthropic’s own docs form the core of effective CLAUDE.md writing. Size: keep the file under 200 lines; longer files consume more context and reduce adherence. If instructions grow, split via path-scoped rules or imports. Structure: instructions grouped under markdown headings and bullets are far more scannable than loose paragraphs; Claude reads like a human. Specificity: write verifiable, concrete instructions. “Format code properly” → “Use 2-space indentation”; “Test your changes” → “Run npm test before committing”; “Keep files organised” → “API handlers live in src/api/handlers/“. Consistency: when instructions conflict, Claude picks one at random; review and refresh CLAUDE.md and nested CLAUDE.md files periodically.
When should something go into CLAUDE.md? Anthropic’s guidance is blunt: “Treat CLAUDE.md as the place you write down what you’d otherwise re-explain.” If Claude makes the same mistake twice, if a convention caught in code review is something Claude also needs to know, if you find yourself writing the same correction you wrote last session, or if a new teammate would need a piece of context to be productive — all of those are CLAUDE.md entries. Multi-step procedures or rules that apply to only a corner of the codebase belong in a skill or a path-scoped rule, not in CLAUDE.md itself.
The template below is the minimum functional starting point for a 2026 CLAUDE.md. Copy it directly into your project:
# Project Name
## What this is
One-paragraph summary of what the project does and why it exists.
## Tech stack
- Language: Python 3.12 / TypeScript 5.4
- Framework: FastAPI / Next.js 15
- DB: PostgreSQL 16
- Tests: pytest + httpx / vitest
## Commands
- Install: `uv sync` / `pnpm install`
- Run dev: `uv run uvicorn app.main:app --reload` / `pnpm dev`
- Test: `uv run pytest -x` / `pnpm test`
- Lint: `uv run ruff check .` / `pnpm lint`
- Typecheck: `uv run mypy app/` / `pnpm typecheck`
## Conventions
- Type hints everywhere
- Public functions: docstrings (Google style)
- Tests live in `tests/` matching `app/` structure
- No global state — pass dependencies explicitly
## Don't
- No emoji in code or commits
- No `print()` for debug — use `logger.debug()`
- No new dependencies without justifying in PR description
- Don't write code comments that just restate what code does
## Common pitfalls
- DB migrations: run `alembic upgrade head` after pulling
- The `vendor/` folder is git-tracked but not editable
- `pytest` requires `.env.test` (copy from `.env.test.example`)
## Architecture in 3 lines
- Request → middleware (auth) → router → service → repository → DB
- Async I/O end-to-end with `asyncpg`
- Background jobs in `app/jobs/` use `arq` (not Celery)
## Imports
@README.md
@docs/architecture.md
@AGENTS.md
Two extra pieces of advice from Karpathy’s practice: first, the “AI is a junior dev with infinite enthusiasm” analogy — the AI agent is like a talented but amnesiac junior developer who needs the morning briefing each day; CLAUDE.md is that briefing in writing. Second, the “living memory” principle: the file shouldn’t be a write-once-and-forget README — it should grow with every new mistake the AI makes.
CLAUDE.md vs Cursor Rules vs ChatGPT Custom Instructions
The three main AI coding tools store developer context in different ways. As of 2026 Claude Code’s CLAUDE.md system is the richest and most hierarchical — managed/project/user/local + path-scoped rules + auto memory + imports. Cursor offers a similar structure with markdown + YAML frontmatter inside .cursor/rules/, but lacks a user-level shared scope. ChatGPT Custom Instructions is tied to your OpenAI account, stored in the cloud, and consists of two free-text fields — no project context support.
| Dimension | CLAUDE.md (Claude Code) | Cursor Rules | ChatGPT Custom Instructions |
|---|---|---|---|
| Location | Repo + user + managed (org) | .cursor/rules/*.md |
OpenAI account (cloud) |
| Hierarchy | 4 scopes + nested + auto memory | Project only | User only |
| Format | Markdown + YAML frontmatter (rules) | Markdown + YAML frontmatter | Plain text (2 fields) |
| Imports | @path 5-hop recursive |
Limited | None |
| Path-scoped rules | ✅ .claude/rules/ + paths glob |
Partial | ❌ |
| Auto memory | ✅ v2.1.59+ | ❌ | ❌ |
| AGENTS.md interop | ✅ @AGENTS.md import |
❌ | ❌ |
| Version control | Yes (in Git) | Yes (in Git) | No (cloud-only) |
| Team sharing | Yes | Yes | No |
The practical takeaway: if you use all tools in the same project, write CLAUDE.md as the master source, import AGENTS.md from it, and copy 1:1 into .cursor/rules/ for Cursor. Put personal preferences only into ChatGPT Custom Instructions (e.g. “Reply in English, code comments in English”) — project details don’t belong there because they apply to every project in your account.
Practical Tips for Turkish Developers
CLAUDE.md adoption spread quickly across Turkey’s developer community from late 2025. You see it in side projects opened on GitHub by Insider, Trendyol, Hepsiburada, Getir and others. The shared rule across those projects is language consistency: code comments, error messages and docstrings should be in English; user-facing documentation can be in Turkish; PR descriptions are bilingual. A single line in CLAUDE.md does it: “Code comments, docstrings, error messages: English. Documentation in docs/: Turkish. PR descriptions: bilingual.”
The second issue you encounter in Turkish projects is encoding and locale. UTF-8 file encoding (no BOM), utf8mb4_unicode_ci database collation, and explicit tr_TR.UTF-8 for locale-sensitive sort tests are standard practice. Without that small note the classic “i / İ / ı / I” trap keeps producing bad results. The third critical block is regulation and local business rules: KVKK compliance (don’t log TC ID numbers), e-fatura inside the eFatura.NS namespace, TL pricing format adhering to f"{amount:,.2f} ₺" — none of which the AI can infer on its own.
A final tip: version CLAUDE.md with your team. Keep it on main and review every change in PR. A rule one developer adds becomes the team’s instant standard because the AI always reads the latest version. This is the foundation of the recent shift in Turkish engineering teams toward codifying technical standards together with the AI.
Frequently Asked Questions About CLAUDE.md
Are CLAUDE.md and auto memory the same thing?
No. CLAUDE.md is the file you write that explains rules and architecture. Auto memory is what Claude keeps on its own at ~/.claude/projects/<project>/memory/MEMORY.md — inferred preferences from past corrections. The two load together; neither replaces the other. Auto memory is available in Claude Code v2.1.59+.
What happens if ~/.claude/CLAUDE.md and ./CLAUDE.md conflict?
Both load and contents merge. For directly conflicting rules, the project level (./CLAUDE.md) wins because it’s more specific. Use the user level for “things I want in every project,” the project level for “rules unique to this project.”
How do @path imports work?
Writing @README.md or @~/.claude/preferences.md makes Claude pull that file into context. Both relative and absolute paths are supported. Max recursion is 5 hops — an imported file can import another, which can import another, but the 6th level is rejected. The first external import shows an approval dialog; declining it dismisses the dialog permanently.
What’s the difference between .claude/rules/ and CLAUDE.md?
CLAUDE.md always loads; files under .claude/rules/ with a paths frontmatter load only when Claude is processing a matching file. In big projects, the rules folder slices instructions by topic/path and reduces context spend. Rules files without a paths frontmatter carry the same priority as CLAUDE.md.
How do skills, plugins and subagents relate to CLAUDE.md?
Skills are heavier modules invoked on demand, not loaded each session. Plugins package MCP servers, slash commands and skill bundles for distribution. Subagents can keep their own auto memory (enable-persistent-memory). CLAUDE.md sits as the base context layer underneath all of these; task-specific flows move into skills.
Did Karpathy’s “idea file” concept redefine CLAUDE.md?
Not directly, but it widened its scope. Classic CLAUDE.md holds rules and commands. In Karpathy’s April 2026 proposal, CLAUDE.md additionally plays the role of the schema file governing raw/ (sources) and wiki/ (LLM-compiled knowledge). That moves CLAUDE.md from a command list into the centre of the knowledge management system.
Where do you follow Karpathy?
Four main channels: YouTube (@AndrejKarpathy) for marathon lectures, X / Twitter (@karpathy) for daily observations, GitHub (github.com/karpathy) for open-source projects like nanogpt, nanochat, makemore, micrograd, llm.c, and Eureka Labs (eurekalabs.ai) for AI-education platform announcements. The idea file gist is directly at gist.github.com/karpathy/442a6bf555914893e9891c11519de94f.
Conclusion: CLAUDE.md, the New Memory of AI-Era Software
CLAUDE.md is a simple-looking convention that is reshaping the nature of software development. By 2026 it’s no longer a single file but a system encompassing four scopes, imports, path-scoped rules, auto memory and idea-file architecture. As Karpathy points out: software’s new currency isn’t just code; it’s the context you give the AI. Keeping that context persistent, continuously updated and team-shared has become the new baseline configuration for modern software teams.
The practical plan is simple. Day one: start Claude Code in any open project of yours and run /init (ideally with CLAUDE_CODE_NEW_INIT=1). Day two: edit the generated draft against the template in this guide. Week one: every time the AI makes a mistake, add a one-liner to CLAUDE.md before fixing it. Week two: share with your team and bring it into PR review. A month later: if the file is approaching 200 lines, split via .claude/rules/ and start using @path imports. Three months later: consider Karpathy’s idea-file architecture with raw/ and wiki/ layers.
The recommendation is clear: treat CLAUDE.md with the same seriousness as README.md. Every line you’ve added in a month is a mistake the AI hasn’t made in a month. This investment compounds — the return grows as the weeks pass.
Sources
- Anthropic. Claude Code Documentation — How Claude remembers your project. code.claude.com/docs/en/memory (accessed 2026-05-01)
- Anthropic. Claude Code: Skills, Plugins, Hooks, Subagents documentation. code.claude.com/docs/en
- Karpathy, Andrej. Idea file — GitHub gist, April 2026. gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
- Karpathy, Andrej. X (Twitter) posts, @karpathy — 3 April 2026 idea-file tweet and follow-up discussions.
- Karpathy, Andrej. Software Is Changing (Again) — keynote, Y Combinator AI Startup School, 2024. YouTube: youtube.com/watch?v=LCEmiRjPEtQ
- Karpathy, Andrej. Software 2.0. Medium, November 2017. karpathy.medium.com/software-2-0-a64152b37c35
- Karpathy, Andrej. github.com/karpathy — CLAUDE.md and AGENTS.md examples in
nanogpt,nanochat,makemore,micrograd,llm.c. - Antigravity Codes. Karpathy’s LLM Wiki: The Complete Guide to His Idea File. antigravity.codes/blog/karpathy-llm-wiki-idea-file
- MCP Directory. Claude Code Best Practices: A Developer’s Guide (2026). mcp.directory/blog/claude-code-best-practices
Related reading: What Is Generation Alpha? 2026 Guide · 60 Business Ideas 2026: A List Built for the AI Era · Best Video Call Apps 2026 · How to Build a Daily Plan
