VocalFuse is a Fuse Intelligence product.

AGENTS.MD GUIDE

AGENTS.md Template: Brief Your Coding Agents in One File

AGENTS.md is the plain-Markdown file at your repo root that tells AI coding agents how your project builds, tests, and behaves. In 2026 it is the closest thing agent tooling has to a standard — 60,000+ open-source projects ship one, and Claude Code, Codex, Cursor, Copilot, Windsurf, and Cline all read it. Copy the five-section AGENTS.md template below, then run your agents in VibeFuse — the free widget-based harness that keeps every agent on one canvas.

Copy the template Get the free harness

What is AGENTS.md?

AGENTS.md is a plain Markdown file committed to your repository root that briefs AI coding agents before they touch a single file: the real commands, the conventions, what "done" means, and what never to modify. The format is deliberately minimal — no schema, no frontmatter, no required headings. As the official site puts it, it's "a README for agents": standard Markdown the agent parses as plain text. When several AGENTS.md files exist in a directory tree, agents apply the one closest to the file being edited; the nested file wins.

Adoption crossed from convention to standard during 2026. The format's repository sits at roughly 23,000 stars, the open-source count is estimated above 60,000 projects, and more than 25 tools read the file — Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf, VS Code agent mode, and Cline among them. Cursor deprecated .cursorrules in AGENTS.md's favor. An exploratory study presented at AIware '26 (co-located with FSE in Montreal), which analyzed configuration mechanisms across Claude Code, Copilot, Cursor, Gemini CLI, and Codex in 3,000+ real repositories, concluded that repository-level artifacts like AGENTS.md are the natural starting point for harness engineering.

Why it matters: most agent failures are context failures, not capability failures. A fresh agent guesses your test command, invents a style that matches nothing, "fixes" a bug by deleting the code that loaded the value, or commits generated files. Every one of those is the agent not knowing something your repo never stated. AGENTS.md is the cheapest fix — one file, read at the start of every session, on every tool.

One nuance worth knowing before you write yours: tool loading rules differ. Claude Code reads AGENTS.md natively (and concatenates every CLAUDE.md up the tree rather than picking the nearest), Cursor and VS Code agent mode read it directly, and older tool versions may need a one-line shim or symlink — though on Windows, prefer a copy or an import over a symlink, which requires Administrator privileges. Check your tool's current docs; this area moved fast in 2026.

The AGENTS.md template (copy-paste)

Five sections, roughly forty lines, every one earning its place in context. AGENTS.md rides in the agent's context on every task, so every line is a recurring tax — this template is short on purpose. Fill the brackets, delete what doesn't apply, keep the five headings. 

# AGENTS.md

## Purpose
[One sentence: what this repo is and does]

## Commands
- Setup: [exact command]
- Run: [dev/start command]
- Test: [exact command incl. filter flags — e.g. uv run pytest -m "not e2e"]
- Lint: [command]
- Typecheck: [command]
- Build: [command]

## Workflow
- [Branch naming, commit style, PR process]
- [Run the full check above; paste the output in the PR body]

## Style
- [Language/formatting conventions the linter can't catch]
- [Naming patterns that exist nowhere else]

## Boundaries & Gotchas
- Don't edit [generated paths] — regenerated on every build
- Don't modify existing files in [migrations dir] — append new ones
- Secrets come from env vars; never hardcode or commit real data
- [The one command that looks safe but isn't]

## Done means
- Test suite green, no new lint or type errors
- If behavior changed, a test changed with it

Commands is the highest-value section

The single-file test command alone pays for the file: without it, agents run your full suite after every edit. Include exact filter flags.

Keep it under ~150 lines

Past that, split by package rather than adding sections. Monorepos: a root file with global facts, then short per-package files with local deltas — the nearest file wins.

Pointers, not essays

Agents can read code; they need commands and boundaries, not architecture narrative. Link long docs (see docs/architecture.md) instead of carrying them every turn.

What NOT to put in AGENTS.md

The most common mistake is treating AGENTS.md like documentation. Four things consistently waste context and teach the agent your file is decoration:

Rules you don't enforce are worse than no rule: production examples show agents inherit the file's precision. Keep only what's true regardless of which agent shows up, and push tool-specific config into the tools that own it.

AGENTS.md and the harness: the config layer is half the loop

AGENTS.md configures what the agent knows; the harness configures what the agent can do. Harness engineering — the 2026 discipline covered in our harness engineering guide — treats the loop, tool access, context management, and verification as design decisions, and the AIware '26 study found repository-level files like AGENTS.md are where that engineering starts. The two layers compose: a well-briefed agent still needs a workspace that keeps the loop visible.

That is where VibeFuse comes in. It is the first ever free widget-based AI harness: Claude Code, Codex, Gemini CLI, Cursor Agent, and Qwen run side by side as live widgets on one canvas, MCP tools wire in with legible errors, and named sessions persist your layout per repo — so the agent that just read your AGENTS.md runs inside a loop you designed, not inside one vendor's defaults.

Going deeper: pair the file with spec-driven development (spec-first workflow, GitHub Spec Kit), read agentic engineering for the orchestration discipline, and see vibe coding security for the review gates every AI-built change needs. Compare harnesses in our best vibe coding tools breakdown, or see how VibeFuse works as a Claude Code GUI and Cursor alternative.

  • ✓ Every agent CLI as a widget
  • ✓ MCP + Skill Seekers
  • ✓ Named per-repo sessions
  • ✓ 80% creator payouts
Run your agents free Browse the marketplace

Explore VibeFuse & harness guides

AGENTS.md template FAQ

What is AGENTS.md?

AGENTS.md is a plain Markdown file at your repository root that tells AI coding agents how your project works: the real build/test commands, conventions, what "done" means, and what never to modify. Agents read it automatically at the start of every session. There is no required schema — standard Markdown with any headings works.

Which tools read AGENTS.md?

In 2026, Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf, VS Code agent mode, and Cline all read AGENTS.md natively or via a one-line shim — over 25 tools total. Cursor deprecated .cursorrules in its favor. Check your tool's current docs for loading rules, because they differ: Claude Code concatenates every CLAUDE.md up the tree, while AGENTS.md uses nearest-file-wins.

What should an AGENTS.md file contain?

The five highest-value sections: Purpose (one sentence), Commands (exact setup/test/lint/typecheck/build commands with filter flags), Workflow (branching, commits, PR process), Style (conventions the linter cannot catch), and Boundaries (generated paths never to edit, secrets rules, known gotchas). Keep the whole file under roughly 150 lines.

What should I NOT put in AGENTS.md?

No long tutorials or architecture essays (agents can read code — link docs instead), no duplicate README content, no unenforceable absolute rules like "always write perfect code" (they teach the agent your file is decoration), and no secrets or internal URLs — the file is committed.

Where does AGENTS.md go in a monorepo?

Place one AGENTS.md at the repository root with global facts and shared commands, then short per-package files with only local deltas. Agents apply the closest file to the code being edited, and the nested file overrides the root. Past ~150 lines, split by package instead of adding sections.

Does AGENTS.md replace CLAUDE.md or .cursorrules?

It can. AGENTS.md is the cross-tool shared file; CLAUDE.md is Claude Code-specific and .cursorrules is deprecated by Cursor. The cheapest portable setup in 2026 is AGENTS.md as the source of truth plus a thin bridge where a tool still expects its own file. Tool-specific config that a tool owns (hooks, MCP wiring) stays in that tool's config.