What's Actually in My AGENTS.md

Short summary

Instruction files (like AGENTS.md) work best when they give agents explicit permission to stop and ask clarifying questions instead of confidently solving the wrong problem. Name specific bad instincts—over-building, over-reaching, pattern averaging—and forbid them. Most critically, separate guidance (soft prose preferences) from hard requirements (enforce via CI/hooks/scripts). Instructions are suggestions; real guarantees need enforcement mechanisms.

• •Permission to stop and ask is more valuable than style guidance—fighting the default to confident silence on ambiguous requests
• •Name specific bad instincts (over-building, over-reaching, pattern averaging) and forbid them explicitly
• •Hard requirements belong in enforcement mechanisms (CI/hooks/scripts), not prose—instructions are suggestions, guarantees need gates

Generated with AI, which can make mistakes.