Why commands matter most
Most agent tasks end in a build or a test. List the exact commands and the agent runs them, reads the output, and fixes its own errors before finishing. Leave them out and it guesses — or reports success on code that never passed.
Be literal
"Run the tests" can't be executed. pnpm test can.
## Commands
Install: pnpm install --frozen-lockfile
Dev: pnpm dev
Build: pnpm build
Test (all): pnpm test
Test (one): pnpm test -- path/to/file.test.ts
Typecheck: pnpm typecheck
Lint + fix: pnpm lint --fix
Don't skip the single-test command
Test (one) lets the agent iterate in seconds on a focused change instead of running the whole suite (or skipping verification entirely).
Name the gate
Say what must pass before a change is "done" — types, lint, tests. The agent treats that as the bar to clear. Bonus: make it match your CI so the work it considers done is work that actually merges.
Monorepo?
Put workspace-wide commands at the root and package-specific ones in each package's AGENTS.md — the nearest file wins.
Free cheat sheet: the format, an annotated example, and the one-line test — AGENTS.md Cheat Sheet.
Go deeper: the full reference — cross-tool setup, the monorepo hierarchy, and a 30-day plan — AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.
What's in your commands section that's saved you the most rework? 👇
Top comments (2)
This is one of those small pieces of advice that saves a disproportionate amount of pain. When an agent has exact build, test, and typecheck commands, it stops guessing what "done" means and starts converging on the same bar your CI enforces. I have seen the single-test command matter even more than the full-suite command because it is what keeps the iteration loop fast enough for the agent to actually self-correct instead of bailing early. The other half is visibility into which commands it chose and how many failed retries it burned before succeeding. Do you also recommend pairing AGENTS.md with an execution trace or command log, or do you view that as a separate harness concern?
Glad that one landed — the single-test command is genuinely the detail people skip and then wonder why the agent burns 40 turns running the full suite for a one-line change.
On the trace/log question: I think of it as a different layer, but a layer you want anyway, and I'd loosely pair it rather than treat it as fully separate. AGENTS.md is the declared contract — what "done" and "correct" mean, stated once, upfront. A command log is the empirical record of whether the agent actually operated inside that contract. Without it you're trusting that the agent followed the commands you wrote; with it you can see the gap between declared and actual — which command it reached for, how many retries before it converged, where it drifted to something you didn't specify.
That gap is also the best source of edits to AGENTS.md itself. If a command keeps getting retried or substituted, that's not a harness problem, that's the file telling you it's ambiguous or wrong for a scenario you didn't cover.
So: full observability harness (spans, structured traces, dashboards) — separate concern, build it if you need it. But some form of lightweight command log — what ran, exit code, retry count — I'd consider close to required, because it's the only way to know if the AGENTS.md you wrote is the AGENTS.md the agent is actually using.