CLAUDE.md and AGENTS.md.
CLAUDE.md and AGENTS.md are text files in the root folder of a software project that a coding agent reads at the start of every session. They record how the project is structured, which commands apply and which rules must be followed. CLAUDE.md is the file for Claude Code; AGENTS.md is an open format read by several agent tools.
CLAUDE.md and AGENTS.md — Explained in Detail
A coding agent starts every session without any memory of the last one. So that it does not have to work out each time how a project functions, it reads a file with the essentials. In Claude Code it is called CLAUDE.md; other tools such as OpenAI Codex, Cursor or GitHub Copilot read AGENTS.md. Both are ordinary Markdown files, meaning text with headings and lists. They live in the project folder, are versioned with the code and are therefore the same for everyone on the team.
Typical contents: what the project is for, how it is structured, which commands start, check and test it, which files play central roles and which rules apply. Rules are often the most valuable part because they arise from mistakes: 'Never apply database changes automatically', 'Prices only from the central configuration', 'Copy in Swiss spelling with ss'. Many teams also keep a personal file with their own preferences that does not belong in the project.
AGENTS.md emerged in 2025 as a shared, vendor-neutral format so that a project does not need a separate file for every tool. The format is now stewarded by a foundation under the umbrella of the Linux Foundation. If you serve both worlds, keep the content in one place and reference it from the second file. These project files should be distinguished from agent skills: the project file is always loaded and applies to one project; a skill is loaded only when needed and can be reused across many projects.
A good project file is short, current and concrete. Every line costs space in the context window and the model's attention. Long essays with outdated information do more harm than good because the agent takes them seriously. A proven practice is to add a brief rule after every repeated mistake and to clear out the file regularly.
What belongs in a good project file
First, orientation: two or three sentences on the project's purpose and a short overview of the key folders and files. Second, commands: how to install, start, check and test, and which checks must pass before every change. Third, rules: what must never happen, which conventions apply, where the single source of truth for prices, copy or configuration lives. Fourth, open points and decisions, so the agent does not resolve something on its own that has not yet been decided.
Passwords, API keys and other secrets do not belong in it, because the file lives in the repository. Nor do long copies of documentation that can be looked up elsewhere. How we set up projects for work with AI agents is described on AI-assisted development and custom software Switzerland.
Example: the project file of an online shop
A constructed example: a wine merchant in Valais has its shop developed further with the help of a coding agent. After a few weeks it becomes apparent that the agent occasionally writes prices directly into pages instead of reading them from the product database, and that it uses German spelling with ß. Both have already led to corrections.
The developer adds two lines to the project file: 'Never type prices into the code, always read them from the product table' and 'Swiss spelling, ss instead of ß'. From the next session onwards the agent complies. The file grows with the project but stays short, because resolved points are deleted again.
Related Page
Agent SkillFrequently Asked Questions About CLAUDE.md and AGENTS.md
That depends on the tool. Claude Code reads CLAUDE.md; many other agents read AGENTS.md. If you use several tools, maintain the content in one file and reference it from the other so that two versions do not drift apart.
As short as possible, as long as necessary. Every line is loaded in every session and influences behaviour. Clear sections on structure, commands and rules work well. Outdated information should be deleted consistently, because otherwise the agent follows it.
No. The file lives in the repository and can be read by everyone with access. Credentials belong in environment variables or a password vault. At most, the project file states which variables exist and what they are used for.
More Terms Starting with "C"
CLS (Cumulative Layout Shift)
CLS is one of Google's three Core Web Vitals and measures the visual stability of a page. It quantif...
CMS (Content Management System)
A CMS (content management system) is software that lets you create and change a website's text, imag...
CDN (Content Delivery Network)
A CDN is a global network of servers that delivers your website files as close to the user as possib...
Ready for Your Project?
Apply this knowledge to your website — DLM Digital will help you.