给Codex戴上紧箍,治一治AI过度发挥

作者:技术拾光时间:2026-06-03 13:53:02浏览:449

AI写代码常出现过度兼容、重构和抽象等问题,导致代码膨胀和技术债务。通过项目级规则文件如codex-dev-norms,为Codex设定明确边界,强调最小改动、严格接口字段、控制抽象和编码规范,避免过度发挥,确保代码可控与可维护。

在使用 Codex 编写代码的过程中,不少开发者逐渐发现一个典型问题:

给Codex戴上紧箍,治一治AI过度发挥

AI 并非不会写代码,而是“太过擅长”导致频繁超出预期。

当你让它修改一个接口字段,它可能自动补上兼容逻辑:

const title = data.title || data.name || data.label || data.displayName || ''

当你让它修正一个按钮文案,它可能顺手重构半个组件。

当你要求加上 loading 状态,它可能会抽离 hook、拆分 utils、添加类型、优化结构,最后还贴心地告诉你:“这样更具可维护性。”

这种情景,相信很多人已多次经历。

好比请朋友来家里换灯泡,他却观察天花板后说:“你的采光系统有问题,我帮你重新设计电路。”

谢谢,但我只需要让灯亮起来。

于是,为 Codex 制定一套开发规则——例如 codex-dev-norms 这类 skill——便成为很自然的选择。目标不是降低 AI 的能力,而是让 AI 在写代码前先理解一件事:

并非所有能写的代码,都应该被写出。

一、背景:AI 写代码的常见“热心事故”

在 AI 开发中,存在一个典型问题:AI 经常“补过头”。

人类工程师写代码时,会携带项目上下文、团队约定、业务边界,以及过往线上事故带来的谨慎。

AI 则不同。它擅长从已有模式中推断下一步,也善于把“不确定”补成“看起来合理”。这在许多场景中很有用,但在业务代码里,它也可能制造出令人熟悉的事故现场。

1. 过度兼容

比如接口文档明确返回 title,AI 可能猜测后端也许会返回 name,历史数据或许有 label,为保险再兼容 displayName。

于是代码变成:

const title = item.title || item.name || item.label || item.displayName

看起来稳妥,实则暗藏风险。

它将明确的接口契约变成了字段猜谜游戏。今天兼容四个字段,明天再来一个 text,后天补一个 caption,最后谁也不清楚真实数据的标准格式。代码逐渐变得像在相亲——谁来都能临时接一下。

2. 过度重构

你只想修复一个 bug,AI 却觉得附近代码不够优雅。

“这个函数可以抽离。” “这个组件可以拆分。” “这个命名可以统一。” “这个结构可以更通用。”

在学习项目中,这或许令人欣喜。但在真实业务里,这种“顺手优化”常引发范围失控。一个小改动突然牵连多个文件,原本只需验证一个按钮,现在却要确认半个页面是否存在回归问题。AI 很积极,但 Code Review 的人开始沉默。

3. 过度抽象

AI 看到重复代码,容易触发封装欲望。两处都有某个状态判断?抽离。两个组件 class 类似?抽离。两个类型字段相近?合并。

然而工程中的重复并非总是坏事。有些重复只是外形相似,业务含义却不相同;有些代码当前重复,未来变化方向可能完全不同。强行抽象之后,项目可能从“有一些重复”升级为“没人敢动”。

4. 忽略编码和中文环境

中文项目还有一个经典问题:编码。尤其在 Windows 环境下,如果读写文件时未确认 UTF-8、GBK、ANSI,轻则中文变乱码,重则打开文件时仿佛看到项目在使用另一种文明与你交流。

有些 AI 还会将中文写成一串 Unicode 转义字符。虽然可能正常运行,但人类阅读时会很想下班。

5. 缺少“改动边界感”

归根结底,许多问题不在于 AI 不懂代码,而在于它不知道边界。它不清楚哪些文件不能动,哪些字段不能猜,哪些重复可以保留,哪些项目当前需要的是“修复”而非“翻新”。

因此,我们需要一套规则,让 AI 在行动前就收到明确提醒:做需要做的事,不要做看起来也不错的事。

二、有哪些解决办法

针对 AI 过度发挥,常见解决方案有以下几种。

1. 靠人工 Code Review

这是最传统也最可靠的方式。AI 写完,人类审查。但问题是,AI 生成速度太快,一分钟可能产出大片代码,而人类需逐行确认:这个兼容是否必要、这次抽象是否有收益、这个字段是不是猜测、这个文件是否不该动。久而久之,Code Review 会从“质量保障”变成“AI 善后现场”。

