How to Write CLAUDE.md and AGENTS.md for AI Coding Agents

The first impression of running a new AI coding agent on an existing repo is usually disappointment: the agent knows the project's name, but has no idea which package manager you use, what the test command is, or which folder it should never touch. The answer to "how do you write CLAUDE.md and AGENTS.md" starts right here — the agent isn't dumb, just contextless. This article explains what CLAUDE.md and AGENTS.md are for, in what order they're read, and what should and shouldn't go into them, using the mechanisms current as of November 2025.

💡 Pro Tip: Don't think of the context file as "documentation" — think of it as a resource that gets pulled into context automatically every session and consumes tokens. The longer it is, the more expensive it is.

Table of Contents

• Why your agent gets dumb on your project — the missing context
• AGENTS.md: a tool-agnostic contract
• CLAUDE.md: project memory loaded automatically at session start
• Priority order: global rule, project rule, subfolder rule
• What to write: commands, architecture boundaries, prohibitions, proof expectations
• What NOT to write: documentation copies, changelogs, bloated lists
• Measuring context cost: why you should keep it short
• Template: a 30-line minimum core
• Quick editing: the `#` shortcut and the `/memory` command
• FAQ
• What's the difference between CLAUDE.md and AGENTS.md?
• What should a good project context file contain, and how long should it be?
• In what order do rules take effect (global, project, subfolder)?
• Does the context file burn tokens every session?
• Update (September 2026)
• Conclusion
• Sources

Why your agent gets dumb on your project — the missing context

When a coding agent starts a new conversation, all it has is the model's general training plus your current request; it doesn't know your repo's history, your team's conventions, or the "why we did it this way" decisions. Claude Code fills this gap with a special file called CLAUDE.md: a file Claude automatically pulls into context at conversation start, ideal for things like bash commands, file structure, code style, and testing instructions (Anthropic, "Claude Code: Best practices for agentic coding," published April 2025; web.archive.org 2025-11-08 snapshot). So the agent "getting dumb" isn't a model limitation — it's a missing-context problem, fixed by putting the right file in the right place.

AGENTS.md: a tool-agnostic contract

AGENTS.md emerged to solve a different problem: if every coding-agent tool has its own context-file format (CLAUDE.md for Claude Code, a different name for another tool), teams running the same project with multiple agents end up writing the same information over and over. AGENTS.md instead proposes a tool-agnostic, plain-Markdown "README for agents." As of November 18, 2025, agents.md stated it was used in more than 20,000 open-source projects (agents.md, web.archive.org 2025-11-18 snapshot). At that date, the list of tools agents.md supported included Codex, Jules, Factory, Aider, Kilo Code, Phoenix, Semgrep, GitHub Copilot Coding Agent, Ona, UiPath, Amp, Cursor, RooCode, Gemini CLI, opencode, Zed, Warp, VS Code, and Devin — Claude Code was not yet on that list.

This meant Claude Code didn't read AGENTS.md on its own at the time; nothing stopped you from writing the file, and you could load it into Claude Code with a single line, @AGENTS.md, in the root CLAUDE.md (import mechanism 0.2.107, May 9, 2025). Both files serve the same purpose — project context — just under different names in different ecosystems.

CLAUDE.md: project memory loaded automatically at session start

Claude Code offers a four-layer memory hierarchy: Enterprise policy (organization-wide, managed by IT), Project memory (shared with the team, committed to the repo root as ./CLAUDE.md), User memory (~/.claude/CLAUDE.md, personal preferences across all projects), and Project memory (local) — ./CLAUDE.local.md (code.claude.com/docs/en/memory, web.archive.org 2025-11-13 snapshot). This fourth layer was already deprecated at that date, in favor of the import mechanism — imports work better across multiple git worktrees (same source). So in practice, two files remained for project context: the team-shared CLAUDE.md and the personal ~/.claude/CLAUDE.md.

