GUIDE / AGENTS.MD

An AGENTS.md quality checklist

A useful instruction file tells an agent what the repository is, how to work safely, and how to verify a change.

Start with project context

Describe the repository's purpose, language, important directories and boundaries. Prefer a few precise facts over a long company overview.

Provide commands that actually work

List setup, test, lint and build commands. Include the directory in which they should run, and explain any prerequisites. Verify these commands in CI or a clean checkout.

Define safety boundaries

Explain how secrets are handled, which files should not be edited, and which actions require explicit approval. Do not put credentials in the instruction file.

Specify what success looks like

Give acceptance criteria and required checks. A command alone is less useful than a command paired with an expected result.

Keep it maintainable

Use descriptive headings, short lists and links to authoritative documentation. Remove stale commands and contradictory rules as the repository evolves.

Validate with real tasks

Run representative agent tasks and inspect outcomes. Structural scores can highlight omissions, but they cannot prove that an agent will perform better.