best-of-Agent-Harnesses

One AGENTS.md for every coding agent

One briefing file that Codex, Claude Code, Cursor, OpenCode, GitHub Copilot, Gemini CLI, and Aider all read, so you write your build commands, conventions, and hard rules once instead of once per tool.

What is in this template

File Copy it to Why
AGENTS.md the repo root The briefing file. Fill in the <...> parts and delete what does not apply.
CLAUDE.md the repo root, only if you need it Claude Code 2.1.277 and later reads AGENTS.md by itself when there is no CLAUDE.md (docs). Add this one-line import for older versions, or when you want Claude-only rules on top.
.gemini/settings.json .gemini/settings.json Gemini CLI reads GEMINI.md unless you point it at AGENTS.md (agents.md).
.aider.conf.yml the repo root Aider loads the file only when told to (agents.md).

Codex, Cursor, OpenCode, GitHub Copilot's coding agent, Zed, Warp, Jules, goose, Amp, and Windsurf read AGENTS.md with no extra file (the list at agents.md).

Install

curl -fsSLO https://raw.githubusercontent.com/RyanAlberts/best-of-Agent-Harnesses/main/templates/agents-md/AGENTS.md

Or ask your agent to do it: with the MCP server installed, say "get the agents-md template and fill it in for this repo". The agent reads your build files and fills in the commands; check what it writes.

Why the file is shaped this way

Instructions are advice, not enforcement. An agent can still ignore "Never push to main". To block an action for real, use a permission rule or a hook: the safe Claude Code settings template does this for Claude Code.

Go further

.aider.conf.yml

Raw file

read: AGENTS.md

.gemini/settings.json

Raw file

{
  "context": {
    "fileName": "AGENTS.md"
  }
}

AGENTS.md

Raw file

# AGENTS.md

<!-- Replace every <...> and delete what does not apply. Keep this file under
     150 lines: it loads into every session, so every line costs context. Put
     long procedures in docs/ and link them below instead of pasting them here. -->

## Project

<one or two sentences: what this repo is, who uses it, and the one thing an agent must not break>

## Commands

- Install: `<npm ci | uv sync | go mod download>`
- Build: `<npm run build>`
- Test, all: `<npm test>`
- Test, one file: `<npm test -- path/to/file.test.ts>`
- Lint and format: `<npm run lint && npm run format>`
- Run locally: `<npm run dev>` (serves on `<http://localhost:3000>`)

Run the one-file test while you work and the full test and lint commands before you say a task is done.

## Layout

- `<src/api/>`: <HTTP handlers; one file per resource>
- `<src/core/>`: <business logic; no I/O here>
- `<src/db/>`: <schema and migrations; migrations are append-only>
- `<tests/>`: <mirrors src/; fixtures in tests/fixtures/>

## Conventions

- <Language and version, e.g. TypeScript 5 strict mode, Python 3.12 with type hints>
- <Error handling rule, e.g. return errors, do not throw across module boundaries>
- <Naming rule, e.g. files kebab-case, types PascalCase>
- Match the style of the file you are editing over any general preference.
- Add or update a test for every behavior change.

## Boundaries

Always:
- Read a file before you edit it.
- Keep changes to what the task asks for; mention other problems you notice instead of fixing them.

Ask first:
- Adding a dependency.
- Changing a public API, a database schema, or CI configuration.
- Deleting files.

Never:
- Commit secrets, or read `.env` files and credentials.
- Push to `<main>`, force-push, or rewrite history.
- Edit generated files: `<dist/, *.lock, src/generated/>`. Change the generator instead.

## More detail, loaded only when needed

- Architecture: `<docs/architecture.md>`
- Release process: `<docs/releasing.md>`
- <Subdirectory rules live in their own AGENTS.md, e.g. `packages/web/AGENTS.md`; the closest file to the code wins.>

CLAUDE.md

Raw file

@AGENTS.md

<!-- Claude Code 2.1.277 and later reads AGENTS.md by itself when a repo has no
     CLAUDE.md, so you only need this file for older versions, or to add rules
     that apply to Claude Code alone. Put those rules below the import line. -->