The enterprise policy file's path was fixed per operating system: /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux, C:\ProgramData\ClaudeCode\CLAUDE.md on Windows (same source, 2025-11-13 snapshot) — the user cannot access this file, it's distributed centrally by IT, and it's loaded with the highest priority.

Seeing all four layers together clarifies which one goes into git and which one stays personal:

In practice, this table answers the question "where should I write this rule?" Anything meant for the team goes into ./CLAUDE.md and ships via PR; a "personally, I prefer to work this way" preference goes into ~/.claude/CLAUDE.md and never mixes into the repo.

1# See where the hierarchy sits in the project root
2ls -la CLAUDE.md CLAUDE.local.md ~/.claude/CLAUDE.md 2>/dev/null

Priority order: global rule, project rule, subfolder rule

The rule is simple: files higher up take priority and load first, forming a general base, while lower layers make that base more specific (code.claude.com/docs/en/memory, 2025-11-13). The order: Enterprise policy first (organizational standard), then Project memory (team decision, CLAUDE.md), then User memory (personal preference, ~/.claude/CLAUDE.md). On conflict, it's not the more specific/lower layer that wins — it's the file's position in the hierarchy. So "does a project rule override a global rule" depends on position in the hierarchy, not on the file itself.

One way to share information between files is the import mechanism: CLAUDE.md files can pull in other files with @path/to/file.md syntax — added on May 9, 2025 in version 0.2.107 ("CLAUDE.md files can now import other files. Add @path/to/file.md to ./CLAUDE.md to load additional files on launch," code.claude.com/docs/en/changelog). In practice, this is the standard way to keep the root CLAUDE.md short and split details into subfolders:

1# CLAUDE.md (project root)
2 
3This project is a Next.js monorepo. Package manager: pnpm.
4 
5@docs/testing-conventions.md
6@docs/api-error-handling.md

This way the root file stays short, but the detailed rules in subfolders still enter context whenever they're needed.

What to write: commands, architecture boundaries, prohibitions, proof expectations

Anthropic's April 2025 guide gave a clear list of recommended content types for CLAUDE.md: frequently used bash commands, core files and helper functions, code style rules, testing instructions, repo etiquette (branch naming, merge vs. rebase), developer environment setup (e.g. a specific compiler version), and unexpected behaviors or warnings specific to the project ("Claude Code: Best practices for agentic coding," web.archive.org 2025-11-08 snapshot). This list covers everything you want an agent to already know rather than having to ask about.

1# A typical command block you might put in CLAUDE.md
2pnpm dev          # local dev server
3pnpm test         # vitest unit tests
4pnpm test:e2e     # playwright, requires `pnpm dev` first
5pnpm lint --fix   # eslint + prettier auto-fix

• Bash commands: exact commands the agent can copy and run instead of guessing.
• Code style: indentation, import order, naming — not "format it properly," but concrete rules.
• Testing instructions: which command, from which directory, with which prerequisite.
• Repo etiquette: branch naming, commit message format, rebase vs. merge.
• Unexpected behaviors: traps like "this module actually does X but is named Y."

A common pattern stands out here: this is all information the agent could find out by asking, but it's cheaper to already know without asking. An agent can find the test command by scanning the repo instead of reading it from a file, but that costs time and tokens; every line in CLAUDE.md lets it skip that discovery step. Proof expectations follow the same logic — a rule like "don't say you're done until both pnpm test and pnpm build pass" is a concrete gate that stops the agent from declaring "done" on its own.

What NOT to write: documentation copies, changelogs, bloated lists

CLAUDE.md has no required format; Anthropic recommended keeping it concise and human-readable ("There's no required format for CLAUDE.md files. We recommend keeping them concise and human-readable," same source, 2025-11-08 snapshot). Three principles were given for memory files: be specific ("indent with 2 spaces" beats "format the code properly"), organize with structure, and review periodically (code.claude.com/docs/en/memory, 2025-11-13). The practical conclusion: CLAUDE.md isn't a README copy, a CHANGELOG, or a to-do list — it should be information the agent actually re-reads and uses every session.

