Once a team starts using AI to help write code, the same frustration appears fast: you keep re-explaining the same rules, which framework to use, how tests are run, what the code style should be. Switch to another tool or another colleague, and you explain it all over again. A standard that took shape through 2026 targets exactly this pain, and it is called AGENTS.md. This article covers what it is, what to put in it, why it became a de facto standard so quickly, and the lesson in it even for teams that are not purely technical.
What AGENTS.md is
AGENTS.md is a plain Markdown file at the root of a repository whose job is to tell the AI how the project is built, how it is tested, and what rules to follow when making changes. It is written by hand, and its contents are the minimum background an AI coding assistant needs to work effectively. Think of it as an instruction sheet written specifically for AI, kept in a fixed, predictable place, so any tool that can read it benefits the moment it opens the project.
How it differs from a README
The biggest difference is the reader. A README is written for humans: it explains what the project is and how to get started. AGENTS.md is written for AI agents, focused on build commands, test commands, code-style conventions, testing frameworks, architectural decisions, and anything else an agent must know before touching the code. Separating "for humans" from "for AI" keeps both clear: your README does not become long and messy to accommodate the AI, and the AI is not left hunting for the point inside a pile of human-facing prose.
What to put inside
AGENTS.md has no required schema and needs no tooling to install, but most projects include a few common sections: a project overview, build and test commands, code style, testing instructions, security notes, and commit or pull-request rules. For build and test, list the actual commands, for example install, develop, run only the changed tests, or lint only what changed, so the AI can follow them instead of guessing. The key is to be specific and executable, because the more concrete the instruction, the fewer mistakes the AI makes.
Large projects: multiple files and "nearest wins"
For a large structure that holds several sub-projects in one repository (a monorepo), AGENTS.md supports nesting: a general set of rules at the root, and a dedicated file inside each package such as api or web. The AI reads the nearest file in the directory tree, so the closest one takes precedence, and every package can carry its own instructions without conflict. This is genuinely practical: OpenAI's own main repository already contained 88 AGENTS.md files at the time the standard's site was written, one per package.
Why it became a de facto standard so quickly
AGENTS.md spread fast because you "write once and it applies everywhere." As of mid-2026 it had been adopted across more than 60,000 open-source repositories and is supported by 30-plus AI tools, including OpenAI Codex, Cursor, GitHub Copilot and Gemini CLI. In other words, you do not write a separate rule set for each tool; you write one AGENTS.md and they all follow it. On governance, the standard is now stewarded by the Agentic AI Foundation under the Linux Foundation, the same body that maintains MCP (the Model Context Protocol), which gives it a stable, neutral long-term footing rather than depending on any single company.
The lesson for your team
Even if you are not an engineering team, the thinking behind AGENTS.md is worth borrowing: instead of repeating instructions verbally every time, write your team's rules, conventions and standards into a document the AI can read and follow, kept in a fixed place. Then, whatever tool or colleague changes, the AI's output stays consistent and you spend less time correcting it back and forth. This is the practice of turning knowledge into a reusable asset, and it is the first step to making AI a real part of daily operations. To learn how to build this kind of AI working standard for your company and deploy AI assistants into real business workflows, visit ai.ud.hk to explore UD's AI Staff solutions.
懂AI，更懂你｜UD相伴，AI不冷
