# AGENTS.md

An open Markdown format at a repository's root carrying the build, test, style, and security context a coding agent needs.

# AGENTS.md

Source: https://agents.md/
Fetched: 2026-05-17

## What it is

"A simple, open format for guiding coding agents." Functions as a
"README for agents: a dedicated, predictable place to provide the context"
that AI coding tools need. Complements README.md, which stays human-focused,
by carrying the "extra, sometimes detailed context coding agents need:
build steps, tests, and conventions."

## File format

- Plain Markdown at the repository root.
- Filename: `AGENTS.md`.
- No required fields; "use any headings you like."
- Nested `AGENTS.md` files supported in monorepos. The closest file to the
  edited code takes precedence; explicit user chat prompts override everything.

## Suggested sections

- Project overview
- Build and test commands
- Code style guidelines
- Testing instructions
- Security considerations
- Commit message guidelines
- PR guidelines

## Canonical example

```markdown
# AGENTS.md

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible
```

## Adoption (Used by, as of 2026-05-17)

OpenAI (Codex), Google (Jules, Gemini CLI), Factory.ai, Aider, Block (goose),
opencode.ai, Zed, Warp, Microsoft (VS Code), Cognition (Devin, Windsurf),
UiPath, JetBrains (Junie), Cursor, RooCode, Kilo Code, Phoenix, Semgrep,
GitHub Copilot, Ona, Augment Code.

Used by 60k+ open-source projects on GitHub.

## Origin and governance

Originated from collaborative effort across OpenAI Codex, Amp, Jules, Cursor,
and Factory. Now stewarded by the **Agentic AI Foundation** under the
Linux Foundation. Copyright: "AGENTS.md a Series of LF Projects, LLC".

## Behavior

When testing commands are listed, agents "attempt to execute relevant
programmatic checks and fix failures before finishing the task."

## Migration

Existing docs can be renamed; symbolic-link backward compatibility is supported.
Example configurations exist for Aider (`.aider.conf.yml`) and Gemini CLI
(`.gemini/settings.json`).

---

## Backlinks

Pages that link here:

- [AGENTS.md](/wiki/agents-md.md) — An open Markdown format at a repository's root carrying the build, test, style, and security context a coding agent needs.
- [Agent-Readable Web Standards](/wiki/agent-readable-web-standards.md) — A family of plain-text conventions at well-known paths that let machine readers understand how a site or repository wants to be read — the protocol surface of the Independent Internet.
- [design.md](/wiki/design-md.md) — An early Markdown convention for declaring a project's design system to design-aware coding agents.
- [Glossary](/wiki/glossary.md) — Formal definitions of the key terms behind the Independent Internet and Web 4.0, as used across this wiki, with links to source material.
- [Interpretable Context Methodology: Folder Structure as Agent Architecture](/wiki/icm-paper.md) — Van Clief and McDermott's paper arguing that a well-organized folder hierarchy can replace a multi-agent framework: the folder structure is the orchestration.
- [The Governance of Agent-Readable Standards](/wiki/governance-of-agent-readable-standards.md) — The five agent-readable web standards differ sharply in who governs them — and that trajectory is the real story.
- [Interpretable Context Methodology (ICM)](/wiki/interpretable-context-methodology.md) — Using folder structure — plain files in a well-organized hierarchy — as the orchestration mechanism for a multi-step AI workflow, instead of a code-level framework.