1. 为什么AI写的代码总带着一股“自作聪明”的味儿刚接触AI编程助手那会儿我一度觉得这玩意儿简直是救星。你描述一个需求它唰唰唰给你吐出一大段代码结构完整、注释齐全乍一看比我自己写的还规范。但真正把它接进项目里跑起来问题就来了它总在你看不见的地方偷偷“加戏”。举个我上周刚踩的坑。我让AI帮我写一个读取配置文件并返回字典的函数需求描述得很清楚文件不存在时返回空字典。结果它给我写了个什么东西呢它不但读了文件还顺手帮我做了类型校验、默认值填充、环境变量覆盖甚至在文件不存在时自动创建了一个模板文件。我当时就愣住了——我只是想要个读取函数它给我整了个配置管理中心。这就是典型的“自作聪明”AI在缺乏明确边界约束时会基于训练数据中的常见模式自行脑补出大量你没要求的功能。这种行为的根源在于大语言模型的生成机制。它本质上是在做“最可能的下一段代码”预测而训练语料里充斥着各种“完整”“健壮”“生产级”的代码范例。当你给出的提示词不够精确时模型会倾向于选择那些看起来更“专业”、更“周全”的实现路径。问题在于它并不知道你的项目上下文不知道你的异常处理策略、不知道你的日志规范、不知道你的依赖管理原则。于是它就用一套通用的、教科书式的方案来填空结果就是代码能跑但跟你的项目格格不入。更麻烦的是这种“自作聪明”往往藏在细节里。比如它会在你的同步函数里悄悄塞一个异步调用会在你的纯函数里引入一个全局状态会在你的轻量工具类里加上一堆你根本没装的第三方依赖。你Review的时候如果不逐行看很容易就放过去了。等到线上出问题再回头查才发现是AI给你埋的雷。所以这篇内容我想聊的就是怎么通过一套组合拳把AI写代码时的“自由发挥”关进笼子里。核心思路不复杂用AGENTS.md定规矩用结构化Prompt划边界用代码Review做兜底。这三件事做好了AI就能从一个“爱炫技的实习生”变成一个“听话的靠谱队友”。下面我按实操顺序把每个环节拆开讲。2. 用AGENTS.md给AI立规矩项目级的约束文件怎么写2.1 AGENTS.md到底是什么为什么它比Prompt更管用AGENTS.md这个概念最近在AI编程圈子里讨论得很多但很多人对它理解有偏差。它不是某个工具的专属配置文件而是一种约定在项目根目录放一个Markdown文件用自然语言描述这个项目的技术栈、代码规范、目录结构、依赖管理策略、异常处理约定等等。AI编程助手在生成代码前会读取这个文件把它作为上下文的一部分。为什么它比在每次对话里写一长串Prompt更管用因为Prompt是临时的、一次性的而AGENTS.md是持久的、项目级的。你不需要每次跟AI对话都重复“我们用Python 3.11、用pydantic做校验、异常统一走自定义的AppError、日志用structlog”这些信息。写一次所有后续的代码生成都会自动带上这些约束。我自己的项目里AGENTS.md大概长这样# 项目约定 ## 技术栈 - Python 3.11使用uv管理依赖 - Web框架FastAPI - 数据校验pydantic v2 - 日志structlog禁止使用print - 测试pytest pytest-asyncio ## 代码规范 - 所有公开函数必须有类型注解 - 异常统一继承自 AppError禁止直接抛 ValueError - 禁止在业务逻辑中直接读写环境变量统一走 config 模块 - 禁止引入新的第三方依赖如需引入必须先讨论 ## 目录结构 - src/ 放业务代码 - tests/ 放测试文件名以 test_ 开头 - scripts/ 放一次性脚本不纳入CI ## 禁止事项 - 不要自动创建文件或目录 - 不要添加未要求的日志语句 - 不要做防御性编程以外的额外校验 - 不要修改函数签名这个文件的关键在于“禁止事项”那一节。AI的“自作聪明”往往就藏在它“顺手帮你做”的那些事情里。你明确告诉它不要做什么比告诉它要做什么更有效。2.2 写AGENTS.md时最容易犯的三个错误第一个错误是写得太笼统。比如只写“遵循PEP8规范”这对AI来说几乎没有约束力因为PEP8本身很宽泛AI可以找到无数种“符合PEP8”但你不想要的写法。有效的约束必须是具体的、可判定的。比如“函数参数超过5个时必须用dataclass封装”就比“保持函数简洁”有用得多。第二个错误是只写“要什么”不写“不要什么”。AI在正向指令下的行为空间仍然很大只有负向指令才能有效压缩它的发挥余地。我现在的习惯是每写一条正向规范就配一条对应的负向禁令。比如“用structlog记日志”配“禁止使用print和logging模块”。第三个错误是写完就不管了。AGENTS.md不是一劳永逸的每次你发现AI又犯了新的“自作聪明”就应该把对应的禁令补进去。我大概每两周会更新一次这个文件现在它已经成了项目里最有价值的文档之一。2.3 一个真实案例AGENTS.md怎么拦住了一次“过度设计”上个月我让AI帮我写一个简单的重试装饰器需求是“网络请求失败时重试3次每次间隔1秒”。如果没有AGENTS.mdAI大概率会给我写一个支持指数退避、抖动、最大重试时间、异常白名单、回调钩子的“通用重试框架”。但因为我提前在文件里写了“禁止引入未要求的配置项”和“工具函数保持单一职责”它这次只写了一个带for循环和time.sleep的简单实现。我后来问它为什么这次这么克制它说因为上下文里明确说了不要加额外配置。这说明约束是有效的。当然你不能指望一次就到位但持续迭代下来AI的输出会越来越贴近你的预期。3. 结构化Prompt的写法把“帮我写个函数”变成可执行的规格说明3.1 为什么你的Prompt总被AI“过度解读”大多数人写Prompt的方式是“帮我写一个函数读取用户上传的CSV文件返回DataFrame。”这句话在人看来很明确但在AI看来充满了模糊地带CSV编码是什么分隔符是什么有没有表头空值怎么处理文件大小有限制吗返回的DataFrame需要做类型转换吗异常怎么抛AI面对这些空白不会停下来问你而是会用自己的“常识”去填。它的常识来自训练数据而训练数据里的CSV读取代码往往带着一堆防御性逻辑尝试多种编码、自动推断分隔符、跳过坏行、填充缺失值。这些逻辑单独看都没问题但堆在一起就是你不想要的“自作聪明”。结构化Prompt的核心思路就是把所有你能提前决定的细节都写进去不给AI留脑补的空间。我习惯用一个固定的模板来组织## 任务 [一句话描述要做什么] ## 输入 [函数签名、参数类型、参数含义] ## 输出 [返回值类型、返回值含义] ## 约束 [必须遵守的规则] ## 禁止 [明确不要做的事情] ## 示例 [输入示例和期望输出]这个模板看起来有点繁琐但写习惯了之后反而比反复跟AI扯皮要快得多。3.2 把“禁止”写清楚负向Prompt的威力正向Prompt告诉AI“做什么”负向Prompt告诉AI“不做什么”。在抑制“自作聪明”这件事上负向Prompt的效力远大于正向。我整理了一份常用的负向Prompt清单基本覆盖了AI最爱“加戏”的几个方向AI爱加的东西对应的负向Prompt额外的参数校验不要做调用方未要求的参数校验自动创建文件/目录不要创建任何文件或目录日志和打印不要添加日志语句异常包装不要捕获和重新抛出异常除非明确要求类型转换不要做隐式类型转换默认值填充不要为缺失值提供默认值缓存逻辑不要引入缓存机制并发处理不要使用多线程或异步除非明确要求第三方依赖不要引入新的import配置项不要添加可配置参数这张表我基本是贴在AGENTS.md里的每次写Prompt时也会对照着检查一遍。效果很明显AI的输出从“一个功能完整的模块”变成了“一个刚好满足需求的函数”。3.3 用示例锚定输出格式光有文字约束还不够AI对“示例”的敏感度远高于对“描述”的敏感度。如果你在Prompt里给一个输入输出的例子AI会倾向于模仿这个例子的风格和粒度。比如你想要一个简洁的实现就给一个简洁的示例你想要详细的注释就在示例里体现注释的写法。我通常会给两个示例一个正常输入一个边界输入。这样AI就知道边界情况该怎么处理而不是自己发明一套处理逻辑。比如读取CSV的函数我会给一个“文件存在且格式正确”的示例再给一个“文件不存在”的示例明确期望是“抛出FileNotFoundError”而不是“返回空DataFrame”。这一个示例就能省掉后面大量的返工。3.4 Prompt写完之后先让AI复述一遍需求这是一个我最近才养成的习惯效果出奇地好。在让AI写代码之前先让它用自己的话把需求复述一遍并列出它打算怎么实现。如果它的复述里出现了你没提到的功能或者它的实现计划里有你不想要的步骤你可以在它动手之前就纠正。这个步骤的成本很低但能拦住大部分“自作聪明”。因为AI在复述时会把它理解到的隐含需求显式化你一眼就能看出它是不是想多了。我现在的流程基本是写Prompt → 让AI复述 → 确认无误 → 让AI写代码 → Review。多了一步复述返工率大概降了一半。4. 代码Review环节怎么快速识别AI埋的“聪明雷”4.1 AI代码Review和人类代码Review的区别Review人类写的代码你关注的是逻辑正确性、边界处理、性能问题。Review AI写的代码你首先要关注的是“它有没有做你没让它做的事”。这是一个完全不同的审查视角。人类程序员偷懒通常是少写AI“偷懒”反而是多写。我现在的Review流程分三步第一步扫import看有没有引入新的依赖第二步扫函数签名看有没有多出参数第三步逐行看逻辑重点找那些“看起来合理但你没要求”的代码块。这三步走下来大部分“自作聪明”都能揪出来。4.2 高频“聪明雷”清单根据我自己的踩坑经验AI最爱在以下几个地方“加戏”Review时重点看这些位置异常处理AI特别喜欢写try...except而且except的粒度往往很粗比如except Exception。它还会在except里做各种“优雅降级”比如返回默认值、记录日志、重试。这些行为在你没要求的情况下都是雷。类型转换AI会在你意想不到的地方做类型转换比如把字符串转成数字、把None转成空字符串。这些转换在单测里可能没问题但在真实数据上会掩盖bug。默认值AI喜欢给参数加默认值尤其是None、[]、{}这些。有些默认值是合理的但有些会改变函数的语义。缓存和记忆化AI有时候会“贴心”地给你加个lru_cache但你的函数可能有副作用加了缓存就出bug。并发AI会在IO操作上自动加async或线程池但你的调用方可能是同步的加了反而坏事。日志AI会在关键路径上插日志但你的项目可能有统一的日志规范它插的日志格式不对或者级别不对。我把这个清单做成了一个Checklist每次Review AI代码时对着过一遍。熟练之后扫一眼就能看出问题。4.3 用测试用例反向约束AI除了Review另一个有效手段是让AI先写测试再写实现。你先描述清楚函数的输入输出和边界条件让AI写测试用例。测试用例是具体的、可执行的AI很难在测试里“自作聪明”。然后你让AI根据测试写实现它就会收敛很多因为测试已经定义了行为边界。这个方法的额外好处是你顺便得到了一套测试。我现在的习惯是对于稍微复杂一点的函数都让AI先写测试。测试写完之后我会人工过一遍确认边界条件覆盖到位再让它写实现。这样出来的代码质量比直接生成要高一个档次。5. 多AI协作时的“自作聪明”放大效应5.1 为什么多个AI一起干活反而更容易出问题现在很多人喜欢用多个AI协作比如一个AI写代码另一个AI做Review还有一个AI写测试。这个思路本身没问题但实操下来你会发现“自作聪明”的问题会被放大。因为每个AI都有自己的“常识”它们之间的常识还不一致。我遇到过最离谱的一次是AI-A写了一个函数返回None表示失败AI-B做Review时认为应该抛异常就“顺手”改了AI-C写测试时又按照返回None来断言。三个AI各自都觉得自己在做正确的事合在一起就是一团乱麻。5.2 用统一的AGENTS.md做“共同语言”解决这个问题的关键是让所有AI共享同一份AGENTS.md。这份文件不只是给写代码的AI看的也是给Review的AI和写测试的AI看的。它定义了项目的“共同语言”异常怎么抛、返回值怎么约定、日志怎么打。所有AI都基于同一套约定工作冲突就会少很多。我现在的做法是在AGENTS.md里专门加一节叫“接口约定”把函数的错误处理策略、返回值语义、副作用范围都写清楚。比如“所有可能失败的操作必须抛AppError的子类禁止返回None表示失败”。这一条写进去之后多AI协作时的扯皮少了一大半。5.3 给每个AI分配明确的职责边界另一个经验是不要让多个AI做同一件事。比如Review这件事要么让AI做要么让人做不要两个AI互相Review。因为AI之间的Review很容易变成“互相加戏”A说你应该加个校验B说你应该加个日志最后代码越Review越复杂。我的做法是AI-A负责写实现AI-B负责写测试人负责Review。AI-B写测试时只关注行为是否正确不关注实现细节。人Review时关注实现是否符合项目约定。职责清晰了每个环节的“自作聪明”都能被下一环节拦住。6. 把“自作聪明”变成“恰到好处”的长期调优思路6.1 建立你自己的“AI犯错日志”我从今年年初开始维护一个Markdown文件专门记录AI在项目里犯的“自作聪明”错误。每次发现一个新的模式就记一条什么场景、AI做了什么、期望是什么、对应的约束应该怎么写。这个文件现在有四十多条记录基本覆盖了AI在我这个项目里的所有“加戏”模式。这个日志的价值在于它让你从“每次都要重新想怎么约束AI”变成“查表补约束”。而且当你把日志里的约束逐步沉淀到AGENTS.md和Prompt模板里之后AI的输出会越来越稳定。我现在的新项目基本第一周就能把AI调教到“听话”的状态靠的就是之前积累的这份日志。6.2 定期回顾AI生成的代码找出系统性偏差除了记录单次错误我还会每个月抽时间回顾一下AI生成的代码看看有没有系统性的偏差。比如我发现自己项目里AI生成的函数参数数量普遍偏多平均比手写函数多两个参数。这就是一个系统性偏差说明我的Prompt模板里对参数数量的约束不够。发现系统性偏差之后就可以针对性地调整约束。比如在AGENTS.md里加一条“函数参数不超过4个超过时用dataclass封装”。这种调整一次就能影响后续所有生成效率很高。6.3 不要追求“零自作聪明”追求“可控”最后想说一个心态上的问题。我一开始的目标是让AI完全按照我的想法写代码一点偏差都不能有。后来发现这不现实也不必要。AI的“自作聪明”有时候确实能带来一些我没想到的好点子完全扼杀反而可惜。我现在的目标是“可控”AI可以有自己的想法但必须在Review环节被我发现和评估。如果它的想法确实更好我就采纳并更新约束如果不好我就加一条禁令。这样AI既是一个执行者也是一个能带来惊喜的协作者。关键是你要有一套机制让它的“聪明”在你的掌控范围内。这套机制的核心就是三件事AGENTS.md定规矩、结构化Prompt划边界、代码Review做兜底。三件事都做到位AI写代码的“自作聪明”就不再是问题而是一种可以被利用的特性。我现在的项目里AI生成的代码大概有七成可以直接用两成需要小改一成需要重写。这个比例比我半年前刚开始用的时候好太多了靠的就是持续调优这套约束体系。