AI 写页面像说明书，修 Bug 像贴膏药？把这两句话写进 AGENTS.md

用 Agent 写页面，有一种返工特别烦：功能基本对了，页面上却多了一堆你没让它写的东西。

邮箱输入框下面写着"请在此输入您的邮箱地址"，保存按钮旁边写着"点击后将保存当前信息"，表单上方再来一句"请按照要求填写以下内容"。你在需求里交代的填写要求、校验逻辑，甚至开发注意事项，也被它当成文案摆上了页面。

最后还得补一句："把这些多余的说明删掉。"

本文同步发布于 AI Coding 指北。

关于 Codex 会员，我经常去chong-zhen.com这家购买

最近看到 X 上的 @luinlee 分享了一句提示词，专门约束这个问题。他在同一条讨论里还补充了另一句，用来约束 AI 修 Bug 时爱打补丁的习惯。两句都很短，适合放进项目的 AGENTS.md。讨论镜像

下面用两个开发场景，聊聊怎么把它们用起来。案例是为解释规则设计的示例，效果还要在自己的项目里验证。

01 别让 AI 把页面写成说明书

第一句原文是：

text 复制代码

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

翻译过来：避免不必要的次级标签和描述，让布局本身解释界面。

重点在 unnecessary，也就是"不必要"。

比如让 AI 写一个个人资料表单，它可能交付这样的内容：

text 复制代码

个人资料
在这里管理您的个人资料信息

昵称 [请输入昵称       ]
请在上方输入您想使用的昵称

邮箱 [请输入邮箱       ]
请填写有效的邮箱地址，系统会校验邮箱格式

[保存修改]
点击按钮保存您刚才修改的个人资料

这些句子单独看，都没什么语病。堆在一起，页面就显得啰嗦：标题、字段名、按钮已经表达过的信息，又被解释了一遍。

先做一轮删减：

text 复制代码

个人资料

昵称 [                 ]
邮箱 [                 ]

[保存修改]

这时再检查：用户有没有缺少真正必要的信息？如果昵称只能填 2～20 个字符，输入前就该让用户知道；邮箱格式不对，报错时要告诉用户怎么改。涉及费用、公开范围、不可撤销操作的信息，更不能为了简洁而藏起来。

可以用一个很实用的判断标准：这句话能帮助用户做决定、避免出错，还是只在重复眼前的控件？

原来的文字	更合适的处理
"点击保存按钮保存修改"	删除，按钮名称已表达用途
"系统会校验邮箱格式"	实现校验，出错时给具体反馈
"昵称长度为 2～20 个字符"	保留，用户填写前需要知道
"保存后昵称将对所有人公开"	保留，影响用户决策

这里还有个容易踩的坑：别把字段标签一起删了，只剩 placeholder。 用户开始输入后，placeholder 就消失了；必要的控件名称和可访问名称都要保留。

"让布局解释界面"，可以落实到字段分组、清楚的按钮名称、合理的间距和信息层级上。如果一个表单必须靠半屏文字才能说明白怎么填，先看看表单结构是否需要调整。

02 修 Bug，别急着再贴一层补丁

第二句原文是：

text 复制代码

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

意思是：结合第一性原理和成熟实践，从根因修复 Bug，避免只遮住表面症状。

继续看刚才的资料表单。现在出现一个问题：点击保存后，列表偶尔还显示旧昵称。

你让 AI 修，它可能先加一个延时：

js 复制代码

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

本地一试，好像好了。但为什么是 500 毫秒？网络慢一点还管用吗？

如果真正的问题是 saveProfile 没有返回请求的 Promise，那么外面的 await 根本没有等到保存结束：

js 复制代码

// 问题：请求发出去了，调用方却等不到它完成。
function saveProfile(values) {
  api.updateProfile(values);
}

在这个假设下，修复点就在异步调用链：

js 复制代码

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

await saveProfile(values);
await refreshList();

这样才能表达正确的执行顺序：保存成功，再刷新列表；保存失败，交给错误处理流程。

当然，真实项目也可能是缓存没有失效、旧请求覆盖了新请求，或者后端数据存在可见性延迟。要先找到证据，再选择对应的修复。 不能看到"不更新"就认定一定是少了一个 return。

这里的"第一性原理"不需要讲得很玄。落到这次问题上，就是问清楚：数据在哪里保存？谁在等待它？列表读的是什么数据？哪一步偏离了预期？

同样，也别把这条规则理解成"发现 Bug 就重构整个模块"。修根因的改动可能只有一行。好的修复应当让原来的失败场景通过，并且有证据说明为什么有效。

03 直接复制进 AGENTS.md

AGENTS.md 用来给编码 Agent 提供项目上下文和工作约定。已有这个文件，就把下面的内容合并进去；工具如何发现、读取规则，要按各自的支持方式确认。格式说明

把 luinlee 分享的两句原文放进去就可以：

markdown 复制代码

## 界面文案

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

## Bug 修复

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

这两条规则能把偏好说清楚，但写进文件并不代表每次都会执行到位。下一次让 AI 改页面时，可以让它顺手检查"哪些说明在重复控件"；修 Bug 时，让它交代"问题在哪产生，改动为什么有效"。

你也可以拿最近一个表单和一个 Bug 试试：看看能删掉多少重复文案，修复里有没有解释不清的延时、兜底和特殊分支。把反复提醒 AI 的那几句话，逐步沉淀成项目自己的工作规则。

我这边也有一些AI Coding（SDD Agent AI工具等）和 Node技术交流交流群，感兴趣的可以加微信 ikoala520 进群，一起学习，共同进步。

本文同步发布于 AI Coding 指北。