Common Mistakes & Conflicting Instructions
Even a well-intentioned AGENTS.md can make an agent less effective.
The most common problems aren't complicated syntax errors.
They're things like:
- Vague instructions.
- Duplicate rules.
- Contradictions.
- Wrong scope.
- Stale commands.
- Excessive restrictions.
- Too much context.
- Rules that should be enforced by tools instead.
Let's learn how to recognize and fix them.
1. Vague Instructions
Consider:
- Follow best practices.
- Write clean code.
- Make sure everything works.
Nothing here is necessarily wrong.
But these instructions don't tell the agent what your project actually expects.
✅ Better
- Keep business logic inside services.
- Add unit tests for new service-layer logic.
- Run `pnpm lint` and `pnpm test` before completing application changes.
Replace vague intentions with observable actions.
2. Duplicate Instructions
As AGENTS.md evolves, similar instructions often accumulate.
## Development
- Run tests before finishing.
## Testing
- Always make sure tests pass.
## Validation
- Run the test suite before completing work.
All three express roughly the same idea.
Why is duplication a problem?
It:
- Adds unnecessary context.
- Makes the file longer.
- Makes future updates harder.
- Can create subtle inconsistencies.
✅ Fix
Keep one authoritative instruction:
## Validation
- Run `pnpm test` before completing application changes.
3. Direct Contradictions
Now consider:
## Development
- Use npm for dependency management.
## Package Management
- Always use pnpm.
The agent has been given two incompatible instructions.
Another example:
- Add tests for every bug fix.
and later:
- Do not modify tests unless explicitly requested.
Both may have sounded reasonable when they were added.
Together, they create ambiguity.
Fix the policy, not the wording
Decide what the repository actually expects.
For example:
- Use `pnpm` for dependency management.
and:
- Add regression tests when fixing bugs.
- Do not modify unrelated existing tests unless required by the change.
Now the rules can coexist.
4. Root vs Nested Conflicts
Conflicts can also occur across instruction files.
Root
- Use Vitest for unit tests.
packages/legacy/AGENTS.md
- Use Jest for unit tests.
This might be intentional.
Perhaps the legacy package hasn't migrated yet.
If so, make the exception explicit:
# Legacy Package
- This package still uses Jest.
- Continue using Jest for tests in this package.
- Do not migrate to Vitest unless the task explicitly requires the migration.
Now the difference looks intentional rather than accidental.
5. Wrong Scope
Suppose the root AGENTS.md says:
- Validate every request using Zod.
But the repository contains:
web/
api/
mobile/
infrastructure/
That rule probably applies only to the API.
❌ Wrong
Root AGENTS.md
→ Validate every request using Zod.
✅ Better
api/AGENTS.md
→ Validate incoming API request payloads using Zod.
Put instructions at the broadest scope where they remain correct.
6. Stale Instructions
Suppose your project used to run:
npm test
but migrated to:
pnpm test
If AGENTS.md still says:
- Run `npm test` before completing changes.
the agent may correctly follow an incorrect instruction.
This is particularly dangerous because the agent isn't necessarily doing anything wrong.
Your documentation is wrong.
Treat AGENTS.md as maintained project configuration
When changing:
- Package managers.
- Test frameworks.
- Folder structures.
- Build commands.
- Architecture.
- Generated-code workflows.
check whether AGENTS.md also needs updating.
7. Instructions That Fight the Repository
Imagine AGENTS.md says:
- Use repository classes for all database access.
But the entire application actually uses:
Server Action
↓
Supabase client
with no repository layer.
Now the instruction contradicts the established architecture.
Agents may start introducing unnecessary abstractions just to satisfy the file.
Instructions should describe the architecture you actually want—not an idealized architecture copied from another project.
8. Excessive Restrictions
Consider:
- Never create new files.
- Never add dependencies.
- Never modify existing tests.
- Never refactor existing code.
- Never change function signatures.
This may feel "safe."
But it can make legitimate development nearly impossible.
Prefer boundaries that explain the actual concern.
Instead of:
- Never add dependencies.
consider:
- Reuse existing dependencies when practical.
- Add a new production dependency only when existing dependencies do not reasonably satisfy the requirement.
The second rule preserves flexibility while communicating the goal.
9. Too Many "Always" and "Never" Rules
Absolute rules are useful for genuine boundaries:
- Never commit secrets.
But this:
- Always create a new abstraction for shared logic.
- Always add comments to functions.
- Always write integration tests.
- Always create separate files for types.
can force poor decisions.
Use absolute language only when the requirement is actually absolute.
10. Instructions That Are Too Detailed
Consider:
When creating a React component:
1. Create the file.
2. Import React.
3. Define the props.
4. Define the component.
5. Add the JSX.
6. Export the component.
A capable coding agent doesn't need this.
What might actually matter is:
- Reuse components from `src/components/ui` before creating new shared UI.
- Keep feature-specific components inside their feature directory.
Focus on project decisions the agent cannot safely infer.
11. Putting Tooling Rules in AGENTS.md
Suppose you write:
- Use single quotes.
- Use trailing commas.
- Use two spaces for indentation.
- Keep lines under 100 characters.
If Prettier already enforces these rules, you're maintaining the same policy twice.
Better:
- Run `pnpm format` when formatting changes are required.
Let automated tools enforce mechanical rules.
Use AGENTS.md to tell the agent which tools and workflows to use.
12. Too Much Context
Imagine an AGENTS.md containing:
Project history
Company history
Architecture documentation
API documentation
Database schema
Coding conventions
Deployment guide
Every development command
Every possible edge case
Eventually the useful instructions become difficult to distinguish from background information.
A good question is:
Does this information change how the agent should perform its coding task?
If not, it may belong somewhere else.
13. Copy-Pasting AGENTS.md Between Projects
You find a great AGENTS.md online and copy it.
It contains:
- Use Prisma for database access.
- Run `yarn test`.
- Use Jest.
- Place components inside `src/ui`.
Your project uses:
Supabase
pnpm
Vitest
src/components
The template is now actively harmful.
Examples and templates are starting points.
Every instruction should be checked against the actual repository.
14. Instructions Without the Correct Workflow
Consider:
- Do not edit generated files.
Good boundary.
But what should the agent do when generated files need changing?
Better
- Do not manually edit files inside `src/generated`.
- Modify the source schema and run `pnpm generate` instead.
Whenever possible, pair:
Don't do X
+
Do Y instead
15. Conflicting Sources of Truth
Imagine:
README
Use pnpm.
AGENTS.md
Use npm.
CI
yarn install
package.json
{
"packageManager": "pnpm@10.0.0"
}
Now the problem isn't only AGENTS.md.
The repository itself has inconsistent guidance.
A coding agent can't reliably resolve organizational confusion.
When you find this situation, establish one source of truth and update the others.
16. Overriding Instead of Adding Specificity
Suppose the root says:
- Add tests for new business logic.
A nested API file says:
- Use Vitest for service tests.
Great.
The nested rule adds specificity.
But this:
Root
- Add tests for new business logic.
API
- Tests are optional for API changes.
creates a real policy conflict.
Prefer nested files that add relevant detail rather than constantly reversing parent instructions.
17. A Broken AGENTS.md
Let's diagnose this:
# Instructions
React is a library for building user interfaces.
Always write clean code.
Use npm.
Use pnpm for installing dependencies.
Always add tests for everything.
Do not modify tests.
Use Prisma for all database access.
Never add dependencies.
Current task: fix the login modal.
Use 2 spaces.
Never modify generated files.
Run tests before finishing.
How many problems can you find?
Diagnosis
❌ Generic knowledge
React is a library for building user interfaces.
Remove it.
❌ Vague instruction
Always write clean code.
Replace it with actual project conventions.
❌ Contradiction
Use npm.
Use pnpm.
Choose the correct package manager.
❌ Testing conflict
Always add tests for everything.
Do not modify tests.
Define the real testing policy.
❓ Possibly incorrect architecture
Use Prisma for all database access.
Verify that the project actually uses Prisma.
❌ Excessive restriction
Never add dependencies.
State the actual dependency policy instead.
❌ Temporary task
Current task: fix the login modal.
Put this in the task prompt.
❌ Better handled by tooling
Use 2 spaces.
Prefer formatter configuration.
⚠️ Incomplete boundary
Never modify generated files.
Explain how they should be regenerated.
A Better Version
After cleanup:
# Project Guidelines
## Development
- Use `pnpm` for dependency management.
## Architecture
- Follow the existing database-access pattern in `src/server/db`.
## Testing
- Add tests for new business logic.
- Add regression tests for bug fixes.
## Generated Code
- Do not manually edit files inside `src/generated`.
- Run `pnpm generate` when generated code needs to change.
## Validation
Before completing application changes:
- Run `pnpm lint`.
- Run `pnpm test`.
The file is shorter.
But the instructions are stronger.
18. Debugging Unexpected Agent Behavior
Suppose the agent repeatedly does something you don't want.
Your first reaction might be:
Add another instruction!
Don't immediately do that.
First investigate.
Step 1 — Check existing instructions
Is there already a relevant rule?
Step 2 — Check for conflicts
Does another instruction say something different?
Step 3 — Check scope
Is the instruction actually applicable to the code being changed?
Step 4 — Check clarity
Is the rule actionable?
❌ Follow our testing standards.
versus:
✅ Add Vitest unit tests for new service-layer business logic.
Step 5 — Check the repository
Does the existing code contradict the instruction?
Agents also learn from the code they're modifying.
Step 6 — Check whether AGENTS.md is the right mechanism
Maybe the requirement should actually be:
ESLint rule
Formatter configuration
TypeScript setting
Test
CI check
Skill
Task prompt
Don't solve every problem by making AGENTS.md longer.
19. The "Add Another Rule" Trap
Imagine an agent makes mistake A.
You add rule A.
Then mistake B.
You add rule B.
Then mistake C.
You add rule C.
Eventually:
Agent mistake
↓
Add instruction
↓
Another mistake
↓
Add instruction
↓
Another mistake
↓
500-line AGENTS.md
Instead, periodically ask:
Are these individual mistakes actually symptoms of one missing principle, workflow, test, or automated check?
Sometimes one strong rule can replace ten patches.
20. Refactoring AGENTS.md
Just like code, instruction files benefit from refactoring.
Periodically:
Remove stale rules
↓
Merge duplicates
↓
Resolve contradictions
↓
Move scoped rules
↓
Replace vague rules
↓
Move mechanical rules to tooling
↓
Keep the useful core
Don't measure quality by line count.
Measure it by how clearly the file communicates the repository's working expectations.
Debugging Checklist
When an instruction setup isn't working well, check:
- Is the instruction correct?
- Is it still current?
- Is it specific?
- Is it actionable?
- Is it in the correct scope?
- Is it duplicated?
- Does another rule contradict it?
- Does the repository itself contradict it?
- Is the rule unnecessarily restrictive?
- Could tooling enforce it better?
- Is
AGENTS.mdeven the right mechanism?
Key Takeaway
Most AGENTS.md problems come from instruction quality and maintenance, not Markdown syntax.
Watch for:
Vague rules
Duplicates
Contradictions
Wrong scope
Stale instructions
Excessive restrictions
Too much context
Wrong mechanism
And when an agent behaves unexpectedly, don't automatically add another rule.
First ask:
Is the existing instruction system clear, consistent, correctly scoped, and actually aligned with the repository?
A smaller, coherent AGENTS.md is usually more useful than a large collection of defensive instructions.
Up Next
Real-World AGENTS.md Patterns
We've spent seven lessons learning the principles.
Now we'll put them together.
Next we'll build realistic AGENTS.md examples for a Next.js application, Node.js API, monorepo, shared package, testing-heavy project, and other common development environments.