AGENTS.md
By Mike Schreiber · Updated 31 October 2026
AGENTS.md
AGENTS.md is a Markdown instruction file that gives coding agents persistent project guidance, such as test commands, coding conventions, and review expectations. It captures what an agent should know before working, rather than preserving everything said in a conversation. Codex reads these files before starting work and combines global and project-specific guidance into an instruction chain. [1]
How it works
In Codex, discovery starts with global instructions in the Codex home directory, then proceeds from the project root to the current working directory. Each directory contributes at most one file, with AGENTS.override.md taking priority over AGENTS.md. More specific instructions appear later and override earlier guidance. The default combined limit is 32 KiB. These are Codex rules, not guarantees that every agent interprets the file identically. [1]
Claude Code support is version-dependent. Direct AGENTS.md loading requires v2.1.277 or later. By default, qualifying CLAUDE.md or CLAUDE.local.md files in the working directory or its ancestors take precedence. Supported sessions can load both through the Project instructions setting. Where direct support is unavailable, a CLAUDE.md containing @AGENTS.md provides an import route. [2]
Practical example
A small repository might commit this AGENTS.md:
# Project instructions
- Use pnpm for dependency installation.
- Run pnpm test before proposing a completed change.
- Ask before adding production dependencies.
- Preserve public API compatibility unless explicitly approved.
Replace these example commands with commands that actually exist. Keep instructions concise, review changes alongside code, and ask the agent to identify its loaded instruction sources. Instructions guide behavior; they should not replace permissions, automated checks, or other enforcement mechanisms. Claude Code explicitly treats instruction files as context rather than enforced configuration. [1][2]
Instructions, memory, and project records
An AGENTS.md file is not an MCP memory server. For a memory server exposed through MCP, local means the server runs on the same machine, commonly through standard input/output; hosted means it runs remotely and is accessed over a network, commonly through Streamable HTTP. Check the implementation’s storage, access, and retention policies separately. MCP defines context exchange, not a universal memory-storage or transcript-transfer system. [3]
Hark belongs in the project-record category: its briefs, Memory, and handoffs draw from a shared record covering Inventory, Health, Work, Authority, and Decisions. When a linked repository instruction file is selected as authoritative, Hark mirrors it rather than authoring competing edits. This supports project continuity, not universal transcript transfer between agents. [4]
Sources
[1] OpenAI: Custom instructions with AGENTS.md
[2] Claude Code: Project memory