用 Agent 写页面，有一种返工特别烦：功能基本对了，页面上却多了一堆你没让它写的东西。
邮箱输入框下面写着“请在此输入您的邮箱地址”，保存按钮旁边写着“点击后将保存当前信息”，表单上方再来一句“请按照要求填写以下内容”。你在需求里交代的填写要求、校验逻辑，甚至开发注意事项，也被它当成文案摆上了页面。
最后还得补一句：“把这些多余的说明删掉。”
最近看到 X 上的 @luinlee 分享了一句提示词，专门约束这个问题。他在同一条讨论里还补充了另一句，用来约束 AI 修 Bug 时爱打补丁的习惯。两句都很短，适合放进项目的 AGENTS.md。讨论镜像
下面用两个开发场景，聊聊怎么把它们用起来。案例是为解释规则设计的示例，效果还要在自己的项目里验证。
01 别让 AI 把页面写成说明书
第一句原文是：
Avoid unnecessary secondary labels and descriptions. Let the layout do the explaining.
翻译过来：避免不必要的次级标签和描述，让布局本身解释界面。
重点在 unnecessary，也就是“不必要”。
比如让 AI 写一个个人资料表单，它可能交付这样的内容：
个人资料
在这里管理您的个人资料信息
昵称 [请输入昵称 ]
请在上方输入您想使用的昵称
邮箱 [请输入邮箱 ]
请填写有效的邮箱地址，系统会校验邮箱格式
[保存修改]
点击按钮保存您刚才修改的个人资料
这些句子单独看，都没什么语病。堆在一起，页面就显得啰嗦：标题、字段名、按钮已经表达过的信息，又被解释了一遍。
先做一轮删减：
个人资料
昵称 [ ]
邮箱 [ ]
[保存修改]
这时再检查：用户有没有缺少真正必要的信息？如果昵称只能填 2～20 个字符，输入前就该让用户知道；邮箱格式不对，报错时要告诉用户怎么改。涉及费用、公开范围、不可撤销操作的信息，更不能为了简洁而藏起来。
可以用一个很实用的判断标准：这句话能帮助用户做决定、避免出错，还是只在重复眼前的控件？
| 原来的文字 | 更合适的处理 |
|---|---|
| “点击保存按钮保存修改” | 删除，按钮名称已表达用途 |
| “系统会校验邮箱格式” | 实现校验，出错时给具体反馈 |
| “昵称长度为 2～20 个字符” | 保留，用户填写前需要知道 |
| “保存后昵称将对所有人公开” | 保留，影响用户决策 |
这里还有个容易踩的坑：别把字段标签一起删了，只剩 placeholder。 用户开始输入后，placeholder 就消失了；必要的控件名称和可访问名称都要保留。
“让布局解释界面”，可以落实到字段分组、清楚的按钮名称、合理的间距和信息层级上。如果一个表单必须靠半屏文字才能说明白怎么填，先看看表单结构是否需要调整。
02 修 Bug，别急着再贴一层补丁
第二句原文是：
Fix a bug at its cause, reasoning from first principles and established best practice. Do not patch over the symptom
意思是：结合第一性原理和成熟实践，从根因修复 Bug，避免只遮住表面症状。
继续看刚才的资料表单。现在出现一个问题：点击保存后，列表偶尔还显示旧昵称。
你让 AI 修，它可能先加一个延时：
await saveProfile(values);
setTimeout(() => refreshList(), 500);
本地一试，好像好了。但为什么是 500 毫秒？网络慢一点还管用吗？
如果真正的问题是 saveProfile 没有返回请求的 Promise，那么外面的 await 根本没有等到保存结束：
// 问题：请求发出去了，调用方却等不到它完成。
function saveProfile(values) {
api.updateProfile(values);
}
在这个假设下，修复点就在异步调用链：
function saveProfile(values) {
return api.updateProfile(values);
}
await saveProfile(values);
await refreshList();
这样才能表达正确的执行顺序：保存成功，再刷新列表；保存失败，交给错误处理流程。
当然，真实项目也可能是缓存没有失效、旧请求覆盖了新请求，或者后端数据存在可见性延迟。要先找到证据，再选择对应的修复。 不能看到“不更新”就认定一定是少了一个 return。
这里的“第一性原理”不需要讲得很玄。落到这次问题上，就是问清楚：数据在哪里保存？谁在等待它？列表读的是什么数据？哪一步偏离了预期？
同样，也别把这条规则理解成“发现 Bug 就重构整个模块”。修根因的改动可能只有一行。好的修复应当让原来的失败场景通过，并且有证据说明为什么有效。
03 直接复制进 AGENTS.md
AGENTS.md 用来给编码 Agent 提供项目上下文和工作约定。已有这个文件，就把下面的内容合并进去；工具如何发现、读取规则，要按各自的支持方式确认。格式说明
把 luinlee 分享的两句原文放进去就可以：
## 界面文案
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 的那几句话，逐步沉淀成项目自己的工作规则。
常见问题 FAQ
AGENTS.md 是什么，应该放在哪里？
AGENTS.md 是写给编码 Agent 的 Markdown 项目说明文件，可以记录开发约定、构建命令和测试要求。通常先放在项目根目录；如果子项目需要不同规则，再按工具支持情况添加子目录规则。已有文件时，把本文两句提示词合并进去即可，不要覆盖原有的项目约定。格式与用法
这两条 AGENTS.md 提示词是谁分享的？
两句英文都来自 @luinlee：减少次级标签和描述的规则出现在主帖，从根因修 Bug 的规则出现在他自己的回复中。本文的中文解释、表单示例和异步代码示例是围绕这两句原文展开的说明。文末可复制模板只保留两句英文规则，中文小标题用于分组。讨论镜像
如何避免 AI 把填写要求、校验逻辑变成界面废话？
在 Agent 实际读取的项目规则文件中加入第一句提示词，并在检查页面时区分“用户需要知道的信息”和“开发实现细节”。删除重复解释按钮、标题和字段的句子；校验逻辑落实到交互中，必要的输入限制提前告知，错误发生时给出具体反馈。
减少 UI 文案，会不会把必要提示也删掉？
有这个风险，所以应当保留字段标签、可访问名称、必要的格式要求，以及费用、公开范围和不可撤销操作等影响决策的信息。删减标准是文字是否重复、是否帮助用户完成操作，不能只追求字数少，也不要用 placeholder 替代必要标签。
怎样判断 AI 是从根因修 Bug，还是只加了补丁？
看它能否说明原来的失败条件、问题产生的位置，以及修改为什么能解决问题，再用原来的失败场景验证。无依据地加延时、吞掉错误或堆特殊分支，都值得追问原因；但重试、兜底本身也可能是合理设计，要结合实际故障机制判断。
写进 AGENTS.md 后，所有 AI 编程工具都会自动生效吗？
不能一概而论。不同工具对规则文件的发现、读取和优先级处理有所区别，部分工具需要配置才能读取 AGENTS.md。先确认当前工具支持并加载了该文件，再检查实际输出是否遵守规则。提示词能表达项目要求，不能代替代码审查、功能验证和回归测试。格式说明与配置示例
如果还想整理完整的项目约定，可以接着看AGENTS.md 项目规则编写指南。这篇先从两条短规则开始，用一个页面和一次 Bug 修复检验它们是否帮你减少了返工。