An AGENTS.md
file should make a coding agent safer and faster. But many instruction files become background noise: long, generic, contradictory, or impossible to verify.
Here are seven common failure modes—and the smallest fix for each one.
Weak:
Write clean, production-ready code.
Better:
Before finishing:
- run npm test
- run npm run lint
- do not modify generated files in src/generated/
Agents act more reliably on observable rules than on adjectives.
A root-level instruction file is useful, but a monorepo often needs narrower rules. Put specialized guidance closer to the code it governs:
/
├── AGENTS.md
├── apps/
│ └── web/
│ └── AGENTS.md
└── packages/
└── database/
└── AGENTS.md
The root file should define shared policy. Nested files should only add or override rules that genuinely differ.
"Run the tests" creates ambiguity. Which tests? From which directory? With which runtime?
Prefer exact commands:
Validation from repository root:
1. npm ci
2. npm run typecheck
3. npm test -- --runInBand
4. npm run build
If a command is slow or optional, say so explicitly.
A coding agent needs an exit condition. A useful acceptance checklist might be:
That turns a vague request into a checkable delivery.
AGENTS.md
should contain durable repository guidance: architecture, commands, boundaries, conventions, and validation.
The current task should live in the prompt or a separate brief:
## Objective
Add rate limiting to the public API.
## In scope
- middleware
- configuration
- tests
## Out of scope
- auth redesign
- database migration
## Acceptance criteria
- returns 429 after the configured threshold
- includes Retry-After
- existing API tests still pass
Keeping the two layers separate makes both easier to maintain.
Agents need to know what to do when the happy path breaks.
Add a compact recovery rule:
If validation fails:
1. determine whether the failure predates your change
2. fix failures caused by your change
3. do not weaken or delete tests to make them pass
4. report any verified pre-existing failure with the exact command and error
This prevents silent test deletion and vague "could not verify" handoffs.
An instruction file is an operational interface, not a company handbook. Put the highest-value rules first:
Link to deeper documentation instead of duplicating it.
## Repository map
- src/: application code
- tests/: automated tests
- docs/: user-facing documentation
- generated/: do not edit manually
## Working rules
- keep changes scoped to the request
- preserve public API compatibility unless explicitly requested
- follow the nearest existing pattern before adding a new abstraction
- never commit credentials or local environment files
## Validation
Run from the repository root:
- npm run lint
- npm run typecheck
- npm test
- npm run build
## Definition of done
- acceptance criteria are met
- relevant tests are added or updated
- validation passes
- final response summarizes changes and commands run
## Failure recovery
Do not bypass failing checks. Fix failures introduced by the change and clearly report verified pre-existing failures.
The template is intentionally small. The value comes from adapting it to the repository's real commands, architecture, risks, and release process.
I published a free AgentBrief starter with reusable examples. If you want a repo-specific audit and custom AGENTS.md
delivered in one day, the US$25 Fiverr package is the hands-on option.
What instruction has made the biggest difference in your coding-agent workflow?