Fabler Labs → Guides → AGENTS.md example

AGENTS.md example: a complete, copy-paste template

Free · no signup · verified against the spec · last updated July 2026

AGENTS.md is the open, tool-agnostic file that tells AI coding agents how your project works — the same job a CLAUDE.md does for Claude Code, but read by a whole ecosystem: OpenAI Codex, Cursor, GitHub Copilot's agent, Google Jules, VS Code, Zed, Aider, and more. One file, every tool. This page gives you a complete, copy-paste example, then the details that matter: where it goes, how monorepos resolve it, and how it relates to CLAUDE.md and .cursorrules.

A complete AGENTS.md example

Here's a realistic AGENTS.md for a TypeScript / Node service. Copy it, delete what doesn't apply, and replace the specifics with yours. There's no required format — the value is in the shape: concrete, verifiable instructions grouped under plain headers, with an explicit "don't touch" list.

# AGENTS.md

Instructions for AI coding agents working in this repo. Read this before
making changes. It applies to the whole repository unless a nested
AGENTS.md in a subproject overrides it.

## Project overview
Acme API — a TypeScript + Node service. REST API backed by Postgres.
Handlers are thin; business logic lives in services; all DB access is
funneled through one module.

## Setup & commands
- Install: `pnpm install` (we use pnpm, never npm or yarn)
- Dev server: `pnpm dev` (runs on http://localhost:3000)
- Test: `pnpm test` — run this before every commit
- Test one file: `pnpm test path/to/file.test.ts`
- Typecheck: `pnpm typecheck`
- Lint/format: `pnpm lint --fix` (Biome; do not add Prettier or ESLint)

## Project layout
- HTTP handlers: `src/api/handlers/`, one file per resource.
- Business logic: `src/services/` — handlers stay thin.
- Database access: `src/db/` only — never import `pg` directly elsewhere.
- Shared types: `src/types/`. Generated types are in `src/types/gen/`
  — never edit those by hand; regenerate with `pnpm gen:types`.

## Code style & conventions
- 2-space indentation. Named exports only (no default exports).
- Validate all request input with the Zod schemas in `src/schemas/`.
- Return errors via `problemJson(res, status, detail)` — never `res.json`
  a raw error. This keeps the error shape consistent for clients.
- Every new endpoint needs a test in `tests/` and an entry in `openapi.yaml`.

## Testing instructions
- Vitest. Tests are colocated as `*.test.ts` next to the code they cover.
- Integration tests need a local Postgres: `docker compose up -d db` first.
- After changing an endpoint, run the tests and confirm they pass before
  you report done — don't just typecheck.

## Commit & PR guidance
- Conventional Commits (`feat:`, `fix:`, `chore:`). Branch off `main`;
  never commit directly to `main`.
- Keep PRs focused; include what changed and how you verified it.

## Do not
- Do not edit anything under `src/types/gen/` or `migrations/` by hand.
- Do not add new dependencies without flagging it first — check if a
  helper in `src/lib/` already does the job.

Notice what's not here: no "write clean code," no restating language docs, no essay. Every line is something a new teammate would have to be told, phrased concretely enough that an agent can act on it.

Where the file goes

AGENTS.md lives at your repo root (./AGENTS.md) and is checked into version control, so every teammate and every agent reads the same instructions. It's plain Markdown — no frontmatter, no schema, nothing to register. An agent that supports the standard discovers it automatically at the start of a session.

Monorepos: you can drop an AGENTS.md inside any subproject as well as at the root. When guidance conflicts, the AGENTS.md closest to the file being edited wins — so a root file sets house-wide defaults and a packages/web/AGENTS.md can add or override rules just for that package. Agents read the nearest one; you don't have to repeat the root's contents.

No required format — but a good default set of sections

Because there's no schema, the file is only as useful as what you put in it. These are the sections the ecosystem's examples converge on — use the ones that apply and skip the rest:

• Project overview — one paragraph on what this is and how it's shaped.
• Setup & commands — the exact invocations to install, run, test, and lint.
• Project layout — where things live, so the agent doesn't scatter files.
• Code style & conventions — the non-obvious rules a new hire would need told.
• Testing instructions — how to run tests and the expectation to actually run them.
• Commit & PR guidance — commit format, branch rules, what a PR should contain.
• Do not — generated files, protected paths, "never commit to main."

Keep it tight. The file is loaded into the agent's context, so every line costs tokens on every run and a shorter, sharper file is followed more reliably than a sprawling one. Aim for what a capable teammate couldn't infer from the code alone.

Which tools read AGENTS.md

The point of the standard is that one file works everywhere. Agents that read AGENTS.md natively include OpenAI Codex, Cursor, GitHub Copilot's coding agent, Google Jules, VS Code, JetBrains Junie, Zed, Warp, and Aider, among others — the site lists 25+ integrations and the roster keeps growing. As of mid-2026 the project reports it's used by over 60,000 open-source repositories. That's the pitch: write your project's operating manual once instead of maintaining a different file per tool.

The notable exception is Claude Code, which reads its own CLAUDE.md and not AGENTS.md. That's easy to bridge — see below — so you can keep a single source of truth even in a mixed-tool team. (Claude Code's /init command will also read an existing AGENTS.md and fold it into the CLAUDE.md it generates.)

AGENTS.md vs CLAUDE.md vs .cursorrules

• vs CLAUDE.md. Same job, different reader. Put your instructions in AGENTS.md and give Claude Code a CLAUDE.md whose only line is @AGENTS.md (Claude Code imports it), or symlink CLAUDE.md → AGENTS.md. Now both ecosystems read one file. Add Claude-specific notes below the import if you need them.
• vs .cursorrules. Cursor reads AGENTS.md, and the old single-file .cursorrules format is deprecated in favor of AGENTS.md or Cursor's newer .cursor/rules/ directory (scoped rule files with frontmatter). If you still have a .cursorrules, migrate its contents into AGENTS.md so every tool shares one source.

The migration in one move: make AGENTS.md the source of truth, then point the tool-specific files at it (import or symlink). One file to edit; every agent stays in sync.

The 5-line checklist for a good AGENTS.md

1. Commands — how to install, run, test, and lint, with the exact invocations.
2. Layout — where things live, so the agent doesn't scatter files.
3. Conventions — the non-obvious rules a new hire would need told.
4. Do-not — generated files, protected paths, "never commit to main."
5. Verify — one line telling the agent to exercise its changes, not just typecheck.