AGENTS.md Guide: Open source "project description" format for coding agents (AI Agents). AGENTS.md is an open-source instruction format for "AI coding agents". It's like the "agent version" of the README: it provides the agent with key information such as builds, tests, code specifications, and considerations, helping the agent perform tasks more reliably in your codebase. According to the site, a large number of open source projects have adopted this format; Its design goal is to be common across multiple agents and tools, suitable for teams and open source repositories to quickly implement.
1. What is AGENTS.md
1) Positioning: A documentation document for AI coding agents, which is a functional supplement to the README.
2) Goal: Give agents a fixed, predictable entrance to centralize the context and instructions to "make agents work efficiently".
3) Form: Pure Markdown, no forced fields; Write on demand for long-term maintenance and version management.
2. Why do you need AGENTS.md (relationship with README)
1) README is aimed at human readers, emphasizing product descriptions, quick starts, and contribution guides.
2) AGENTS.md Agent-oriented, emphasizing build/test commands, code style, CI requirements, and security points.
3) Benefits of separation: keep the README concise while giving agents a dedicated document that "just look at this and you can do the job".
3. Core design and ecological compatibility
1) Open format: use any subsection title and content structure, proxy parse by text, no proprietary syntax.
2) Multi-agent compatibility: The official list of adaptation directions for multiple agents/tools (such as Codex, Amp, Jules, Cursor, Factory, RooCode, etc.).
3) Priority rule: In the event of a instruction conflict, the AGENTS.md closest to the target file takes effect; Explicit user dialog instructions take precedence over generic instructions.
4) Monorepo friendly: support placing "nearby" AGENTS.md in subpacks; Large warehouses can manage agent descriptions for different sub-projects in layers.
4. How to adopt (four steps)
1) Add files: Create a AGENTS.md in the root directory of the codebase; If necessary, put a copy in the sub-pack.
2) Coverage focus: project overview, build and test commands, code style, test specifications, security and compliance points.
3) Supplementary rules: submission information and PR specifications, data and model resource downloads, deployment steps and common pitfalls.
4) Iterative maintenance: Treat it as a "living document" and update it as the CI/dependency/directory structure is updated.
5. The minimum available template
# AGENTS.md ## Project overview - Monorepo + PNPM workspace。 The main language is TypeScript. ## Setup & build - Install: pnpm install - Dev: pnpm dev - Test: pnpm test - Lint: pnpm lint ## Code style - TS strict mode； single quotation marks, no semicolons; Functional expressions take precedence. ## Testing - CI at .github/workflows; All use cases need to be passed locally before committing. ## PR rules - Title: [<pkg>] <title>; You must run lint and test before committing. ## Security - Do not submit .env; Keys are injected using warehouse secrets or local injections.
6. Typical use cases
1) Open source repository: Let the agent who comes into contact with it "out of the box and test" and automatically perform build/single test/static check.
2) Team collaboration: Explicit "implicit conventions" (coding style, submission process) to reduce the friction between agents and people.
3) Large warehouse governance: Split AGENTS.md by sub-projects to achieve nearby instructions and differentiated processes.
4) Security and compliance: Write clearly the "non-uploadable data/model" and security red line to reduce the risk of automated operations.
7. Implementation suggestions and risk warnings
1) Start with the "minimum template": only build, test, style, and PR rules, and then gradually refine.
2) Align with CI: Synchronize key commands from CI to AGENTS.md to avoid "agent runs but CI can't".
3) Explicit conflict handling: Write at the top of the file that "if there is a conflict with the user instruction, the user instruction shall prevail".
4) Uncertain statement: When it comes to indicators such as "how many projects have been adopted", it is recommended to mark "according to the site's self-statement" to avoid data misreading.
Q&A FAQs
Q: Are there mandatory fields or standard templates for AGENTS.md?
A: No. It is a generic Markdown instruction that encourages the organization of chapters according to the actual needs of the project.
Q: How do you divide the work with the README?
A: README is for people; AGENTS.md Agent-oriented. The former talks about "what/how to get started" and the latter talks about "how the agent executes builds/tests/specs".
Q: How does Monorepo organize multiple AGENTS.md?
A: Put the general description in the root directory, and put the nearest description in the subpackage; Agents usually prioritize reading the closest copy of the target file.
Q: Do you support multiple proxy tools?
A: According to the project page, it is designed to be compatible with multiple agents and tools, and in principle, "one document, multiple agents are available".
