ARTICLE · 1360215
我把团队的规矩从文档搬进工具链,才知道写在文档里等于没写
我把团队的规矩从文档搬进工具链,才知道写在文档里等于没写
上周AI帮我改一段代码,它把一条我们团队最看重的规矩又犯了一次。
那条规矩就写在我们规范文档的第4页,标题加粗,还贴了链接:《任何删除类操作必须二次确认》。
文档没人看,链接没人点,但它每次都忘。
那次之后我做了个决定,花三周把我们12页的规范文档砍到2页。不是删内容,是把内容换个地方放。
换完之后,同样的AI再改代码,没有再犯过。
这篇讲我具体怎么搬的,以及搬的过程中撞到的几件事。
(下面写的分类方式、字段改造和三步做法来自我自己团队半年的实践,属个人实践口径,不是行业标准,落地前请按自家情况评估。)
一、写在文档里的规矩是概率执行,挂在工具链上的规矩是确定执行
我以前以为,规范文档写得越细,执行得越好。
后来发现不对。文档里的规矩,全靠人记得住、记得起、看得到、愿意照做。这四样少一样,规矩就漏。
而工具链里的规矩不靠人。它是机器在提交的那一刻检查,不合规则直接拦下。
我把这两种约束分成了两层,后来这套分法帮我省了大量返工。
上面那层是生成时的引导。往正确的方向偏一偏,比如提醒它用哪种写法、别写哪种坑。这层有用,但它漏了没人知道,也没人统计。
下面那层是确定性的拦截。跑偏了必被拦下,拦下还要能说出违反了哪一条。
我给自己定了一条判断标准,很土但很管用:这条规矩有没有一个能自动拦住它的检查点?没有,就说明它还只是一句愿望。
我们文档里有87条要求。搬完之后,真正变成自动检查项的有31条,剩下56条里有一部分变成了「例外怎么申请」,还有一部分被我直接删了。
二、第一层改造:把「对」和「错」两个字,换成一串有编号的选项

我们系统里有不少接口,出错时只回一个「失败」标记。前端拿到这个标记,一律渲染成红色错误条。
问题就出在「一律」两个字上。
有一次门店那边反馈,系统弹出一片红色,大家以为整个系统挂了,赶紧刷新,结果正在填的未提交内容全没了。
而那次其实只是一次可重试的限流。语义上它根本不是「必须抢救」的错。
根因不在前端表达能力不够,是接口定义的时候,把「多严重」这个维度整个压没了。它只给了一个是非题,答案落到前端,就只剩「红」这一种表达。
我做的改造很小:把这个失败标记从是非题改成一道选择题,可重试、需人工处理、已终止,三档。前端按档位映射渲染,可重试那档用黄色加倒计时,告诉用户等一会儿会自动重试。
改完之后,这类误报少了一大半。
顺带一个意外收获:改字段那天,编译环境就拦下了两处旧代码,因为有人嫌麻烦把类型悄悄改回了是非题。这个错在我改之前一直藏着,谁都没发现。
这就是机器校验和人工检查的差别。人工检查要靠细心和运气,机器校验只需要规则本身是对的。
三、第二层改造:同一个按钮,换个场景就得换一套规则
我们系统里有个提示组件。系统出故障的时候,它是一个挡在最前面的红色警示条;新功能上线通知的时候,它是一条普通信息条。
同一个东西,两种完全不同的分量。可这种差异过去只写在设计稿的标注里,写在文档里,写在某个人的脑子里。
人看不见,它就不存在。
我把它改成:不同场景对应不同的类型。故障场景只允许接故障那一类参数,通知场景只允许接通知那一类参数。编译器会直接报错。
它报错的时候长这样:跨越了不允许的语义绑定,指出了错在哪个组件、哪个属性。
我觉得这条比拦下错误本身更有价值。以前我们评审时经常吵「这里用红色更有警示效果」,吵到最后看谁嗓门大。现在这个争论有了一个能引用的依据:违反了哪条绑定,在哪一行。
这件事我印象很深,是因为我们真踩过。
我拿一个推演的例子说明。假设某个后台管理系统里有个「批量删除用户」的按钮,被当成页面里的普通操作来声明。结果是AI生成的代码里,这个按钮是个蓝色实心按钮,没有二次确认。用户误触,直接批量删掉了数据。
这类错误最讨厌的地方在于,它在人眼里完全不像错误。代码写得干干净净,测试环境也不一定碰得到。
所以这一层我要守的纪律只有一条:按场景选类型,不按视觉选组件。
四、第三层改造:提交的时候拦一次,而且拦截报告必须能追到具体行

