Skip to content

AGENTS.md

Summary

A plain Markdown file that gives an AI coding agent persistent instructions for a repository. An open format stewarded by the Agentic AI Foundation (AAIF) under the Linux Foundation, adopted by 60 000+ open-source projects. One file covers a broad ecosystem of tools with no per-tool syntax.

Tool

  • Primary: OpenAI Codex CLI (codex)
  • Also read natively by (confirmed):
  • Cursor — project root and subdirectories; plain-markdown alternative to .cursor/rules/
  • Windsurf/Cascade — root-level = always-on; subdirectory files = auto-glob scoped to that directory
  • GitHub Copilot coding agent — any location in the repo; nearest file to the working directory takes precedence
  • Devin (Cognition) — native support
  • Aider — via .aider.conf.yml: read: AGENTS.md (opt-in)
  • Gemini CLI — via .gemini/settings.json: { "contextFileName": "AGENTS.md" } (opt-in)
  • Zed editor AI — native support
  • VS Code (GitHub Copilot in-editor agent)
  • Amp, Kilo Code, Semgrep, UiPath coding agents — listed on agents.md ecosystem page
  • Standard body: AGENTS.md is stewarded by the Agentic AI Foundation, a Linux Foundation series project. Not a proprietary format; designed to be tool-neutral and community-maintained.

Support level

supported — v0.1 Core target.

Canonical path(s)

  • AGENTS.md at repository root — primary project-scoped instruction file
  • <subdirectory>/AGENTS.md — nested scope, loaded when Codex is working in or below that directory

Alternate / legacy path(s)

  • AGENTS.override.md — per-directory override; takes precedence over AGENTS.md in the same directory, allowing temporary overrides without deleting the base file
  • ~/.codex/AGENTS.md — global scope, inherited by every repository (Codex CLI only)
  • ~/.codex/AGENTS.override.md — global override
  • Custom fallback filenames configurable in ~/.codex/config.toml via project_doc_fallback_filenames (e.g. TEAM_GUIDE.md, .agents.md)

File format

Plain Markdown. No frontmatter, no special syntax. Free-form prose and bullet lists. No structural requirements — headings are conventional only, not parsed specially by any tool.

Frontmatter

None. The format is plain Markdown with no YAML frontmatter. Windsurf does not require frontmatter for AGENTS.md; activation mode is determined by file location (root = always-on, subdirectory = glob-scoped).

Discovery / scope behavior

OpenAI Codex CLI (per vendor docs):

  1. Global scope: Reads ~/.codex/AGENTS.override.md if present, else ~/.codex/AGENTS.md. Uses only the first non-empty file.
  2. Project scope: Starting at the git root, walks down to the current working directory. In each directory: checks AGENTS.override.md, then AGENTS.md, then project_doc_fallback_filenames. At most one file per directory.
  3. Merge order: Concatenates from root to CWD, joined with blank lines. Files closer to the CWD appear later and therefore take precedence when instructions conflict.
  4. Size limit: Combined instruction chain is capped at project_doc_max_bytes (default 32 KiB). Configurable in ~/.codex/config.toml. Split across nested directories or raise the limit when hitting the cap.
  5. Instruction chain is built once per run (once per TUI session launch).

Cursor: Reads AGENTS.md at project root and in subdirectories. Treated as a plain-markdown alternative to .cursor/rules/ with no frontmatter or metadata required.

Windsurf/Cascade: Root-level AGENTS.md is processed as always-on (equivalent to a trigger: always_on rule). Subdirectory AGENTS.md files are auto-glob scoped to that directory.

GitHub Copilot coding agent: Reads AGENTS.md files stored anywhere in the repository. The nearest file in the directory tree takes precedence over files higher up.

Repo-safe

Yes. AGENTS.md at the project root is designed to be committed to version control and shared with the team.

User-global files (~/.codex/AGENTS.md) are machine-local and should not be committed.

Renderer notes

  • Output path: AGENTS.md at repository root.
  • Single file output — no per-directory variants are generated by agent-policy (v0.1).
  • No header or frontmatter needed. Content is plain Markdown.
  • Suggested section structure (conventional, not enforced by any tool):
  • Build and test commands
  • Coding standards and conventions
  • Architecture notes
  • Common workflows
  • What the agent should and should not do

Known limitations / gotchas

  • Override files take silent precedence: If an AGENTS.override.md exists anywhere in the directory tree, Codex will silently skip the corresponding AGENTS.md. The generator produces only AGENTS.md; authors must be aware that a pre-existing override in their repo will suppress it.
  • Global file is not repo-committed: The ~/.codex/AGENTS.md global file is machine-local. Team members need to set it up individually.
  • 32 KiB combined cap: The entire merged instruction chain is capped. Large nested files can crowd out parent instructions. Keep files concise.
  • Instructions are context, not enforcement: All tools treat AGENTS.md as context injected into the LLM prompt. The agent may not follow every instruction, especially vague or conflicting ones.
  • Cursor treats it as a simple alternative to rules: Cursor does not apply Cursor-specific activation logic (no globs, description, alwaysApply) to AGENTS.md.

Official references

Minimal example

# AGENTS.md

## Repository expectations

- Run `cargo test --all-targets` before opening a pull request.
- Do not modify `Cargo.lock` manually.
- Document public API items with rustdoc comments.

## Architecture

- All error types live in `src/error.rs`.
- Keep business logic in the library crate (`src/lib.rs`), not in `src/main.rs`.

Internal mapping notes

  • Target ID: agents-md
  • Output path constant: "AGENTS.md"
  • Template: templates/AGENTS.md.j2
  • OutputTargets.agents_md: bool