AGENTS.md can give a coding agent useful project context, but a poorly maintained file can create more confusion than clarity. The best guidance is short, specific, and checked against the repository it describes.
Here are seven common AGENTS.md pitfalls and practical ways to avoid them.
1. Treating AGENTS.md as universal truth
A repository guide is not a replacement for source code, tests, package scripts, or security review. If the file says one thing and the codebase consistently does another, the agent receives conflicting signals.
Fix: describe the current architecture and point to the files or scripts that prove it. Update the guide when the project changes.
2. Duplicating instructions across files
Copying the same rules into AGENTS.md, tool-specific files, and long prompt templates creates drift. One file gets updated while another keeps an obsolete command or directory name.
Fix: keep durable, tool-neutral decisions in AGENTS.md. Put only genuinely tool-specific behavior elsewhere, and make one document the source of truth.
3. Writing a wall of vague advice
“Write clean code” and “follow best practices” are hard for both humans and agents to apply. Long prose also hides the few rules that matter most.
Fix: use concrete checks: which command runs, where tests live, what must never be committed, and what a completed change must include.
4. Forgetting repository scope
5. Omitting security boundaries
An agent should not infer that browser input is trusted, that a hidden UI control is authorization, or that an environment variable is safe to expose. Missing reminders around secrets and server boundaries can turn a quick change into a serious bug.
Fix: state where authentication, authorization, validation, and secret-bearing code belong. Explicitly forbid logging tokens and committing credential files.
6. Letting rules contradict local conventions
A template that mandates a new architecture can be worse than no template. Forcing a team to rename folders, change its package manager, or adopt a different data-access pattern adds noise to every task.
Fix: use AGENTS.md to explain existing conventions first. Add exceptions only when the repository has made a deliberate decision.
7. Never testing whether the guidance works
A file can look excellent and still be ignored, stale, or too broad. Without a small verification loop, nobody knows whether an agent sees the right context.
Fix: make a harmless test edit, run the narrowest relevant checks, and review the diff. Remove rules that produce irrelevant suggestions.
A practical AGENTS.md checklist
Before relying on a project guide, confirm that it:
- names the real stack and directory layout;
- lists the normal install, lint, typecheck, and test commands;
- explains validation and authIf you want a ready-to-adapt starting point, the free Vildanden Agent Config sample includes an
AGENTS.md, a lean companion guide, scoped rules, and prompt templates for a Next.js + React workflow:
Download the free Vildanden sample
You can also preview the material on the Vildanden landing page. For builders who prefer an optional $9 crypto checkout, the same Vildanden offer is available at less-buddy-712.rehost.page.
Start small: adapt the sample to your repository, keep the rules honest, and review every generated diff. An effective AGENTS.md is not the longest one—it is the one that stays accurate when the code changes.
*Disclosure: This post was created for Vildanden. Templates are starting points, not a substitute for engineering judgment, testing, or security review.*orization at server boundaries;
- keeps secrets, credentials, and private data out of source and logs;
- defines a clear finish state for changes;
- avoids duplicating long instructions in multiple places; and
- is reviewed whenever the repository architecture changes.
An instruction written for a small app may be wrong in a monorepo, a src/ layout, or a project with multiple services. Generic paths and commands can lead the agent to edit the wrong package.
Fix: name the relevant directories, package manager, test commands, and service boundaries. Say when a rule applies only to one package.
Top comments (0)