Two AGENTS.md Rules Stop AI From Writing Page Manuals and Patching Bugs
These two rules give development teams a cheap way to encode UI and bug-fix quality bars into AI agents, cutting down on the back-and-forth of deleting AI-generated bloat and re-explaining why a setTimeout is not a fix.
AI coding tools often over-explain interfaces: a form gets placeholder-ish instructions next to every field, repeating what labels and buttons already say. They also tend to fix bugs by adding workarounds, such as a 500ms setTimeout after a save call, without checking whether the call actually returns a Promise. Two short rules, originally shared by @luinlee, address both failure modes directly when added to a project's AGENTS.md file.
First: 'Avoid unnecessary secondary labels and descriptions. Let the layout do the explaining.' The guidance walks through a profile form, showing how to strip away redundant text and keep only information that affects user decisions, like character limits or public-visibility warnings. It also warns against deleting field labels entirely in favor of placeholders, since placeholders disappear once typing starts.
Second: 'Fix a bug at its cause, reasoning from first principles and established best practice. Do not patch over the symptom.' The same form's save/refresh list issue shows that a missing return in an async function causes the UI to refresh before the save completes; the fix is a one-line return, not a delay. The guidance stresses finding evidence of the actual failure point instead of guessing.
Adding these two rules to AGENTS.md is quick, but they're not a guarantee. You still need to verify each request, and it suggests using recent forms and bugs to test how much redundant text disappears and how many unexplained patches remain.
Terse rules like these are easy to paste into AGENTS.md, but their real value depends on the agent's ability to interpret 'unnecessary' and 'symptom' correctly; a naive agent may still need human judgment.
The setTimeout bug fix is a clean example of how AI prioritizes quick visual confirmation over understanding the underlying async contract; forcing a return statement is a one-line fix with clear semantics.
Encouraging layouts to explain themselves is a shift from adding more copy to reducing copy through better design; it's a principle that applies to human UX writing as well.
Skepticism persists about whether two short rules can change how AI models reason, since the models may not actually grasp the substance behind the wording. A practical solution extends the root-cause rule with a delivery requirement: the agent must state the root cause and verification method, and review compares that against the diff to catch superficial fixes. In practice, the rule appears to pay off on personal or independent projects.
AI still can't understand, right? Does writing words that require understanding instead of explanatory language actually bring a fundamental improvement?
For personal development projects it's obvious, you can try it.
And especially for independent developers, it's very necessary.
We also have a similar rule in our team's rules file for the second sentence: after fixing, confirm that the root cause is resolved, not just the symptom disappearing. Just writing this sentence alone, the model can easily verbally agree but still add a setTimeout; you can pair it with a delivery requirement: have it write in the delivery notes what the root cause is and how to verify, and have review compare against the diff—if the root cause isn't clearly written, treat it as not yet fixed.
Okay, I'll try it, learned something [thumbs up]