2. 靠 Prompt 反复提醒

例如每次都告诉 AI:“只做最小改动。不要重构。不要猜接口字段。不要修改无关文件。”

这当然有效,但每次都需要重复。一旦忘记提醒,AI 就可能立刻恢复出厂设置,再次成为那个看到代码就想顺手优化的热心同事。

3. 靠项目级规则文件

如 AGENTS.md、CLAUDE.md 或 Codex skill。这种方式的好处在于将团队约定固化下来,无需每次靠人提醒,而是让 Codex 在工作时就能读到项目边界。哪些事可以做,哪些事不能做;何时需要查接口,何时必须保持最小改动;何时该加测试,何时不要为了覆盖率写废测试。

它相当于为 AI 配了一份“入职手册”。只不过这份手册的重点不是“欢迎加入”,而是“欢迎加入,但先别乱动”。

4. 靠技能化拆分规则

进一步,可将规则拆分为多个 reference。例如 API 有 API 的规则,前端有前端的规则,测试有测试的规则,Git 工作区有 Git 工作区的规则。这样 Codex 无需每次背诵整本规章制度,而是根据任务读取相关部分。修接口就看 API 规则,改组件就看前端规则,做 review 就看 review 规则。

这种方式更贴近真实工程协作:不是把 AI 当作万能文本生成器,而是当作需要遵守项目规范的开发者。

三、这个 skill 具体解决了哪些问题

codex-dev-norms 这套 skill 的核心价值,在于将 AI 常见的失控点拆解成明确的边界。它并非“代码洁癖清单”,而更像一份“防止 AI 过度热心说明书”。

下面按 reference 大致说明它管理了哪些事项。

1. code-change-boundary:先管住手,别乱改

这个 reference 主要强调最小改动原则。即:任务要求什么,就改什么;不要因为“更干净”“更通用”“更优雅”“更符合最佳实践”而扩大范围。

这一点非常关键。因为 AI 很容易将“解决问题”理解为“顺便把附近看不顺眼的地方都整理一下”。但真实项目中,很多时候我们需要的是可控的小变更,而非一次兴致勃勃的局部装修。这条规则会提醒 Codex:“你是来修这个 bug 的,不是来给项目重新投胎的。”

2. global-frontend:中文、编码、前端全局边界

这个 reference 管理全局前端开发规则,尤其是编码和中文字符处理。它要求在读写文件前确认编码,不要默认使用可能出问题的读取方式;中文要直接写中文,不要写 Unicode escape;如果发现乱码或混合编码,要先处理编码问题。

这对中文项目尤其重要。中文乱码并非普通 bug,更像一种仪式——一旦触发,项目里所有汉字都会开始怀疑自己的来源。

除了编码,它还强调不要修改无关代码、不要格式化无关内容、不要乱改结构、命名、props、CSS class 等。一句话:前端可以改,但不能趁机“大扫除”。

3. api-integration:别猜接口,按定义来

这个 reference 专门管理 API 接入。其核心态度明确:API 字段必须严格来自真实定义。不要猜测字段名、不要猜测响应结构、不要添加别名、不要写 a || b || c 这种自动兼容。如果字段不清楚,就去确认接口定义。

这正好命中 AI 的常见毛病:太喜欢替后端“考虑周全”。但在业务代码中,接口契约不是开放式作文。后端返回什么,前端就按什么接。否则所谓的兼容会慢慢变成技术债,最后谁也不知道哪个字段才是真实的。

4. backend-business-logic:业务逻辑别到处流浪

这个 reference 关注后端和业务逻辑边界。它强调业务规则应该待在真正属于它的位置,不要散落在 controller、service、job、mapper、serializer 各处。

这也是 AI 容易犯的错误:哪里需要判断,就在哪里补一段;哪里缺个转换,就在哪里加一个 helper。短期看问题解决,长期看业务规则开始到处流浪。以后要修改一个状态判断,可能需要在五个地方寻找它的分身。这条规则提醒 AI:业务逻辑不是贴纸,不能哪里空就贴哪里。

5. frontend-implementation:小组件别写成小宇宙

这个 reference 关注前端实现。它强调可读性优先,不要为了优化而引入复杂度;组件应小而聚焦;是否抽离 hook、utils,要看真实复杂度,而不是主观认为“这样更优雅”。

这对 AI 很有必要。因为 AI 很擅长将简单事情做得非常完整。一个本来只在当前组件中用到一次的逻辑,它可能抽成 hook;一个简单的 formatter,可能被塞进 utils;一个局部状态,可能被设计成可复用方案。看起来很专业,但专业不等于复杂。尤其前端代码,很多时候“放在这里一眼看懂”比“抽出去但要点击进去看”更优。