Measuring context cost: why you should keep it short

CLAUDE.md, along with every layer in the hierarchy, loads into context automatically at conversation start — so the file's size directly eats into every session's token budget. When all four layers (enterprise, project, user, and the still-supported local layer at that time) load simultaneously, a long, loosely written file inflates tokens consumed before the agent starts actual work. That's why the three principles above (specific, structured, regularly reviewed) matter not just for readability but for cost: unnecessary sentences, repeated explanations, or information derivable from the codebase (a file tree, a dependency list) shouldn't take up space in CLAUDE.md. A practical measurement method is to periodically re-read the file and ask, "did this line ever actually change a real decision the agent made?" — if not, it's a candidate for deletion.

Template: a 30-line minimum core

Since there's no format requirement, the starting point can be kept small. The skeleton below shows the minimum core you could add to CLAUDE.md from day one — as it grows, split subsections off via @path imports (see above):

1# Project Name
2 
3**Commands**
4 
5- Dev: pnpm dev
6- Test: pnpm test
7- Lint: pnpm lint --fix
8 
9**Architecture**
10 
11- src/api/ — REST endpoints, each in its own file
12- src/lib/db.ts — the single DB connection point, don't import it from anywhere else
13 
14**Code style**
15 
16- TypeScript strict, no any
17- Import order: external -> internal -> relative
18 
19**Prohibitions**
20 
21- No direct pushes to the main branch
22- Never commit the .env file
23 
24**Testing instructions**
25 
26- pnpm test requires pnpm db:seed first

This core is under 30 lines, yet answers five basic questions up front (how do I run it, what shouldn't I touch, how do I write code, what's forbidden, how do I verify). As the project grows, each section can move into its own @docs/...md file, keeping the root file small.

Quick editing: the `#` shortcut and the `/memory` command

As of 2025-11-19, Claude Code had two ways to quickly add a note to a memory file: starting your message with # (shorthand for "remember this"), or opening the relevant file directly with /memory. Layer selection existed in both paths; the shortcut also asked which memory file to save into. The real difference was scope: /memory opened the file in its own editor, letting you make long additions and reorganize it instead of adding a single line. Recommended flow: use the shortcut for a small, in-the-moment rule; use /memory when restructuring or adding a long section.

1claude
2# then, at the Claude prompt, type: /memory

FAQ

What's the difference between CLAUDE.md and AGENTS.md?

Both serve the same purpose: giving a coding agent project context. The difference is who reads them. CLAUDE.md is a file specific to Claude Code and gets pulled into context automatically when a conversation starts. AGENTS.md is a tool-agnostic standard, read by many different agents like Codex, Cursor, Aider, Gemini CLI, Zed, and Warp. As of 2025-11-19, Claude Code did not read AGENTS.md on its own; but you didn't need to duplicate its content — you could load the same file by adding a single line, @AGENTS.md, to the root CLAUDE.md (import 0.2.107, May 9, 2025).

What should a good project context file contain, and how long should it be?

It should include bash commands, core files and helper functions, code style rules, testing instructions, repo etiquette, developer environment setup, and unexpected behaviors specific to the project. There was no required format or numeric limit for length; Anthropic's recommendation was to keep the file short and human-readable, be specific, use structure, and review it periodically.

In what order do rules take effect (global, project, subfolder)?

Claude Code uses a four-layer hierarchy: Enterprise policy at the top (centrally managed by the organization), below it Project memory (team-shared CLAUDE.md), below that User memory (~/.claude/CLAUDE.md, personal preferences that apply across all projects). Files higher in the hierarchy take priority and load first; more specific layers get added on top of that base. Subfolder rules get attached to the root file via the @path import mechanism and load as part of the same hierarchy.

