AGENTS.md

What it means

AGENTS.md is a plain Markdown file committed to a repository that tells AI coding agents how to work on the project. The agents.md site calls it “a README for agents”: a dedicated, predictable place for the context a human-facing README leaves out. It has no required fields.

The convention emerged from OpenAI Codex, Amp, Jules from Google, Cursor, and Factory, among others. It is now stewarded by the Agentic AI Foundation under the Linux Foundation, and the site reports use in over 60k open-source projects.

The site’s popular sections:

• Project overview and repository layout.
• Build and test commands, which the agent will run if listed.
• Code style guidelines and testing instructions.
• Security considerations, pull request conventions, and deployment steps.

Types and variants

Most tools read a file of their own and, increasingly, AGENTS.md as well:

File	Read by	Placement and precedence
AGENTS.md	Codex, GitHub Copilot, and the tools listed on agents.md	Nested files allowed; the nearest file in the directory tree takes precedence
CLAUDE.md	Claude Code	./CLAUDE.md or ./.claude/CLAUDE.md; subdirectory files load on demand
.github/copilot-instructions.md	GitHub Copilot	Repository-wide; path-specific NAME.instructions.md files sit under .github/instructions
.cursorrules, .cursor/rules, GEMINI.md	Tool-specific rule files	Listed by Enji Guard’s readiness runbook (OpenSSF names only “Cursor rules”); placement not verified here

On conflict, the agents.md FAQ says the closest AGENTS.md to the edited file wins and explicit user chat prompts override everything. Codex builds its instruction chain the same way: a global file in its home directory, then project files from the repository root down, with closer files overriding earlier guidance.

Claude Code reads CLAUDE.md, not AGENTS.md; an existing AGENTS.md can be imported with @AGENTS.md or a symlink.

Why it matters for AI-written code

An agent begins each task from the instructions it can find. OpenSSF’s guide recommends custom instruction files (Claude markdown, Copilot instructions, Cursor rules) so the assistant “accounts for application code security, supply chain safety, and platform or language-specific” requirements, and states that AI-generated code is not a shortcut around code reviews, testing, static analysis, documentation, and version control discipline.

The failure mode is drift. Claude Code’s documentation warns that when two rules contradict each other, Claude “may pick one arbitrarily,” and asks teams to review instruction files periodically for outdated or conflicting rules; the agents.md FAQ calls the file living documentation.

A retired test command, a module still described as canonical, or two tools carrying different rules make the next agent change less predictable and harder to review.

How Enji Guard helps

The AI readiness audit’s infrastructure inventory includes root or nested instruction files: AGENTS.md, CLAUDE.md, .cursorrules, .cursor/rules, .github/copilot-instructions.md, GEMINI.md, and equivalents. The catalog states the audit’s job as “Check whether the repository is easy for agents to understand and change,” and the runbook forbids reducing that question to whether AGENTS.md or CLAUDE.md exists. The file is evidence, not the goal:

• Absence is not a failure. A missing AGENTS.md or CLAUDE.md does not automatically lower the score when another system provides equivalent agent-readable context. The final-scoring rule: “Lower the score when agents lack a clear, current, portable path to work safely.”
• Weak signals are named. For cross-agent portability they include a CLAUDE.md alone holding critical rules, duplicated conflicting instructions across tools, and tool-specific slash commands with no generic fallback, among others.

GUARD.md is a different file: it tells Enji Guard’s own runs what to skip and what is intentional, and no audit lowers a score because it is missing. Enji Guard reruns the readiness audit as the repository changes; that recurring audit and autofix cycle keeps the project in the green zone, where coding agents inherit fewer unresolved risks.

The audit is read-only and repository-centered. Enji Guard does not generate or rewrite AGENTS.md. The agent documentation improvement is a prototype that does not yet inspect AGENTS.md or CLAUDE.md drift deeply, edit documentation, or open a pull request; agent-context changes go through your normal review.