# What is AGENTS.md?

URL: https://agentvera.dev/en/glossary/agents-md/

AGENTS.md is an open, plain Markdown file in a repository that tells AI coding agents how to work on the project: how to build and test it, which conventions to follow and what to avoid. Think of it as a README for agents that many different tools read.

**Which agents read it.** The format is described at agents.md, which lists more than 20 tools that support it. Support differs in the details, so check your agent’s docs.

- Codex, Cursor, GitHub Copilot’s coding agent, opencode, Amp, Aider, goose, Zed, Warp, Junie and Jules, among others, read it.
- Gemini CLI reads GEMINI.md by default; add AGENTS.md to the context.fileName setting in settings.json and it reads that too.
- Claude Code reads CLAUDE.md, and since version 2.1.277 it reads AGENTS.md when the repository has no CLAUDE.md. You can also import it into CLAUDE.md with @AGENTS.md.

**AGENTS.md, CLAUDE.md and GEMINI.md.** CLAUDE.md and GEMINI.md are the tool-specific files of Claude Code and Gemini CLI; AGENTS.md is the shared one. All three hold the same kind of content. A common setup keeps the shared rules in AGENTS.md and has the tool files point to it, adding only what is specific to one tool, so the instructions don’t drift apart. By default Claude Code reads only CLAUDE.md when both exist, so import AGENTS.md from it or change its Project instructions setting.

**What to put in it.** Write down what a new teammate would need on day one and what you would otherwise repeat in every prompt. Keep it short: agents load it into their context at the start of a session.

- Setup, build and test commands, exactly as they are run.
- Code style and conventions the linter doesn’t enforce.
- Project layout: where things live and which folders are generated.
- Rules for commits and pull requests.
- What never to do, such as editing generated files or committing secrets.

**A short example.** A minimal AGENTS.md for a TypeScript project could look like this. In a monorepo each package can have its own AGENTS.md, and agents use the one nearest to the file they are editing.

- ## Commands: pnpm install; run pnpm test before every commit and pnpm lint after moving files.
- ## Style: TypeScript strict mode, single quotes, no semicolons.
- ## Layout: app code in src/; the API client in src/gen/ is generated, never edit it by hand.
- ## Pull requests: title as “[package] Short summary”; lint and tests must pass.

**Where AgentVera fits.** AgentVera starts each agent’s own CLI in the project folder, so AGENTS.md and the tool files apply as usual; an agent’s role and instructions field adds standing instructions on top, and CLIs without a flag for extra instructions (Cursor, Gemini CLI and Amp, for example) rely on the project’s AGENTS.md or rule files instead.

- **Is AGENTS.md a formal standard?** It’s an open format with no required fields or schema: plain Markdown with whatever headings help. Its home is agents.md.
- **Do I need both CLAUDE.md and AGENTS.md?** Not necessarily. Recent Claude Code versions read AGENTS.md when there is no CLAUDE.md. If you want Claude-specific rules, keep a short CLAUDE.md that imports AGENTS.md with @AGENTS.md.
- **Where does the file go?** At the root of the repository. Large repositories can add more in subfolders; the file nearest to the code being edited takes precedence, and a direct instruction in the chat overrides it.
- **How long should it be?** As short as it can be while still useful. It takes up context in every session, and a rule buried in a long file is easier for an agent to miss.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/