AGENTS.md and CLAUDE.md: writing instructions that agents follow

What it does

• AGENTS.md. A dedicated Markdown file for agent context and instructions (build/test commands, conventions, security notes) kept separate from the human README. No required fields or headings; the agent parses the text you provide. How: Create an AGENTS.md file at the root of the repository. source
• nested AGENTS.md files for subprojects. Per-package instruction files in a monorepo. Agents read the nearest file in the directory tree; the closest one takes precedence. Explicit user chat prompts override everything. How: Place another AGENTS.md inside each package. source
• AGENTS.override.md. Codex instruction file that, when present in a directory, is used instead of AGENTS.md at that level. Codex uses only the first non-empty file per directory and concatenates the chain from global home then project root down to cwd. How: Global: ~/.codex/AGENTS.override.md or ~/.codex/AGENTS.md (CODEXHOME overrides the home). Project: AGENTS.override.md then AGENTS.md then names in projectdocfallbackfilenames. Example: codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded." source
• projectdocmaxbytes. Codex combined size cap for project instruction files. Empty files are skipped; Codex stops adding files once the combined size reaches this limit (32 KiB by default). How: Set in ~/.codex/config.toml, e.g. projectdocmaxbytes = 65536 and projectdocfallbackfilenames = "TEAMGUIDE.md", ".agents.md". Restart Codex so the config loads. source
• CLAUDE.md files. Markdown instructions Claude Code loads at the start of every session. Treated as context, not enforced configuration. Load order from broadest to most specific: managed policy, user (~/.claude/CLAUDE.md), project (./CLAUDE.md or ./.claude/CLAUDE.md), local (./CLAUDE.local.md). Ancestor files load at launch; subdirectory files load on demand. How: Run /init to generate a starting CLAUDE.md, or /memory to open locations. Confirm with /context all under Memory files. source
• Import additional files. CLAUDE.md can pull in other files with @path/to/import. Imports expand into the same context (they do not reduce context cost). Relative paths resolve from the importing file. Recursive imports max out at four hops. Quoted paths are not imported; wrap a mention in backticks to keep it literal. How: Write @README or @docs/git-instructions.md in CLAUDE.md. Escape spaces as @Design\ Docs/api-conventions.md. source
• AGENTS.md. Claude Code can read AGENTS.md as project instructions so a repo set up for other agents needs no CLAUDE.md. Default: AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md on the working-directory path. User ~/.claude/CLAUDE.md, managed CLAUDE.md, and .claude/rules/ do not block it. Requires v2.1.277 or later. How: In a session, /config → Project instructions, or pluginConfigs.cc-plugin-agents-md@builtin.options.instructionFiles in ~/.claude/settings.json. Values: claude-md-or-agents-md (default), claude-md-and-agents-md, claude-md, managed-only. Workaround: a CLAUDE.md containing @AGENTS.md. source
• Organize rules with .claude/rules/. Topic files under .claude/rules/ (recursive .md). Rules without paths frontmatter load at launch like .claude/CLAUDE.md. Path-scoped rules load when Claude Reads, Writes, or Edits a matching file. paths is the only frontmatter field Claude Code reads. How: Put testing.md, api-design.md, etc. in .claude/rules/. Path-scoped example frontmatter: paths: "src/api//.ts". User-level copy: ~/.claude/rules/. source
• Project Rules. Version-controlled Cursor rules in .cursor/rules as .mdc files, scoped with alwaysApply, globs, or description. A plain .md file in .cursor/rules is ignored because it has no frontmatter. How: Type /create-rule in Agent, or open Customize → Rules → Add Rule. Frontmatter fields: alwaysApply, description, globs. source
• AGENTS.md. Cursor’s plain-markdown agent instructions without metadata. Documented as a simple alternative to .cursor/rules. Supported in the project root and subdirectories; nested files combine with parents, more specific instructions taking precedence. How: Place AGENTS.md in the project root and optionally in subdirectories (frontend/, backend/, components/). source
• Team Rules. Team-wide rules from the Cursor dashboard, available on Team and Enterprise plans. Can be drafted, enabled, or enforced so members cannot disable them in Customize. Support glob patterns. Precedence: Team Rules → Project Rules → User Rules. How: Team administrators create them in the Cursor dashboard. Optional glob e.g. /.py. Enforce this rule to make them required. source
• context.fileName. Gemini CLI setting that names which Markdown context files to load. Default documented filename is GEMINI.md. Hierarchical load: ~/.gemini/GEMINI.md, workspace/parent files, then JIT files when a tool accesses a directory. How: In settings.json: {"context": {"fileName": "AGENTS.md", "CONTEXT.md", "GEMINI.md"}}. Inspect with /memory show; reload with /memory reload. Imports use @./components/instructions.md. source
• Include AGENTS.md file. Jules automatically looks for AGENTS.md in the repository root and uses it for how to understand the code and generate plans. How: Add AGENTS.md at the repo root; keep it up to date. source
• Agent instructions. GitHub Copilot type of repository custom instructions specified in files named AGENTS.md, CLAUDE.md, or GEMINI.md. Similar to repo-wide instructions but not supported by all Copilot features. Distinct from custom agent definition files in .github/agents. How: Create AGENTS.md (and optionally CLAUDE.md or GEMINI.md) in the repository. Nested AGENTS.md: the nearest file in the directory tree takes precedence for Copilot coding agent. source

