Minimal AGENTS.md Template: What to Write in the Repo First

There is no required schema for an AGENTS.md template. The agents.md site recommends starting with project overview, build/test commands, code style, and security. Codex loads these files at session start; Cursor and many other agents recognize the same name.

This article covers the minimal bones only—not CLAUDE.md sync workflows or personal reviews.

What are the essential sections?

One-line answer: Overview + install/run/test commands + style + “don’ts” (secrets, forbidden paths) is enough.

No fields are mandatory. A paste-ready minimum:

# AGENTS.md

## Project overview
- What this repo ships in one paragraph.
- Primary language and package manager.

## Setup commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Code style
- TypeScript strict; prefer small PRs.
- Match existing file patterns before inventing new ones.

## Security
- Never commit `.env` or API keys.
- Do not run destructive git (`push --force`, hard reset) unless asked.

Per the Codex guide: global defaults live in ~/.codex/AGENTS.md, repo rules in root AGENTS.md, and package-specific rules in nested AGENTS.md / AGENTS.override.md. Combined size stops at project_doc_max_bytes (32 KiB by default).

What should you share with CLAUDE.md?

One-line answer: Share exact build/test/lint command strings and secret paths; keep tool-specific permission/hook syntax in each tool’s own file.

Safe to shareKeep tool-specific
Exact npm test / make check commandsClaude Code permissions JSON
Directory map, “which package to touch”Cursor Hooks / rules paths
PR title / pre-commit checklistCodex config.toml sandbox/approval

Minimal sync strategy:

  1. Write commands once in root AGENTS.md.
  2. In CLAUDE.md, point to AGENTS.md for repo norms; keep Claude-only permissions/hooks there.
  3. Codex can list alternate names in project_doc_fallback_filenames, but a single source of truth at root AGENTS.md stays simpler.

Mismatched commands make each agent run different checks—fix Setup first.

What if it gets too long?

One-line answer: Keep the root short, split into nested AGENTS.md files, and raise project_doc_max_bytes or split further when you hit Codex’s default 32 KiB cap.

Smells:

  • Monorepo package commands piled into one file
  • Style sections turning into essays
  • The same paragraph copied into CLAUDE.md, README, and rules

Fixes:

  1. Root: workspace-wide commands and security only.
  2. Nested: closest file wins (official rule).
  3. Override: Codex AGENTS.override.md replaces guidance for that directory.
  4. Cut: anything CI/linters already enforce, and stale migration notes.

Agents will try to run the test commands you list—short executable lists beat long prose.

Wrap-up

First AGENTS.md: overview → setup commands → style → security. Share commands with CLAUDE.md; nest files when it grows. See AGENTS.md and Custom instructions with AGENTS.md.

Sources