6. state-management-boundary:状态该归谁,就归谁

这个 reference 管理状态边界。它区分了组件状态、hook 状态、store 状态、URL query 状态和 server state。这能解决一个常见问题:AI 喜欢将状态放到“看起来更通用”的地方。

本来只属于一个组件的展开状态,被放进 store;本来应该体现在 URL 上的筛选条件,被藏在内部 state;本来属于服务端缓存的数据,被复制成多份本地状态。最终状态之间互相看不顺眼,页面刷新、返回、切换 tab 都可能出现奇怪行为。这条规则告诉 Codex:状态不是越全局越高级,放对地方才高级。

7. side-effects-and-subscriptions:副作用要有生命周期

这个 reference 管理事件监听、订阅、定时器、watcher 等副作用。它强调注册要清楚,清理要明确,生命周期要看得见。

AI 写副作用代码时,很容易只关心“让它生效”,而忘记“让它结束”。例如添加了 resize listener 却没有清理;开启了 timer 但卸载时不处理;watcher 和事件订阅重复触发同一段逻辑。这些问题短期不明显,但长期运行会变成难以排查的行为异常。这条规则相当于提醒 AI:不是所有副作用都能靠缘分收场。

8. constants-and-magic-values:别让魔法值满地跑

这个 reference 管理常量和魔法值,例如业务状态、事件名、缓存 key、storage key、路由、API path、正则、默认值、分页数等。如果这些值只有局部意义,可以留在局部;但如果代表共享业务含义,就应该有稳定来源。

AI 有时会随手写字符串:status === 'success'。单看没有问题。但如果项目里到处都是 'success'、'SUCCESS'、'done'、'finished',将来修改业务状态时就会非常热闹。这条规则的意义是:有业务含义的值,不要让它自由奔跑在项目中。

9. type-convergence:类型相同,不代表概念相同

这个 reference 管理类型收敛。它提醒 Codex:如果多个类型字段相同,且业务含义、生命周期也相同,可以考虑统一;但如果只是结构长得像,就不要强行合并。

这一点非常重要。AI 很容易看到两个 interface 字段一样,就认为可以抽取公共类型。但前端表单类型、接口响应类型、数据库实体类型,可能字段一模一样,语义却完全不同。强行合并后,一个地方修改,另一个地方被迫跟随变动,最终类型系统从保护伞变成连坐制度。

10. convergence-and-abstraction:不是所有重复都该抽象

这个 reference 管理代码收敛和抽象边界。它承认一个现实:允许合理的局部重复。如果逻辑只出现一次,或者业务含义不同,或者未来变化方向不同,或者抽象会让代码更难懂,那么就不应该为了“消灭重复”而抽象。

这条规则非常反 AI 本能。AI 看到重复,常常想收敛;看到相似,常常想封装。但抽象不是奖励机制,不是写得越多越高级。好的抽象应该降低理解成本,而不是把简单代码变成参数迷宫。

11. ui-style-convergence:UI 风格可以统一,但别硬统一

这个 reference 管理 UI 样式和变体收敛。例如相同的按钮、输入框、卡片、徽标、表格样式,重复的 class list,暗色模式规则,响应式布局规则,都可以考虑收敛到基础组件、设计 token 或 variant。但它并非鼓励 AI 看到 class 重复就马上抽取组件。

UI 中的一些重复来自设计系统,另一些来自局部业务场景。前者值得收敛,后者未必。这条规则的价值在于:让 AI 既能识别真正的设计重复,也不要将每个长得像的东西都拉去认亲。

12. engineering-config-convergence:工程配置别各玩各的

这个 reference 管理工程配置收敛,例如 TypeScript 配置、lint 配置、测试配置、构建配置、formatter、package scripts、依赖版本、环境变量 schema、发布流程等。这些地方一旦重复且不一致,很容易出现“我这里能跑,你那里不行”的经典情况。

但同样,它并非让 AI 随意修改配置。工程配置影响范围通常很大,所以只有当任务确实涉及配置收敛时,才应该去动它。换句话说:配置文件不是许愿池,不能路过就扔一个优化进去。

13. dependency-management:不要为小事加新包

这个 reference 管理依赖管理。它强调不要为了简单功能引入新依赖,不要引入职责重复的第二个库,不要在窄任务中升级无关依赖,也不随便修改 lockfile。

AI 有时很热衷于推荐库。格式化时间?加个库。深拷贝?加个库。简单校验?加个库。但依赖不是免费的,它带来体积、维护、安全、升级和团队认知成本。这条规则提醒 Codex:能用三行解决的问题,不要先召唤整个 npm。

