Playbook · May 20, 2026 · Last updated 2026-05-20 · 14 min read

AGENTS.md for Claude Code, Codex, and Cursor

AGENTS.md is where a repo stops relying on prompt memory. If Codex, Claude Code, Cursor, and CI all learn the project from different scraps, every agent run becomes a negotiation. A good AGENTS.md turns the repo into an operating room: the commands are obvious, the guardrails are durable, and the handoff is clear enough for the next agent to continue.

AGENTS.md control room coordinating coding agents — AGENTS.md should be short enough to be read every run and specific enough to prevent expensive guesses.

Questions this page answers

What should go in AGENTS.md for a coding-agent repo?
How do I keep Codex, Claude Code, Cursor, and CI using the same rules?
Which instructions belong in AGENTS.md versus prompts or tickets?
How does a persistent Mac make agent instructions more reliable?

Copy this

A Practical AGENTS.md Template

# AGENTS.md

## Mission
Ship small, reviewed changes that preserve production behavior.

## Commands
- Install: npm install
- Lint: npm run lint
- Typecheck: npm run typecheck
- Unit tests: npm test
- E2E: npm run test:e2e
- Build: npm run build

## Rules
- Do not commit secrets.
- Do not rewrite unrelated files.
- Keep changes scoped to the ticket.
- Add tests for behavior changes.
- Prefer existing patterns over new abstractions.

## Definition of done
- Relevant tests pass.
- Docs updated when behavior changes.
- Risks and rollback are listed in the PR.

## Handoff
- Summarize what changed.
- List checks run.
- List open risks or follow-ups.

What Belongs In AGENTS.md

Section	Include	Avoid
Mission	The product-shaped goal agents should optimize for.	A generic company manifesto.
Commands	Install, lint, typecheck, test, e2e, build, and local dev commands.	Commands that only work on one person's laptop.
Guardrails	Security, data, migration, dependency, and deployment rules.	Vague style preferences with no enforcement.
Definition of done	The proof required before a PR is reviewable.	A wishlist that nobody checks.
Handoff	What the next agent or human needs to know.	Long logs or copied terminal output.

Shared Rules Versus Tool-Specific Memory

AGENTS.md is the shared operational contract. Tool-specific memory can still exist, but it should not contain the only copy of a critical build command, migration rule, or security constraint.

Where	Use it for	Risk
AGENTS.md	Repo-wide commands, guardrails, and handoff rules.	Becomes noisy if it tries to document every subsystem.
Claude Code or Codex session prompt	The current ticket, branch, and acceptance criteria.	Disappears after the session or gets buried in chat.
Issue or Linear ticket	Business context, user story, and product constraints.	May not include the commands needed to prove the change.
CI config	Enforcement.	Can tell agents what failed but not why the repo is shaped that way.

Write Instructions Agents Can Actually Use

Prefer concrete commands over prose.
Say which folders are generated, owned externally, or unsafe to edit.
Call out production state, billing paths, auth flows, and migrations by name.
Use short examples for PR summaries, test evidence, and rollback notes.
Remove stale instructions as aggressively as you add new ones.

The AGENTS.md smell test

If a new engineer cannot use the file to make one safe change on day one, an agent will not do better. Cut the poetry. Keep the commands.

Why Persistent Machines Make Instructions Matter More

On a short-lived sandbox, a bad instruction usually wastes one run. On an always-on agent host, bad instructions can repeat every morning. That is why the file needs to include recovery, logging, and approval rules, not just code style.

## Background agents
- Long-running jobs must write logs to ./logs/agents/
- Risky actions require human approval before execution
- If a job fails twice, stop and summarize the failure
- Never rotate credentials or modify billing state unattended
- Record restart reason in the task handoff

Review Checklist For AGENTS.md Changes

Does every command still run on a fresh machine?
Can the file be read in under two minutes?
Are safety rules specific enough to block bad actions?
Does the definition of done match CI and human review?
Did you remove old instructions that contradict the new flow?

Frequently asked questions

Is AGENTS.md only for Codex?

AGENTS.md is a useful pattern for Codex, and the broader idea works anywhere a coding agent needs repo-local instructions. Keep tool-specific files when a tool requires them, but use one shared source of operational truth.

What should not go in AGENTS.md?

Do not put secrets, giant architecture essays, stale setup notes, or vague preferences in AGENTS.md. Put durable commands, safety rules, definitions of done, and handoff expectations there.

How often should AGENTS.md change?

Update it when build commands, test commands, safety policy, deployment flow, or repo ownership changes. If an agent learns something important twice, promote that lesson into the file.

Always-on Mac runtime

Give your agent a Mac that stays online after your laptop closes.

Hyperbox gives Codex, Claude Code, OpenClaw, and remote dev workflows a persistent macOS machine with SSH, VNC, and full desktop access.

Start with Hyperbox