# AGENTS.md

> VI: https://5ac.vn/wiki/agents-md/ · EN: https://5ac.vn/en/wiki/agents-md/ · lang: en · spec_as_of 2026-10-18 (spec unversioned) · cluster C4

A markdown file at the repository root where a project declares build and test commands, code conventions, and the boundaries a coding agent must respect.

---
## Definition

AGENTS.md is a markdown file at the repository root that a coding agent reads before doing any work: build and test commands, code conventions, and the boundaries of what may and may not be touched. No field is required and the format is plain Markdown; large repos drop copies into subdirectories so guidance sits close to the code.

## Mechanism

The standard site recommends covering a project overview, install and test commands, code style, testing instructions and security notes. There is no shared schema: the agent reads whatever text you write as the project's own convention.

Codex (OpenAI) shows how a mainstream agent layers those files:

| Scope | Location | Role |
| --- | --- | --- |
| Global | ~/.codex/AGENTS.md | defaults for every repository |
| Project root | repo/AGENTS.md | the project's own commands and rules |
| Subdirectory | services/payments/AGENTS.md | overrides for the code closest by |

Flow: Global → Repo root → Working directory

Codex concatenates files from the root down, so the file nearer the current directory wins; each directory contributes at most one file, and the combined size is capped at 32 KiB (project_doc_max_bytes), with overflow pushed into subdirectories. Codex builds this chain once per run, or once per launched session in the TUI, and skips empty files. A repo that already ships its own guide can add TEAM_GUIDE.md to project_doc_fallback_filenames and Codex will read it like AGENTS.md. The general rule on agents.md agrees: the file closest to the edit wins, and an explicit prompt in the chat window overrides every file.

## Spec anchor

The normative site is [agents.md](https://agents.md), which carries no version string, so the frontmatter records "unversioned" with the check date 2026-10-18. The same page confirms that AGENTS.md is now stewarded by the Agentic AI Foundation under the Linux Foundation, and that the format emerged from work by OpenAI Codex, Amp, Jules from Google, Cursor and Factory. The page also lists Jules from Google, Factory, Aider, goose, opencode, Zed, Warp, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Phoenix, Semgrep, Windsurf and Ona among the tools that read the same file, which is how an open format stays independent of any single vendor. [Codex's official AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md) documents how one tool reads the files.

## Academic anchors

No arXiv paper on AGENTS.md has been verified for this entry, so the block pins public figures instead:

| Source | Figure | Measured |
| --- | --- | --- |
| [agents.md](https://agents.md/) | more than 60,000 open-source projects use it (the site's own claim) | 2026-10-18 |
| [agents.md](https://agents.md/) | OpenAI's repo held 88 AGENTS.md files at the time the page was written | 2026-10-18 |
| [developers.openai.com](https://developers.openai.com/codex/guides/agents-md) | project_doc_max_bytes defaults to 32 KiB per merge | 2026-10-18 |

## FAQ

**How does AGENTS.md differ from a README?** A README is written for humans skimming a project; AGENTS.md is written for an agent about to act, so it keeps commands and boundaries instead of storytelling.

**Are any fields required?** None. The standard site states the file is plain Markdown, any headings work, and the agent parses whatever text you provide.

**What if several files disagree?** That is not an error: the file closest to the edited one wins, and an explicit user prompt in chat overrides them all.

**Will the agent run test commands by itself?** Yes, if you list them; the agent tries to run the relevant checks and fix failures before finishing a task.

**A repo has an old AGENT.md — what now?** The standard site suggests renaming and leaving a symbolic link so older tools still find it: `mv AGENT.md AGENTS.md` with `ln -s AGENTS.md AGENT.md`.

**Which sources built this entry?** Two pages, both fetched on 2026-10-18: [agents.md](https://agents.md/) for the format and its reading rules, [Codex's AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md) for the precedence chain and the 32 KiB cap.

## Related

- [Agent Skills (SKILL.md)](/en/wiki/agent-skills/)
- [What Is a Multi-Agent OS?](/en/blog/what-is-multi-agent-os/)
- [One-Person Company with 42 AI agents](/en/blog/one-person-company-ai-os/)