CLAUDE.md and AGENTS.md: Permanent Instructions for Agents

What are they and how are they alike?

AGENTS.md is an open format in plain Markdown with no required fields, now stewarded by the Agentic AI Foundation under the Linux Foundation. According to its site, it works as “a README for agents”: it gathers the context that would clutter a README written for people, such as build and test steps and conventions. You can put one in each subproject, agents read the closest one to the code being edited, and what you write in chat overrides all of them. Codex, Cursor, Gemini CLI and GitHub Copilot, among others, read it.

In Codex, the global file lives in ~/.codex (AGENTS.md, or AGENTS.override.md if it exists). From the project root down to the working folder it takes one file per folder, and the closest ones come later and take precedence. It stops once the combined content reaches 32 KiB, the default for project_doc_max_bytes.

CLAUDE.md is Claude Code’s equivalent, and it can live in several places:

AGENTS.md has a catch. By default, Claude Code reads it only when no CLAUDE.md (or CLAUDE.local.md) exists in the working folder or above it; if both exist, it reads only the CLAUDE.md files. To keep a single file for every tool, create a CLAUDE.md that starts with the line @AGENTS.md and add the Claude-specific parts below. Reading AGENTS.md directly requires Claude Code 2.1.277 or later.

Claude Code also keeps automatic memory: notes the agent writes itself from your corrections, in ~/.claude/projects/<project>/memory/. From its MEMORY.md index, the first 200 lines or 25 KB are loaded. That limit belongs to automatic memory, not to CLAUDE.md.

Why does it matter to a designer?

Because in a vibe coding or agent-driven design workflow, this file is where product decisions get translated into rules the agent follows:

• Tokens and tone. If the design system uses certain tokens and not others, writing it down stops the agent from inventing colors.
• Existing components. “Use the Button component from the system; do not create new buttons” prevents duplicates.
• Review criteria. What “done” means for an interface change: accessibility tests, screenshots, contrast.
• Boundaries. Which files or folders must not be modified without human review.

In practice, it is a way of documenting design judgment so that the AI can use it.

What goes in and what stays out?

Include:

• Exact commands to install, build, test and run the project.
• Conventions that are not obvious to someone new.
• Architecture decisions with a short reason.
• What the agent must never do.

Leave out:

• Project history and anecdotes.
• To-do lists, which change every week and belong in a task manager.
• Secrets and keys, which must never be in a versioned file.
• Long instructions that contradict other sections.

How do you write it so it gets followed?

The Claude Code documentation makes clear that these files are context, not mandatory configuration. For the agent to follow them:

1. Be concrete. “Use pnpm, not npm” is followed better than “use the appropriate package manager.”
2. Be brief. The documentation suggests under 200 lines per CLAUDE.md. If it grows, split it into rules by file type. The /init command generates a first draft from the code.
3. Put the critical items first. What must never break goes at the top.
4. If something must always be blocked, do not rely on the text: use a PreToolUse hook or a technical rule that prevents the action.
5. Review it every time the agent makes a mistake. A repeated error points to a missing or misunderstood instruction.

Example

Illustrative example: a product team keeps a 400-line CLAUDE.md with project history, pending tasks and style rules. The agent ignores half of it, because the rules are buried. The team cuts it to 60 lines: commands, three design-system rules, a list of protected folders and the definition of “done.” Tasks move to Linear and the history moves to the product documentation. The agent follows the rules more consistently, and the file is reviewed whenever a new error appears.

How do you organize it as the project grows?

A single file works while the project fits in the head of whoever maintains it. When it grows, it is worth splitting. Claude Code supports rules in .claude/rules/*.md, one file per topic. If the file declares paths in its header (for example src/api/**/*.ts), it loads only when Claude works with matching files: component conventions take no context while you change the API. Another option is a CLAUDE.md inside each subproject: it loads when Claude reads, writes or edits a file in that folder.

Note that in Claude Code files do not override each other, they are concatenated, and the one closest to the working directory is read last. If two rules contradict each other, Claude may follow either one, so each rule should live in one place. @imports help organize a long file but do not reduce its context cost, because they load together with it. This organization also decides what is spent in each session, so it relates to agent memory and context engineering. What is a procedure rather than a fact is better moved into one of the skills.

What you can do tomorrow

Open the instructions file of a project and count its lines. Then mark the ones that are facts that always apply, the ones that are procedures, and the ones that are history or pending tasks. Move the history and the tasks out of the file, turn one of the procedures into a skill and keep the facts in the main file. Run a real task with the agent and note the first mistake it makes: that new or corrected line is the next improvement.

Common mistakes

• Turning CLAUDE.md into a 1,000-line manual nobody reads.
• Putting keys or credentials in the file.
• Leaving contradictory instructions across CLAUDE.md, AGENTS.md and rules.
• Believing a written instruction is the same as a technical prohibition.
• Forgetting to update the file when commands or the design system change.

Sources

• AGENTS.md, official format site
• How Claude remembers your project, Claude Code documentation
• AGENTS.md in Codex, OpenAI documentation