14. docs-and-comments:注释解释为什么,不解释废话

这个 reference 管理文档和注释。它鼓励解释业务目的、分支原因、边界场景、状态流转、兼容约束、性能取舍和临时方案移除条件。但它反对显而易见的注释,也反对没有 owner 或移除条件的 TODO。

AI 特别容易写出这样的注释:// 设置标题setTitle(title)。这不是注释,而是将代码又朗读了一遍。好的注释应该告诉人类:为什么这里要这么做,而不是告诉人类这行代码长什么样。

15. testing:测试行为,不测试自我感动

这个 reference 管理测试。它强调不要给薄包装写无意义的测试,不要重复相同输入输出的测试,不要测试 mock 本身,不要为了覆盖率数字写测试。有价值的测试应覆盖正常路径、边界值、空值、非法值、权限、状态转换、错误处理、回归场景等。

这点也很适合约束 AI。AI 可以快速写出大量测试,但数量不代表质量。如果测试只是证明 mock 会返回 mock,那它更像是在给自己鼓掌。

16. error-handling-and-logging:错误不要被悄悄吞掉

这个 reference 管理错误处理和日志。它强调不要无声地吞掉错误,能明确失败就不要隐藏错误状态;处理错误应在真正能恢复的边界;转换或重新抛出错误时要保留有用上下文。

日志也同样。要记录能帮助诊断真实问题的信息,不要给正常流程添加一堆噪音,也不要把临时 debug 遗留到生产代码。这条规则的目的很朴素:出问题时,人类至少要知道问题在哪里,而不是只能看着控制台思考人生。

17. naming-and-files:命名稳定,文件别乱拆

这个 reference 管理命名和文件组织。它强调一个概念应该有一个稳定名字,不同名字应意味着不同含义;优先使用领域术语,不要随手起 helper、manager、common、base、util 这类模糊名字。

它也提醒不要为了让文件变小就拆分文件,不要为了方便把无关职责塞进一个文件。AI 很容易“整理结构”,但结构整理本身就是改动。如果任务不要求,就不要顺手修改命名、移动文件、拆分模块。否则看起来只是组织调整,实际上可能影响导入路径、公共 API 和团队认知。

18. code-review:Review 先找风险,不先夸优雅

这个 reference 管理代码审查。它要求 review 优先关注错误行为、回归、边界条件、契约不匹配、缺失验证、不安全副作用、测试缺失等。这能避免 AI review 变成空泛评价:“整体结构清晰。”“代码可读性较好。”“建议进一步优化。”

这些话并非完全无用,但如果没有指出真实风险,就像开会时说“我们要持续改进”一样,听起来正确,落地困难。好的 review 应先把可能出事故的地方指出来。

19. final-response:交付时说人话

这个 reference 管理最终回复。它要求 Codex 在完成任务后说清楚:改了什么,验证了什么,还有什么不确定,下一步是什么。这也很重要。因为 AI 很容易把最终回复写成过程汇报:“我首先分析了项目结构,然后检查了相关文件,接着进行了修改……”

用户真正关心的是结果。所以这条规则要求它开门见山:事情是否完成,完成到什么程度,有没有验证,哪里还需要注意。

四、它真正解决的不是代码问题,而是边界问题

回顾这些 reference,会发现 codex-dev-norms 真正解决的并非某一种具体 bug,而是 AI 开发中的边界问题。

AI 很强,但它不知道你的项目中哪些东西不能碰。它不知道这个接口字段必须严格按定义来,不知道这个重复现在不该抽象,不知道这个状态只属于当前组件,不知道这个中文文件不能随便用默认编码读写,它也不知道你今天只是想修一个按钮,而不是顺便参加一次架构改造。

所以这套 skill 的意义,就是将那些隐含经验变成显式规则。让 Codex 从“能写代码”转变为“能按项目边界写代码”。

五、让 AI 少一点自我发挥,多一点工程克制

AI 写代码越来越强,这是事实。但在真实项目中,强不等于可以随便发挥。很多时候,我们需要的不是一个永远有新想法的 AI,而是一个知道什么时候该停手的 AI。

codex-dev-norms 这类 skill,就是给 Codex 准备的一套开发家规。它不会让 AI 失去能力。恰恰相反,它让 AI 的能力更可控、更稳定、更适合进入真实工程协作。

以前的 Codex 像一个精力旺盛的搭子:你说一句,它能写一屏。现在有了这套规则,它仍然能写一屏——但终于知道,哪半屏不该写。