Modes

• claude-md-or-agents-md. Claude Code default Project instructions value: load CLAUDE.md files, or AGENTS.md files when there is no CLAUDE.md or CLAUDE.local.md on the working-directory path. source
• claude-md-and-agents-md. Load CLAUDE.md and AGENTS.md together (CLAUDE.md first in each directory). Skips an AGENTS.md already loaded via import or symlink. Needed if you keep CLAUDE.local.md and still want AGENTS.md. source
• Always Apply. Cursor project-rule type: included in every chat session. Frontmatter alwaysApply: true; globs and description are ignored. source
• Apply to Specific Files. Cursor project-rule type: attached when a file in context matches globs (alwaysApply: false). source
• Apply Intelligently. Cursor project-rule type: Agent decides from the description when the rule is relevant. source
• Just-in-time (JIT) context files. Gemini CLI loads GEMINI.md (or configured names) in a directory and its ancestors up to a trusted root when a tool accesses that path, so component-specific instructions arrive only when needed. source

Recent changes

• 2026-10-29: Jules Turndown: Jules winds down on December 31, 2026; sessions finishable until November 11, 2026, then read-only. Jules is one of the AGENTS.md readers listed on agents.md and in Jules getting started. source
• 2026-09-18: Claude Code v2.1.277 adds AGENTS.md support: with no CLAUDE.md, Claude Code reads AGENTS.md; change under Project instructions in /config (not yet on Bedrock, Vertex or Foundry at that release). source
• 2025-08-28: Copilot coding agent gains AGENTS.md custom instructions, including nested files, while still supporting .github/copilot-instructions.md, .github/instructions/.instructions.md, CLAUDE.md, and GEMINI.md. source
• 2025-06-20: Jules starts reading AGENTS.md if it is in the repo (Smarter context). source

Alternatives

• Project Rules. Cursor .cursor/rules/.mdc files add frontmatter (alwaysApply, globs, description) and four apply types. AGENTS.md is plain markdown without that metadata; Cursor documents it as the simple alternative. Plain .md in .cursor/rules is ignored. source
• GEMINI.md. Gemini CLI’s default context filename. AGENTS.md is not the documented default; add it via context.fileName in settings.json (official example lists AGENTS.md, CONTEXT.md, and GEMINI.md together). source
• CLAUDE.md. Claude Code’s native instruction file with managed/user/project/local hierarchy, @ imports, and .claude/rules/. By default a project CLAUDE.md or CLAUDE.local.md means Claude does not read AGENTS.md unless Project instructions is claude-md-and-agents-md or you @-import it. source
• .claude/rules/. Path-scoped Claude Code rules that load only for matching files, unlike a root CLAUDE.md which is always in launch context. Anthropic recommends moving part-of-codebase instructions here and keeping each CLAUDE.md under 200 lines. source
• CLAUDE.local.md. Personal project-only Claude instructions; add to .gitignore. It loads after CLAUDE.md in the same directory. Because it counts as a project CLAUDE.md, adding one in an AGENTS.md-only repo stops default AGENTS.md loading. source
• .github/instructions//.instructions.md. GitHub Copilot path-specific custom instructions. Used with copilot-instructions.md; Copilot coding agent and code review support them alongside AGENTS.md. source

Traps

• Codex concatenates AGENTS.md files until projectdocmaxbytes (32 KiB by default) and then stops. Users report the rest is dropped with no TUI warning; later nested files are the ones clipped because the budget is consumed root-first. Raise projectdocmaxbytes or split files. Issue still open as of 2026-11-05. source
• Claude Code by default ignores AGENTS.md if any CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in the working directory or above it. A gitignored CLAUDE.local.md added for personal notes will silently switch Claude off AGENTS.md unless Project instructions is claude-md-and-agents-md. source
• CLAUDE.md is delivered as a user message after the system prompt, not as enforced config. Vague or conflicting instructions across nested files and .claude/rules/ may be followed inconsistently or picked arbitrarily. Files over 200 lines reduce adherence; a file over 4 MiB is skipped entirely. @ imports organize files but still load in full with the importer. source
• On-demand subdirectory CLAUDE.md and path-scoped rules are truncated to the start of the file when over the per-file character limit (40,000 characters on a 200K context window; 200,000 on Opus 4.6/Sonnet 4.6 1M windows, 150,000 on later 1M models). Later instructions are missing until Claude chooses to Read the rest. source
• Cursor docs say nested AGENTS.md apply when working in that directory, but users reported only the root file auto-appended; staff called it a bug (Oct 2025) and suggested @AGENTS.md as a workaround. Reports continued into December 2025. CLI v2026.10.22 later states nested AGENTS.md apply when the agent edits or creates a file, even if it never read one there first. source
• Gemini CLI documents GEMINI.md as the default context filename. AGENTS.md is loaded only if you add it to context.fileName (or if a later CLI default not reflected in this Jun 18, 2026 doc page applies). source
• In a Codex directory that contains both files, AGENTS.override.md is used and AGENTS.md in that same directory is ignored. Wrong guidance often comes from an override higher in the tree or under ~/.codex. Codex also ignores empty files and does not search below the current working directory. source

AuthorAndrey Reshetnikov, AI product and AI engineering