AGENTS.md
Updated October 29, 2026 · first published October 10, 2026 · by the AQ team
AGENTS.md is a Markdown file that gives AI coding agents project instructions, such as build commands, test commands and coding conventions. Teams usually commit it at the repository root and add smaller files inside packages that need different guidance. The filename is shared across tools, but each tool decides where to look, when to load a file and which settings take precedence.
Which filename and location should I use?
Start with AGENTS.md at your repository root. Use the exact plural filename and capitalization. The AGENTS.md format requires no special schema or frontmatter. A useful first file names the package manager, gives the exact test command and explains conventions that the code does not make obvious.
| Filename or path | What it means |
|---|---|
AGENTS.md | Project instructions recognized by supporting tools, subject to their discovery rules. |
packages/web/AGENTS.md | Instructions for a narrower directory. Loading depends on the tool and working directory. |
~/.codex/AGENTS.md | Codex user guidance across projects, unless CODEX_HOME points elsewhere or a global override replaces it. |
AGENTS.override.md | Codex's preferred instruction filename within a directory; Claude Code does not discover it. |
AGENTS.local.md | No portable local-file convention. Claude Code explicitly does not read it; Codex needs a configured fallback filename. |
AGENT.md or .agents/agent.md | Different paths, not aliases for AGENTS.md. The discovery rules below do not recognize them by default. |
A filename containing “local” does not make its contents private. Keep personal files out of version control deliberately, and never store credentials in instruction text.
How Codex finds global and nested instructions
According to OpenAI's instruction discovery guide, Codex builds its chain once per run, usually once per launched TUI session. It first checks its home directory, ~/.codex by default or the directory set by CODEX_HOME. There it uses the first non-empty file: AGENTS.override.md before AGENTS.md.
For project instructions, Codex walks from the project root, typically the Git root, down to the current working directory. Without a project root it checks only the current directory. In each directory it checks AGENTS.override.md, then AGENTS.md, then names from project_doc_fallback_filenames, taking at most one file per directory. It skips empty files and combines guidance from broadest to most specific, with later instructions overriding earlier guidance. It stops adding files at project_doc_max_bytes, which defaults to 32 KiB.
A nested file below the launch directory is not automatically part of that startup chain. Launch a fresh run in the relevant package, or use --cd, when checking its instructions. Restart after changing files or fallback settings. For example, project_doc_fallback_filenames = ["AGENTS.local.md"] makes that name a fallback in each project directory; it does not merge it with an AGENTS.md already selected there. An override in one directory replaces that directory's file, not the entire ancestor chain.
When Claude Code reads AGENTS.md
Claude Code's memory documentation describes native support from v2.1.277. By default, a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any ancestor makes Claude use its CLAUDE.md instructions instead of AGENTS.md. The user file ~/.claude/CLAUDE.md, managed instructions and .claude/rules/ do not trigger that exclusion.
When AGENTS.md loading is enabled, Claude loads AGENTS.md and .claude/AGENTS.md in the working directory and ancestors at session start. A subdirectory's AGENTS.md loads when Claude opens a file there with the Read tool, provided the subdirectory has none of those three CLAUDE.md files of its own. Claude does not discover AGENTS.local.md, AGENTS.override.md or instructions under .agents/.
Adding CLAUDE.local.md can therefore stop default AGENTS.md loading. To keep both, open /config and set Project instructions to claude-md-and-agents-md. The default is claude-md-or-agents-md; claude-md selects CLAUDE.md alone. managed-only excludes project, local and user instruction files at launch, though some subdirectory instructions still load on demand.
For file-based configuration, the documented key is pluginConfigs["cc-plugin-agents-md@builtin"].options.instructionFiles. It is read from user settings (~/.claude/settings.json), a --settings file or managed settings, and ignored in project and local settings files. Before v2.1.285 the plugin ID was agents-md@builtin; v2.1.285 and later accept either ID.
Support is unavailable before v2.1.277, when the built-in plugin is disabled, and sometimes in the first session after upgrading from v2.1.276 or earlier. Before v2.1.281, some environments, including Bedrock or sessions with telemetry disabled, also lacked support. Check claude --version, start a new session and look for the setting in /config. Existing repositories that need imports or symlinks should follow the AGENTS.md and CLAUDE.md sync guide.
What Cursor shares with these tools
Cursor's rules documentation supports a root AGENTS.md and nested AGENTS.md files. Nested instructions apply when working with files in that directory or its children and combine with parent instructions, with more specific guidance taking precedence. Personal User Rules live in Customize → Rules and apply across projects. Cursor also supports scoped project rules in .cursor/rules/*.mdc.
That documentation does not establish an AGENTS.local.md convention. Use the documented User Rules for personal preferences. A shared root file can carry common commands across Codex, Claude Code and Cursor, but their settings, local filenames and discovery triggers still need separate checks.
How to check which instruction files loaded
For Codex, start at the repository root and ask it to summarize the current instructions and name their sources. Repeat in the package directory using --cd. OpenAI also documents opting into a plaintext TUI log with codex -c log_dir=./.codex-log, then checking ./.codex-log/codex-tui.log, or inspecting a recent session-*.jsonl when session logging is enabled. Inspect logs locally: they can contain private context.
For Claude Code, run /memory and look for the file path. Before v2.1.280, directly loaded AGENTS.md files did not appear in /memory or /context; update or ask what the project instructions say. A model's answer is a useful diagnostic, but does not prove every instruction will be followed.
The following is a reader procedure, not an experiment we performed. It uses a disposable repository with harmless markers, so you can check discovery without printing your real repository instructions. Run it in a shell with Git and Codex installed:
fixture=$(mktemp -d)
mkdir -p "$fixture/packages/demo"
git -C "$fixture" init -q
printf '%s\n' 'Discovery marker: ROOT_CHECK_742. Include this marker when asked for discovery markers.' > "$fixture/AGENTS.md"
printf '%s\n' 'Discovery marker: NESTED_CHECK_853. Include this marker when asked for discovery markers.' > "$fixture/packages/demo/AGENTS.md"
codex --version
codex --cd "$fixture" --sandbox read-only --ask-for-approval untrusted \
"Without reading files or running tools, list discovery markers from your startup instructions."
codex --cd "$fixture/packages/demo" --sandbox read-only --ask-for-approval untrusted \
"Without reading files or running tools, list discovery markers from your startup instructions."
Expected from the documented chain: the root run receives ROOT_CHECK_742; the nested run receives both markers. Existing global instructions and byte limits can affect results. Record the CLI version, working directory, relevant configuration and observed markers. If results differ, inspect local loading logs and check CODEX_HOME, empty files, overrides and the byte cap. In this fixture only, rename the nested file to AGENTS.override.md and repeat to check override discovery. Do not paste real instruction files or full logs into an issue.
What to put in the file
Write exact commands, a short directory map and conventions the agent cannot easily infer. Keep root guidance useful across tasks and put package-specific commands in nested files. Move occasional procedures into agent skills, and keep long references in linked documents. Skills, instruction files and agent-written memory have different loading rules; the memory guide explains what persists and where.
Security checks for repository instructions
Treat instruction text from an unfamiliar repository or pull request as untrusted context. The threat is a contributor placing malicious instructions in a file the coding agent loads, then steering it to read credentials, send data to an external destination, weaken tests or change unrelated code. This assumes the attacker can influence repository text and the agent has tools or credentials that could carry out the request. A trusted root file does not make every nested file trustworthy.
Loading a file successfully proves neither compliance nor safety. Models can miss instructions, follow conflicting text or be steered by a later tool result. AGENTS.md is not an access-control boundary. Permissions, sandbox and network controls constrain execution; CI and required review enforce checks before changes ship. A worktree separates edits and branches, but does not by itself prevent credential access or exfiltration.
Before giving an agent an unfamiliar checkout, review instruction-file changes and inspect its effective permission mode. Reproduce loading with the harmless fixture above in an environment without production credentials. To check enforcement, place a dummy marker file outside the permitted workspace and request an action your configured sandbox denies, such as writing to that file. Verify the denial in tool output and confirm the dummy file is unchanged. Test network restrictions only against an endpoint you control with dummy data. These checks cover the tested paths and configuration, not every possible route to data. Follow the secrets guide to reduce what the agent can read in the first place.
Where AQ fits
AQ is the multiplayer coding harness where teams run AI coding agents such as Claude Code and Codex in shared live workspaces. AQ runs stock CLIs with terminals, a code editor and app previews, using isolated git worktrees on dedicated or customer infrastructure. Teammates can inspect a session and review its changes together. The installed CLI, its version, working directory and settings determine which instruction files load; AQ's worktree separation does not enforce the prose in those files or prevent exfiltration. See what AQ provides.
Frequently asked questions
What is an AGENTS.md file?
AGENTS.md is a Markdown file containing project instructions for coding agents: build and test commands, directory guidance and coding conventions. Put shared guidance at the repository root and check each tool's discovery rules for nested files.
Where is the global AGENTS.md file?
Codex uses AGENTS.md in its home directory, normally ~/.codex or the directory set by CODEX_HOME. A non-empty AGENTS.override.md there takes precedence. Claude Code's personal file is ~/.claude/CLAUDE.md; Cursor uses User Rules in settings. There is no universal global path.
Does AGENTS.local.md work?
Support depends on the tool. Claude Code explicitly does not read AGENTS.local.md. Codex can recognize it through project_doc_fallback_filenames, but takes at most one file per directory, so it will not add it alongside an AGENTS.md already selected there. Cursor's cited rules documentation does not define this filename.
How can I check if Codex loaded my AGENTS.md file?
Start a fresh run in the relevant directory, ask for the active instruction sources, and check harmless unique markers in a disposable fixture. For a local audit, enable the documented TUI log with codex -c log_dir=./.codex-log and inspect codex-tui.log there. Check CODEX_HOME, overrides, fallback filenames and the 32 KiB default byte limit if a source is missing.
Does Claude Code read .claude/AGENTS.md?
Yes, when native AGENTS.md support is available and selected. Claude loads AGENTS.md and .claude/AGENTS.md in the working directory and ancestors at startup. A project CLAUDE.md or CLAUDE.local.md can suppress default AGENTS.md loading. Use /config to select claude-md-and-agents-md when both are needed, then check /memory on current versions.
Are AGENT.md and .agents/agent.md the same as AGENTS.md?
No. These are different filenames and paths. They are not default aliases in the discovery rules described here. Codex supports explicitly configured fallback filenames; Claude Code does not discover instructions under .agents/.