CLAUDE.md

Programmers today often work together with AI assistants, that is, programs that write text and program code on instruction in ordinary language. One of these is Claude from the company Anthropic. For such an assistant to help in a meaningful way, it needs to know how the project is structured and which rules apply there. This is exactly what CLAUDE.md is for: a plain text file that sits in the project folder and records these rules in words. The AI reads it automatically before it starts working. You can think of it as a note posted at the workplace that every new temp reads first.

Why the AI needs a note

AI assistants have no memory beyond individual conversations. Every new session starts from zero. Without prior knowledge, the AI guesses: it invents folder names, uses the wrong commands, or writes in the wrong style. The human then has to correct the result by hand.

CLAUDE.md solves this problem by storing the knowledge in the project rather than in the chat. It states, for example, which command is used to test the program, which libraries are allowed, and which files must never be changed. This information is written down once and then applies to every session from then on.

Because the file lives in the project, the whole team benefits from it too. It can be shared like any other file using version control, that is, the system that logs all changes to a project. New colleagues also tend to read it gladly, since it is essentially a short operating manual for the project.

Structure and scope of the file

The .md extension stands for Markdown, a very simple notation for text files with headings and lists. You don’t need any special program for it, a text editor is enough. In terms of content, the file can be designed freely, but sections such as “Commands”, “Project Structure”, and “Style Rules” are common. Short, clear bullet points work better than long essays.

When Claude starts up in a folder, it looks for the file there and prepends its content to its own instructions. The text thus becomes part of what the model reads along with every response. In addition, CLAUDE.md files can be placed in subfolders, for instance a dedicated one for a particular part of the program. There is also a personal variant in the user directory that applies to all of a user’s projects.

One limitation is important: everything in the file takes up space in the so-called context window, that is, the limited amount of text the model can keep in view at once. An overloaded file with a thousand lines therefore costs computing time and money and gets followed less reliably. Experienced users therefore deliberately keep it concise and remove outdated content again. And one more point: the file is an instruction, not a technical lock. The AI can disregard rules; genuine prohibitions must be enforced by other means.

CLAUDE.md in practice and in the news

The term is most commonly encountered in the context of Claude Code, the tool with which Claude works directly in a project folder on the machine. On platforms like GitHub, where program code is shared publicly, tens of thousands of such files can now be found. Many teams publish their version as an example for others.

Competing providers use the same principle under different names, for instance Cursor with its own rule files. Because the coexistence of names became confusing, the neutral name AGENTS.md has established itself as a common standard, which Anthropic now also supports. CLAUDE.md is thus the best-known representative of an entire category.

In business news, the term comes up in discussions of productivity gains from AI in programming. It is a good example of the fact that the usefulness of such tools does not depend on the model alone. Anyone who describes the working environment cleanly gets noticeably more useful results than someone who uses the same model without any preparation.