AI Writes Pages Like Manuals and Patches Bugs Like Band-Aids? Put These Two Sentences in AGENTS.md

Author: ikoala

Tags: Frontend, JavaScript, AI Programming

Using an agent to write pages brings an annoying rework: the functionality is mostly right, but the page ends up with a bunch of stuff you never asked for.

Below the email input it writes "please enter your email address here", next to the save button it says "click to save the current information", and above the form it adds "please fill in the following as required". The filling requirements, validation logic, and even development notes you put in the spec get turned into copy on the page.

You end up having to add: "Remove these redundant descriptions."

This article is also published on AI Coding Guide.

Regarding Codex membership, I often purchase from chong-zhen.com.

Recently I saw a prompt shared by @luinlee on X that specifically constrains this issue. In the same thread, he added another one to curb the AI's habit of patching bugs. Both are short and fit well in a project's AGENTS.md. Mirror thread

Below I use two development scenarios to talk about how to apply them. The cases are examples designed to explain the rules; you'll need to verify the effect in your own projects.

01 Don't Let AI Turn Pages into Instruction Manuals

The first sentence is:

Avoid unnecessary secondary labels and descriptions. Let the layout do the explaining.

Translated: Avoid unnecessary secondary labels and descriptions. Let the layout explain the interface itself.

The key is unnecessary.

For example, ask AI to write a profile form, and it might deliver something like:

Profile
Manage your profile information here

Nickname [Enter nickname       ]
Please enter the nickname you want to use above

Email [Enter email       ]
Please enter a valid email address; the system will validate the format

[Save Changes]
Click the button to save the profile changes you just made

Each sentence alone is grammatically fine. Stacked together, the page becomes wordy: the title, field names, and button already communicate the information, yet it's explained again.

Do a round of trimming:

Profile

Nickname [                 ]
Email [                 ]

[Save Changes]

Then check again: is the user missing any truly necessary information? If the nickname is limited to 2-20 characters, the user should know before typing; if the email format is wrong, the error should tell the user how to fix it. Information about cost, public visibility, or irreversible actions must not be hidden for the sake of brevity.

Use a practical criterion: does this sentence help the user make a decision or avoid errors, or is it only repeating the control in front of them?

Original text	Better handling
"Click save button to save changes"	Remove; button name already conveys the purpose
"The system will validate email format"	Implement validation and give specific feedback on error
"Nickname must be 2-20 characters"	Keep; user needs to know before filling
"After saving, the nickname will be public to everyone"	Keep; affects user decision

There's also a common pitfall: don't delete the field labels along with it, leaving only placeholders. Once the user starts typing, the placeholder disappears; keep the necessary control names and accessible names.

"Let the layout explain the interface" can be realized through field grouping, clear button names, reasonable spacing, and information hierarchy. If a form requires half a screen of text to explain how to fill it, look at whether the form structure needs adjustment.

02 Fix Bugs, Don't Just Slap on Another Patch

The second sentence is:

Fix a bug at its cause, reasoning from first principles and established best practice. Do not patch over the symptom

Meaning: Fix the bug at its root cause, reasoning from first principles and established best practices. Don't just cover up the surface symptom.

Continuing with the profile form. Now there's an issue: after clicking save, the list sometimes still shows the old nickname.

You ask AI to fix it, and it might first add a delay:

await saveProfile(values);
setTimeout(() => refreshList(), 500);

It seems to work locally. But why 500 milliseconds? Will it still work if the network is slower?

If the real issue is that saveProfile doesn't return the request's Promise, then the outer await never actually waits for the save to finish:

// Problem: the request is sent, but the caller can't wait for it to finish.
function saveProfile(values) {
  api.updateProfile(values);
}

Under this assumption, the fix is in the async call chain:

function saveProfile(values) {
  return api.updateProfile(values);
}

await saveProfile(values);
await refreshList();

This expresses the correct order: save successfully, then refresh the list; if save fails, it goes to the error handling flow.

Of course, the real project could also have cache not invalidated, an old request overwriting a new one, or backend data visibility delays. Find evidence first, then choose the corresponding fix. Don't conclude "not updating" means a missing return.

"First principles" doesn't need to be mystical. Applied to this issue, ask: where is the data saved? Who is waiting for it? What data does the list read? Which step deviates from expectation?

Also, don't interpret this rule as "refactor the whole module when you find a bug." The root-cause fix might be just one line. A good fix should make the original failing scenario pass and have evidence explaining why it works.

03 Copy Directly into AGENTS.md

AGENTS.md provides project context and working conventions to coding agents. If you already have this file, merge the following content into it; how tools discover and read the rules depends on each tool's support. Format description

Just put the two original sentences shared by luinlee in:

## UI Copy

Avoid unnecessary secondary labels and descriptions. Let the layout do the explaining.

## Bug Fixing

Fix a bug at its cause, reasoning from first principles and established best practice. Do not patch over the symptom

These two rules articulate the preference clearly, but writing them into the file doesn't guarantee they'll be followed every time. Next time you ask AI to change the page, have it also check "which explanations repeat the controls"; when fixing a bug, ask it to explain "where the problem originated and why the change works".

You can try with a recent form and a bug: see how much redundant copy you can remove, and whether the fix has unexplained delays, fallbacks, or special branches. Gradually distill the phrases you repeatedly remind AI about into your project's own working rules.

---

I also have some AI Coding (SDD Agent AI tools, etc.) and Node.js communication groups. If you're interested, add WeChat ikoala520 to join, and learn and progress together.

This article is also published on AI Coding Guide.