Does the context file burn tokens every session?

Yes — CLAUDE.md, along with every layer of the hierarchy, is automatically loaded into context when a conversation starts, so the file's length directly adds to every session's starting token cost. That's why keeping the file short, specific, and regularly reviewed isn't just about readability — it's directly a cost matter.

Update (September 2026)

The body of this article was written using the mechanisms as they stood on 2025-11-19. Since then, real changes have happened in how Claude Code handles context files:

• AGENTS.md is now read directly. With v2.1.277, released on September 18, 2026, Claude Code started reading AGENTS.md directly when there's no CLAUDE.md in the project root — you no longer need the @AGENTS.md import or a symlink workaround (code.claude.com/docs/en/changelog). This behavior can be changed via the "Project instructions" setting in the /config menu (default claude-md-or-agents-md, with options claude-md-and-agents-md, claude-md, managed-only), or via the pluginConfigs["agents-md@builtin"].options.instructionFiles key in settings.json. Support isn't available yet on Bedrock, Vertex, or Foundry.
• /memory and /context now list AGENTS.md too. Before v2.1.280, released on September 22, 2026, a directly-read AGENTS.md wasn't listed in these commands' output (code.claude.com/docs/en/memory).
• Three separate fixes landed for path-based rules in .claude/rules/: v2.1.198 fixed paths matching for files accessed via symlink, v2.1.207 made an invalid glob pattern break only that pattern instead of the whole rule, and v2.1.217 capped lists with many brace-expansions — which used to freeze the CLI — with one shared budget of 1,000 expanded patterns and 4 MiB (code.claude.com/docs/en/memory).
• The # shortcut was removed. On December 15, 2025, v2.0.70 removed the quick memory-entry shortcut itself: "Removed # shortcut for quick memory entry (tell Claude to edit your CLAUDE.md instead)" (code.claude.com/docs/en/changelog).
• The best-practices page was rewritten from scratch. The anthropic.com/engineering/claude-code-best-practices address quoted in the body now redirects to code.claude.com/docs/en/best-practices, and the page was rewritten under the title "Best practices for Claude Code"; the quotes in this article are taken from the 2025-11-08 archive snapshot.

Conclusion

The short answer to "how do you write CLAUDE.md and AGENTS.md": write little, write specifically, understand the hierarchy. What makes an agent look "dumb" is most often a missing or bloated context file — if the commands aren't concrete, if the prohibitions get lost in the middle of a sentence, or if the file is padded with information that can already be derived from the codebase, the agent repeats the same mistakes every session. Using Claude Code's four-layer hierarchy and the @path import mechanism correctly means keeping a single root file small and loading the details in only when they're actually needed.

If you want to read this topic alongside other layers of context management, the article Claude Projects and Memory: Context Management covers the consumer-side (Claude.ai) context mechanisms — this article covers the agent contract files at the repo root, and the two complement each other. For directing the agent during planning, see Claude Code Plan Mode: Planning Software Architecture with AI; for orchestrating multiple agents, see Claude Code Multi-Agent Teams: Parallel AI Agents; for deciding which agent tool (Skill, Subagent, Hook, MCP) to use when, see Skill, Subagent, Hook, MCP in Claude Code: Which One?; and for keeping delegation costs under control, see Claude Code Subagent Model Assignment and Orchestration.

Sources

• Claude Code memory documentation — hierarchy, import syntax, and memory management
• Claude Code changelog — version-by-version change records (import, AGENTS.md support, the # shortcut)
• Claude Code: Best practices for agentic coding (2025-11-08 archive snapshot) — the original recommendations for CLAUDE.md content; the live address today redirects to code.claude.com/docs/en/best-practices and has been rewritten
• AGENTS.md — the tool-agnostic project context file standard
• AGENTS.md support — Claude Code memory documentation — direct-read behavior and limitations
• @anthropic-ai/claude-code npm package — package registry data for version/date verification