反例先摆出来。你要是跟 AI 说「请保持代码整洁」,它会把一个函数拆成八个,给每个加一段注释,再顺手补一个你永远用不上的抽象层。它不是变坏了,是「整洁」对它没有约束力——它不知道你在乎什么,只能按训练里见过的平均值猜。
能约束它的话长这样,都是这个仓库
---
所有 DML 必须走写队列:不需要返回结果的异步操作用
---
后半句是关键。没有「否则会触发库级写锁竞争」,前半句就是一条风格偏好,AI 会在某次「我这儿就一个 UPDATE,应该没事」的判断里悄悄绕过去,而它觉得自己是理性的。加上物理原因之后,绕过去等于无视一个事实,AI 一般不会这么干。
第二条:
---
页面模板里不许再写 `<svg>` 画界面图标——需要新图标就往片段
---
这条背后有一堆实测数字:全量符号塞进 sprite 会让首页 gzip 从 38,293 涨到 38,983,只留高频六个才降到 35,669。数字写进去,AI 才知道「少一枚图标是可以接受的代价」,而不是「用户体验缺失需要修复」。
第三条最像人话:
---
回帖框是 `textarea`,Enter 换行、Ctrl / ⌘ + Enter 发送,空内容时发送按钮置灰:它曾经是单行
---
为什么必须写「别为了」这三个字:改控件的时候 AI 最喜欢做体验优化,而「回车直接发送」在它的判断里是明确的进步——更快、更顺、更像成熟产品。它不知道这条是有人专门否决过的。你要是不写,它隔三差五就会帮你「进步」一次。
---
---
三条实操,都不复杂:
规则带版本号。写成
只写踩过的坑。假设性的「要注意安全」写进去,AI 会当成铁律照办,结果比没写更糟:它会为了一个从没发生过的风险,把你正常的功能改得别扭。
允许它变长。这份文件现在 586 行,我猜它还会涨。通读一遍的成本是十分钟,从头再踩一遍的成本是一周。这两件事不能等值比较。
#开发日志 #AI协作 #提示词
能约束它的话长这样,都是这个仓库
AGENTS.md 里的原文:---
所有 DML 必须走写队列:不需要返回结果的异步操作用
internal.EnqueueWrite;需要同步结果的用 EnqueueWriteWait;绝对禁止直接调用 db.Create/Update/Delete,否则会触发 SQLite 库级写锁竞争。---
后半句是关键。没有「否则会触发库级写锁竞争」,前半句就是一条风格偏好,AI 会在某次「我这儿就一个 UPDATE,应该没事」的判断里悄悄绕过去,而它觉得自己是理性的。加上物理原因之后,绕过去等于无视一个事实,AI 一般不会这么干。
第二条:
---
页面模板里不许再写 `<svg>` 画界面图标——需要新图标就往片段
if 链里加一条,path 必须取自 Heroicons 官方,不许自己描点;名字没命中时片段渲染空串,这是故意的,宁可少一枚也不画一个不是 Heroicons 的图形。---
这条背后有一堆实测数字:全量符号塞进 sprite 会让首页 gzip 从 38,293 涨到 38,983,只留高频六个才降到 35,669。数字写进去,AI 才知道「少一枚图标是可以接受的代价」,而不是「用户体验缺失需要修复」。
第三条最像人话:
---
回帖框是 `textarea`,Enter 换行、Ctrl / ⌘ + Enter 发送,空内容时发送按钮置灰:它曾经是单行
input(连换行都不支持),改成 textarea 是「回帖 = 主题帖」在控件形态上的对齐,别为了「按回车就能发」改回 input。---
为什么必须写「别为了」这三个字:改控件的时候 AI 最喜欢做体验优化,而「回车直接发送」在它的判断里是明确的进步——更快、更顺、更像成熟产品。它不知道这条是有人专门否决过的。你要是不写,它隔三差五就会帮你「进步」一次。
---
能直接粘的那段
改这个仓库之前,先完整读一遍AGENTS.md。里面每一条形如「必须 X / 不许 Y」的规则,后面那句「否则会 Z」都是真踩过的坑,不是风格偏好。不要用你更喜欢的方案去覆盖它。如果你确实认为某条该改,先告诉我它当初是为了解决什么问题,以及放弃那个收益的代价是什么,我们再决定。---
三条实操,都不复杂:
规则带版本号。写成
(v1.12.12) 那种。半年后你和一个新来的模型(或者一个新来的人)都需要知道这条规则是不是过期了——没版本号的规则,谁都不敢删,最后全部留着,文件变成考古现场。只写踩过的坑。假设性的「要注意安全」写进去,AI 会当成铁律照办,结果比没写更糟:它会为了一个从没发生过的风险,把你正常的功能改得别扭。
允许它变长。这份文件现在 586 行,我猜它还会涨。通读一遍的成本是十分钟,从头再踩一遍的成本是一周。这两件事不能等值比较。
#开发日志 #AI协作 #提示词