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.
1. The instructions describe aspirations, not commands
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.
2. The file ignores repository boundaries
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.
3. The commands are not copy-pasteable
"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.
4. There is no definition of done
A coding agent needs an exit condition. A useful acceptance checklist might be:
- requested behavior is implemented
- existing public APIs remain compatible
- relevant tests cover the change
- lint, typecheck, and build pass
- no secrets, generated artifacts, or unrelated refactors are included
- the final response lists changed files and verification results
That turns a vague request into a checkable delivery.
5. The file mixes permanent policy with task-specific context
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.
6. Failure recovery is missing
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.
7. The file is too long to scan
An instruction file is an operational interface, not a company handbook. Put the highest-value rules first:
- repository map
- exact commands
- scope boundaries
- coding conventions that are unique to the repo
- validation checklist
- recovery rules
Link to deeper documentation instead of duplicating it.
A compact starter template
# AGENTS.md
## 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?
Top comments (0)