前两层是「写对」,第三层是「写错之后怎么办」。
我们一开始的检查工具,报错就一句话:语义校验失败。
这句话有个要命的问题,它不告诉你哪错了。你得自己一个个文件翻,一个下午过去,才找到那行把档位写成了近义词的地方。
我把拦截报告改成必须带三样东西:违反了哪一条规则的哪一款、错在哪个文件的哪一行、按什么改。
这三样凑齐,报告才是有用的。少了「按什么改」,它就只是在说「你错了」。
现在的效果是这样的:AI 生成一段代码,提交的时候被拦下,报错里直接给出文件名、行号、错值和应该填的那个值。改都不用改,直接搜。
我们团队现在每天大概拦下十几次,绝大部分是AI自己写错的,不是人写错的。
五、机器没见过的时候,人的动作是上报,不是就地发明
改造过程中撞到过一个问题。
我们的状态里有一档是「需人工处理」,但业务上冒出来一个「资金冻结」的情况,四档里没有对应的选项。
最先想到的办法是,让AI自己造一个叫「已冻结」的值。它也确实造得出来,跑得也通。
但我把这个方案否了。
因为这个值一旦就地生出来,就没人知道它是临时的还是正式的,也没人评审过它意味着什么。后面每个碰到它的人,都会以为这是系统本来就有的规则。
机器没见过的时候,人的动作是上报,不是就地立法。
我们最后走的是一条反馈流程:业务发现没有对应选项,提交一条反馈,写清楚场景和现在用的是哪个兜底值,然后回到评审,由人决定是复用某一档、临时降级,还是新增一档。
整个过程慢,但链路是干净的。这半年新增了三档,全部有据可查。
六、两种载体要分工,别把手写散文当成约束落地
有件事我一开始搞反了。
我以为把所有规矩都写成检查项就行了。后来发现不行,检查项只管「能不能」,不管「好不好」。
比方说,命名规范里有些词是强烈不建议用的,检查项能拦住硬性违规,但拦不住「读起来别扭」。
所以我们最后把文档重新分成了两半。
文档里只留两类内容:为什么会有这条规矩,以及例外怎么申请。
「必须怎样」那部分,全部变成机器检查项,文档里不再重复。
文档从12页变成2页,不是因为我们偷懒,是因为那10页的内容已经不在文档这个位置上了。它们变成了字段定义、类型声明和提交前的检查规则。
有一次我在团队会上说,规则只有两种活法:要么变成机器拦得住的检查项,要么变成一句没人拦得住的散文。两个都不选的,就是还没想清楚。
说完之后有人问我,那规矩到底该写在哪。
我的回答是:先问它能不能被检查,不能被检查的,再问它值不值得写进文档。两个都不行的,说明这根本不是一条规矩,是一句愿望。
七、这套东西真正的成本在上游
有件事我要提前说清楚,不然容易让人误解。
搬完之后,下游确实变轻松了。但上游变重了。
我们团队花三周做了三件事:把散在几个地方的字段定义合并核对了一遍,把组件按场景重新分了类,把检查规则一条一条落到提交前的流程里。
这三周没有任何新功能产出,全是「把已有的东西整理成机器能读的样子」。
而下游的收益是:提交被拦下的错误,二十个前端同学一个月里被机器拦下了六十几处,没有一处是我手工review出来的。
我越来越觉得,一套规则系统消费得越顺,说明上游做的东西越扎实。反过来,如果下游天天要问「这条到底什么意思」,那就是上游没整理干净。
有个反直觉的地方:真正的成本不在写检查项,在让人相信检查项是对的。规则本身写错了,机器只会更高效地做错事。所以我们每加一条检查项,都要人工评审一遍它的判断逻辑。
八、给自己留的三条
第一,每加一条要求,先问它能不能变成一个检查项。能,就别写进文档。
第二,拦截报告必须能追到具体行。追不到,这套机制就只是在制造摩擦。
第三,例外走清单,不放松规则。规则要改就在评审里改,不要在代码里绕过去。
我们把这三条写在办公室的 whiteboard 上,半年了没擦过。
(本文涉及的系统、字段与做法均来自我自己团队的实践,属个人实践口径,不代表行业通行标准;文中那个批量删除的例子是推演场景,用于说明机制,不是真实事故记录。)
你的团队文档里有没有那种「谁都知道但就是没人守」的规矩?评论区说说是哪一条,我挺想看看能不能也变成一个检查项。
觉得这篇有用的话,收藏一下,下次改规范的时候可以照着这三条走一遍。















































































