agents-md

Writing the AGENTS.md verify step agents actually run

A good AGENTS.md verify section is a short, ordered list of exact commands. Fast checks come first, and each command has a stated pass condition the agent must hit before it reports done. Scope it to the package being changed, say which commands are off-limits, and keep anything slow or destructive out of the default path. What belongs in AGENTS.md vs README covers what goes in the file. This post covers how to write the verify block itself so agents actually run it.

Anatomy of a verify block (template)

These commands are only an example. Use your repo's real ones.

md
## Verify (run before saying done)
1. `pnpm lint`          → exits 0
2. `pnpm typecheck`     → exits 0
3. `pnpm test --filter <changed-package>` → all pass
4. If you touched API routes: `pnpm test:e2e --filter api` → all pass
Done = all of the above green. If any fail, fix or report the failure; do not claim done.

Fast-first ordering and pass criteria

  • Put the cheapest checks first so obvious breaks fail in seconds.
  • Write the pass condition explicitly ("exits 0", "all pass"). Agents follow concrete criteria much more reliably than "make sure it works."
  • Tell the agent what to do when a check fails: fix it, or stop and report.

Per-package verify

In a monorepo, the root sets the shared rule ("always run verify"), and each package's nested AGENTS.md lists its own commands. The inheritance map shows where each part lives.

The don't-run list

Name commands the agent must never run without asking: deploys, database migrations against shared environments, anything that publishes, and anything that needs production secrets. An explicit list beats hoping the agent infers it.

Verifier subagents

If you use a separate verifier pass (see the subagents and verifier pattern), point it at this same block so the writer and the checker share one definition of done.

Where the kit fits

The Operator Pack ($47) is markdown seats + skills + install.sh — not a hosted app, not a chatbot. Seven named seats, three skills, an ops playbook and a token-cost playbook. Done means a file, PR, or URL. Same pack for Cursor, Claude Code, and Grok Bot. Soft path: start at /free. Cheat Sheet for the skim checklist mindset.

Soft next step

Replace "run tests" with an ordered command list and explicit pass criteria in one package today. Soft ladder: /free, then the Operator Pack ($47). Related: AGENTS.md vs README, inheritance map, nested AGENTS.md playbook.

FAQ

What should the verify section of AGENTS.md contain?+

Exact commands to run, in order, plus what passing looks like. Fast checks go first (lint, typecheck), then tests, then build.

How do I make agents run tests before finishing?+

Define "done" as "verify passes" in AGENTS.md and list the commands explicitly. Vague lines like "make sure it works" get skipped.

Should verify commands differ per monorepo package?+

Yes. Root holds shared defaults, and each package's nested AGENTS.md scopes verify to that package so agents don't run the whole repo every time.

How long should an agent verify step take?+

As short as it can be while still catching real breaks. Put fast, scoped checks first and keep slow full-suite runs as a separate, named step.

How does a verifier subagent use AGENTS.md?+

It reads the same verify block and runs it independently, then reports pass or fail against the stated criteria. One source of truth keeps the builder and verifier aligned.

What commands should agents never run?+

List them explicitly: destructive operations, deploys, production migrations, and anything that sends, publishes, or pays. Never-run rules belong in AGENTS.md next to verify.

Get the free starter

Value first, then a kit when you are ready. No fake urgency. Start with Harness Desk Starter at /free.

Get the free starter →See the Operator Pack →