AGENTS.md is a portable Markdown instruction artifact for AI coding agents. It keeps durable, project-specific guidance in a version-controlled file beside the code, so developers do not need to repeat repository rules in every prompt. The open format is stewarded by the Agentic AI Foundation under the Linux Foundation. section 2.4.1 section 11.3.2
A useful shared file can give agents:
- A repository overview, architecture constraints, and coding conventions. section 2.4.1
- Build, test, lint, review, and release instructions, including commands to run before reporting completion. section 11.3.2 section 2.5.4
- Safety boundaries, such as files not to edit, commands requiring approval, and restrictions on secrets or dependencies. section 11.3.2 section 2.4.1
Listing 2.4 Sample AGENTS.md instruction artifact for a backend Python service
# Project guidance for AI agents ## Purpose This repository implements the customer billing service for an e-commerce platform. ## Architecture rules - Keep business logic inside the `services/` layer. - Do not place domain logic inside API controllers. ## Coding conventions - Use Python 3.12 syntax. - Prefer explicit type hints on public functions. ## Validation steps Before submitting changes: 1. Run `pytest tests/unit`. 2. Run `pytest tests/integration` if the database code was modified. 3. Run `ruff check .` and `black --check .`. ## Safety constraints - Do not modify files under `migrations/archive/`. - Do not hardcode secrets, tokens, or credentials. ## Pull request expectations - Summarize the functional change. - List risks and backward-compatibility concerns.
This backend service example combines architecture rules, Python conventions, validation commands, safety constraints, and pull request expectations in one file. section 2.4.1
Place the shared AGENTS.md in the repository root. Codex, Cursor, and Aider can discover it directly; Claude Code can use a CLAUDE.md adapter that imports it with @AGENTS.md and adds tool-specific workflow guidance. Other conventions, such as GitHub Copilot’s repository-wide instructions and Cursor’s path-targeted rules, coexist with the shared baseline. section 2.5.4 section 11.3.2
Check the shared instructions across agents
In a Python task-tracker project, ask each agent to summarize the instructions loaded for its session, then add validation that rejects empty task titles and include a unit test. Check that it makes the required changes, follows the dependency rules, runs the validation commands, and reports any commands it could not run. section 2.5.4
File discovery and the amount of guidance injected into active context differ across agents. Artifact names and locations are evolving integration details, so verify each tool’s behavior rather than assuming every agent reads the same instructions. section 2.4.1 section 11.3.2

