vibestacklab, AI coding tools, sourced in publicvibestacklabAI coding tools, sourced in public
Follow @devdudejeremy on X
Menu

Guide

advanced

Rules files and AGENTS.md

Updated 2026-10-15. Sourced from vendor docs · verified 15 Oct 2026 · hands-on test pending wherever a sentence depends on a vendor page.

Put the commands and the constraints in a file the agent reads every time, instead of retyping them into chat.

Answer

AGENTS.md is a plain Markdown file at the root of a repo, meant as a README for coding agents. The agents.md site lists Cursor, Gemini CLI, and Windsurf among tools that use it. Devin Desktop's FAQ says it still reads Windsurf rules and also reads AGENTS.md. There is no required schema.

Beginner path

A short file is enough

If an agent keeps installing the wrong package or editing the wrong folder, write five lines in AGENTS.md at the project root:

# Project notes

- This is a one-page site. Do not add login.
- Do not commit .env.
- Run the app with npm run dev.
- Ask before adding a dependency.

You do not need a framework to start. The advanced section is for when several tools touch the same repo.

Advanced path

What the format is

The AGENTS.md site calls the file a README for agents: setup commands, code style, and tests that would clutter a human README. It says the format came out of work that included OpenAI Codex, Amp, Jules, Cursor, and Factory, and that it is now stewarded by the Agentic AI Foundation under the Linux Foundation. The same page says it is used by over 60,000 open-source projects. That count is the site's figure, not one this lab counted.

Tools named on that page include Cursor, Gemini CLI, and Windsurf. Devin's own FAQ, written for the June 2026 rename, says Devin Desktop reads AGENTS.md and agents.md, keeps .windsurfrules, prefers .devin/rules/, and can import .cursor/rules.

A file that changes behavior

Include commands, not adjectives.

# Checks

- Install with npm ci.
- Before you finish, run npm run lint and npm run typecheck.
- Do not add a new dependency without asking.
- Secrets stay in environment variables.

Nested files matter in a monorepo. The agents.md site says the nearest file to the edit wins. A chat instruction still overrides the file, which is how you make an exception without deleting the rule.

  • Build and test commands are copy-pastable.
  • The do-not list includes secrets and drive-by refactors.
  • I opened one agent and watched it follow a command from the file.
  • Old Windsurf or Cursor rules were left in place until the new file worked.

Next step

Questions

Is AGENTS.md a special format?

The agents.md site says it is standard Markdown with no required fields. Headings you would give a new teammate are enough.

What if two rule files disagree?

The agents.md FAQ says the closest AGENTS.md to the file being edited wins, and an explicit chat prompt overrides the file. Devin's FAQ says .devin/rules takes precedence over .windsurf/rules.

Sources