用AGENTS.md和Prompt工程约束AI写代码的过度设计问题

1. 为什么AI写代码总爱“自作聪明”1.1 一个让所有开发者都头疼的经典场景你让AI帮你写一个用户注册接口它二话不说给你整了一套完整的JWT鉴权、Redis缓存、消息队列异步写日志还顺手把数据库连接池给你换成了HikariCP。你看着屏幕上两百多行代码心里只有一个想法我就想要一个能往数据库插条记录的接口你给我搞了个分布式系统。这不是段子这是每天都在发生的事情。AI写代码的“自作聪明”几乎成了所有开发者的共同痛点。你让它改一个bug它顺手重构了三个文件你让它加个字段它给你把整个数据模型重新设计了一遍你让它写个简单的工具函数它给你引入了两个第三方依赖。更让人崩溃的是AI还会非常自信地告诉你“这样更好”“这样更健壮”“这样符合最佳实践”。问题是我现在的项目根本不需要这些“最佳实践”我需要的是能跑、能维护、不给我添乱的代码。1.2 问题的根源到底在哪里AI之所以会“自作聪明”核心原因有三个层面。第一个层面是训练数据的偏差。AI模型在训练时接触了大量的开源项目、技术博客和教程文章。这些内容有一个共同特点它们展示的往往是“理想状态”下的代码而不是“实际生产环境”中的代码。开源项目为了吸引star会尽量展示架构的优雅技术博客为了显得专业会尽量堆砌设计模式。AI学到的就是这种“过度设计”的风格。第二个层面是缺乏项目上下文。当你对AI说“帮我写个接口”的时候AI并不知道你的项目规模有多大、团队有多少人、技术栈是什么、现有的代码风格是怎样的、有没有历史包袱。它只能按照“最通用”的方式来写而“最通用”往往意味着“最复杂”。第三个层面是缺少明确的约束。大部分人跟AI对话的方式是“帮我写个XXX”而不是“在我的项目里按照现有的代码风格用最简单的方式实现XXX”。没有约束AI就会自由发挥而自由发挥的结果往往超出你的预期。1.3 解决思路用AGENTS.md给AI立规矩解决这个问题的核心思路其实很简单给AI一份明确的“行为准则”告诉它什么能做、什么不能做、什么必须做、什么绝对不要做。这份行为准则就是AGENTS.md。AGENTS.md本质上是一个放在项目根目录的Markdown文件它的作用是向AI描述项目的技术栈、代码规范、架构约束和编码偏好。当AI读取到这个文件后它就会按照你定义的规则来生成代码而不是按照它自己的“理解”来发挥。这个思路跟给新入职的同事写一份“项目开发规范”是一样的道理。新同事不了解项目你需要告诉他我们用的是什么框架、代码怎么组织、命名用什么风格、哪些库不能用、哪些模式必须遵守。AI也是一样的它不是不聪明而是太聪明了你需要给它划一个圈让它在圈里发挥。提示AGENTS.md不是某个特定工具的专属配置它是一个通用的约定。任何支持读取项目上下文文件的AI编程工具都可以使用这个文件来约束自己的行为。2. AGENTS.md到底应该怎么写才有效2.1 核心结构从“你是谁”到“你不能做什么”一份有效的AGENTS.md需要回答四个核心问题这个项目是什么、代码怎么组织、编码有什么规范、有哪些绝对禁止的操作。我把它总结为“四层结构”。第一层是项目概述。用三到五句话说明项目是做什么的、技术栈是什么、运行环境是什么。这一层的目的是让AI对项目有一个基本的认知避免它给出完全不搭边的建议。比如你用的是Flask而不是Django你就要明确写出来否则AI很可能默认给你生成Django的代码。第二层是目录结构说明。告诉AI每个目录放什么类型的文件这样它在生成新文件的时候就知道该放在哪里。很多人忽略这一层结果AI把工具函数放到了视图目录里把配置文件放到了测试目录里整个项目结构被搞得乱七八糟。第三层是编码规范。这是最核心的部分包括命名规范、注释规范、错误处理规范、日志规范等。你需要把团队内部约定俗成的东西全部写出来因为AI不会读心术你不写它就不知道。第四层是禁止事项。这一层往往被忽略但恰恰是最重要的。你需要明确告诉AI哪些事情绝对不能做比如“不要引入新的第三方依赖”“不要修改数据库schema”“不要使用ORM的raw query”“不要写超过50行的函数”等等。2.2 一个可以直接抄的AGENTS.md模板下面这份模板是我在实际项目中反复打磨出来的你可以直接拿去改改就能用。# 项目概述 这是一个基于Flask的RESTful API服务使用Python 3.11部署在Docker容器中。 数据库使用PostgreSQL 15缓存使用Redis 7。 项目规模约50个接口日均请求量10万级别。 # 目录结构 - app/models/数据库模型定义每个文件对应一张表 - app/views/路由和视图函数按业务模块分文件 - app/services/业务逻辑层所有复杂逻辑必须放在这里 - app/utils/工具函数必须是纯函数不依赖外部状态 - tests/单元测试每个service函数必须有对应的测试 - config.py配置文件所有配置项从环境变量读取 # 编码规范 - 命名变量和函数用snake_case类用PascalCase常量用UPPER_CASE - 注释每个函数必须有docstring说明参数、返回值和异常 - 错误处理使用自定义异常类不要直接raise Exception - 日志使用logging模块不要用print - 类型注解所有函数参数和返回值必须加类型注解 - 函数长度单个函数不超过50行超过必须拆分 - 导入顺序标准库、第三方库、本地模块每组之间空一行 # 禁止事项 - 不要引入新的第三方依赖除非我明确要求 - 不要修改数据库schema需要改表结构时先告诉我 - 不要使用ORM的raw query所有查询通过ORM完成 - 不要写超过50行的函数 - 不要使用全局变量 - 不要在生产代码中使用print - 不要自动生成数据库迁移文件 - 不要修改现有的API返回格式这份模板看起来简单但每一条都是踩过坑之后总结出来的。比如“不要引入新的第三方依赖”这一条就是因为之前AI为了写一个简单的日期格式化功能给我引入了arrow库而项目里已经有pendulum了。2.3 不同场景下的AGENTS.md变体AGENTS.md不是一成不变的不同的项目类型需要不同的约束重点。对于小型工具项目重点是“不要过度设计”。你需要明确告诉AI不需要设计模式、不需要抽象层、不需要考虑扩展性、能跑就行。这种项目最怕的就是AI给你整一堆接口和抽象类。对于大型协作项目重点是“保持一致性”。你需要详细描述现有的代码风格、命名习惯、错误处理方式让AI生成的代码跟现有代码看起来像是同一个人写的。对于遗留系统维护重点是“不要动不该动的东西”。你需要明确列出哪些模块是稳定的、哪些接口是不能改的、哪些依赖是不能升级的。这种项目最怕AI“好心办坏事”为了优化一个函数把整个模块搞崩了。对于原型验证项目重点是“快速迭代”。你可以放宽很多约束告诉AI优先考虑开发速度代码质量可以后续再优化。但即便如此也要明确禁止一些危险操作比如删除数据、修改配置文件等。注意AGENTS.md写完之后不是一劳永逸的。每次AI犯了新的错误你都应该把对应的约束补充进去。这份文件应该是活的随着项目的推进不断迭代。3. 用Prompt工程进一步约束AI的行为3.1 为什么光有AGENTS.md还不够AGENTS.md解决的是“项目级别”的约束问题它告诉AI这个项目的整体规范是什么。但在具体的一次对话中你还需要“任务级别”的约束告诉AI这次任务的具体要求是什么。这就是Prompt工程要解决的问题。很多人觉得有了AGENTS.md就不需要好好写Prompt了这是一个误区。AGENTS.md是底线Prompt是具体要求。底线告诉你不能做什么具体要求告诉你这次要做什么、怎么做、做到什么程度。举个例子AGENTS.md里写了“函数不超过50行”但这次任务你需要AI写一个复杂的数据处理逻辑50行可能不够。你需要在Prompt里明确说明“这次的数据处理函数可以超过50行但必须把每个步骤拆分成独立的子函数主函数只负责编排。”3.2 高效Prompt的五个核心要素一个能有效约束AI行为的Prompt需要包含五个核心要素。第一个要素是角色定义。告诉AI它现在扮演什么角色这个角色有什么经验和偏好。比如“你是一个有10年经验的Python后端工程师你偏好简单直接的代码讨厌过度设计”。角色定义会影响AI的生成风格一个“偏好简单”的角色定义能有效抑制AI的“炫技”冲动。第二个要素是任务描述。用最简洁的语言说清楚你要什么不要绕弯子。很多人喜欢在Prompt里写一大堆背景信息结果AI抓不住重点。正确的做法是先用一句话说清楚任务然后再补充必要的上下文。第三个要素是约束条件。这是最关键的部分。你需要明确列出这次任务的所有约束用什么技术、不用什么技术、代码放在哪个文件、函数叫什么名字、输入输出是什么格式、错误怎么处理等等。约束越具体AI的自由发挥空间就越小结果就越可控。第四个要素是示例。如果你能提供一个“正确”的示例AI的生成质量会大幅提升。示例不需要很复杂哪怕只是展示一下你期望的函数签名和返回值格式都能让AI少犯很多错误。第五个要素是反面示例。告诉AI什么是“错误”的做法这比告诉它什么是“正确”的做法更有效。比如“不要用try-except包裹整个函数体”“不要用lambda表达式”“不要用列表推导式嵌套超过两层”等等。3.3 实战Prompt模板与对比分析下面我用一个实际案例来展示Prompt的写法差异。差的Prompt帮我写一个用户注册的接口这个Prompt的问题在于没有角色定义、没有约束条件、没有示例、没有说明技术栈。AI只能靠猜猜的结果大概率不是你想要的。好的Prompt你是一个有10年经验的Flask后端工程师偏好简单直接的代码风格。 任务在app/views/user.py中新增一个用户注册接口。 约束条件 - 使用现有的User模型不要新建模型 - 密码必须用bcrypt加密项目已经安装了bcrypt库 - 邮箱必须做格式校验使用现有的validate_email工具函数 - 返回格式统一为{code: 0, data: {...}, message: success} - 错误返回格式为{code: 1, data: null, message: 具体错误信息} - 所有异常必须捕获并返回对应的错误码 - 函数名用register_user路由用POST /api/user/register - 不要引入新的第三方依赖 - 不要写超过40行的函数 示例 现有的login接口在app/views/user.py的login_user函数中请参考它的代码风格和错误处理方式。这个Prompt包含了角色定义、任务描述、约束条件、示例参考AI生成的结果基本可以直接用。更好的Prompt追加反面示例反面示例不要这样写 - 不要用try-except包裹整个函数体只包裹可能出错的数据库操作 - 不要用lambda表达式做校验用独立的函数 - 不要在视图函数里写业务逻辑业务逻辑放到app/services/user_service.py - 不要返回HTTP状态码200以外的状态码所有错误通过code字段区分加上反面示例之后AI犯错的概率会进一步降低。3.4 Prompt闪退和flagged问题的处理经验在实际使用中很多人会遇到Prompt被标记为违规或者直接闪退的情况。这个问题通常有几个原因。第一个原因是Prompt里包含了敏感词汇。有些AI平台会对Prompt进行内容审核如果你的Prompt里出现了某些被标记的词汇就会被拦截。解决办法是换一种表达方式用更中性的语言描述你的需求。第二个原因是Prompt太长或者太复杂。有些AI平台对Prompt的长度有限制超过限制就会闪退。解决办法是把Prompt拆分成多次对话先让AI理解上下文再提出具体任务。第三个原因是Prompt的格式有问题。比如包含了特殊字符、代码块嵌套错误、Markdown格式混乱等。解决办法是保持Prompt格式简洁避免复杂的嵌套结构。我个人的经验是把AGENTS.md的内容放在项目文件里让AI自己读取而不是全部塞进Prompt里。这样Prompt可以保持简短减少被拦截的概率。4. 代码规范检查与自动化约束4.1 让AI生成的代码自动符合规范光靠AGENTS.md和Prompt约束还是有可能出现AI“阳奉阴违”的情况。你明明写了“函数不超过50行”它给你写了个49行的函数但里面嵌套了五层if-else。你明明写了“不要引入新依赖”它给你用了一个Python内置库但那个库在Python 3.11里已经废弃了。所以你需要一套自动化的检查机制在AI生成代码之后自动验证是否符合规范。这套机制的核心是把AGENTS.md里的约束转化为可执行的检查规则。具体来说你可以用以下几种工具组合flake8检查代码风格包括行长度、导入顺序、命名规范等pylint检查代码质量包括函数复杂度、重复代码、未使用变量等mypy检查类型注解确保所有函数都有正确的类型标注black自动格式化代码统一代码风格isort自动排序导入语句这些工具可以配置在项目的pre-commit钩子里每次AI生成代码后自动运行。如果检查不通过就把错误信息反馈给AI让它重新生成。4.2 配置示例pre-commit钩子下面是一个实际的pre-commit配置可以直接复制到你的项目里。# .pre-commit-config.yaml repos: - repo: https://github.com/psf/black rev: 23.12.0 hooks: - id: black language_version: python3.11 - repo: https://github.com/pycqa/isort rev: 5.13.2 hooks: - id: isort args: [--profile, black] - repo: https://github.com/pycqa/flake8 rev: 6.1.0 hooks: - id: flake8 args: [--max-line-length100, --max-complexity10] - repo: https://github.com/pre-commit/mirrors-mypy rev: v1.8.0 hooks: - id: mypy args: [--ignore-missing-imports]这个配置会在每次commit之前自动运行black、isort、flake8和mypy。如果AI生成的代码不符合规范commit会被阻止你需要让AI重新生成。4.3 把检查结果反馈给AI的正确姿势当检查工具报错时你需要把错误信息整理成AI能理解的格式然后让它重新生成。这里有一个技巧不要直接把原始的错误信息扔给AI而是要把错误信息翻译成“人话”。比如flake8报了一个“C901 ‘process_data’ is too complex (15)”你直接把这个扔给AI它可能不知道该怎么改。你应该翻译成“process_data函数的圈复杂度是15超过了限制的10。请把这个函数拆分成多个小函数每个函数的圈复杂度不超过10。”再比如mypy报了一个“error: Missing return statement”你应该翻译成“这个函数缺少返回值请检查所有分支是否都有return语句。”我通常会写一个简单的脚本把检查工具的输出转换成自然语言的反馈然后自动发给AI。这样整个流程就可以自动化运行不需要人工干预。提示圈复杂度Cyclomatic Complexity是衡量函数复杂度的指标数值越高说明函数里的分支越多、越难维护。一般来说圈复杂度超过10的函数就应该考虑拆分了。5. 常见问题与排查技巧实录5.1 AI不读AGENTS.md怎么办这是最常见的问题。你明明写了AGENTS.md但AI生成的代码还是我行我素。原因通常有三个。第一个原因是AGENTS.md的位置不对。有些工具要求AGENTS.md必须放在项目根目录有些工具要求放在特定的配置目录下。你需要确认你使用的工具到底从哪里读取这个文件。第二个原因是AGENTS.md的内容太长AI没有全部读取。有些工具对上下文文件有长度限制如果AGENTS.md超过了一定字数AI只会读取前面一部分。解决办法是把最重要的约束放在文件最前面把次要的说明放在后面。第三个原因是AI的“注意力”被其他信息分散了。如果你的Prompt里包含了大量的代码示例或者背景信息AI可能会忽略AGENTS.md里的约束。解决办法是在Prompt里显式提醒AI“请严格遵守AGENTS.md中的所有约束。”5.2 AI生成的代码总是“差一点”有时候AI生成的代码大方向是对的但总有一些小问题变量名不符合规范、错误处理不完整、注释写错了、返回值格式不对。这些问题不致命但每次都要手动改很烦。解决这个问题的关键是提供“正面示例”。你可以在AGENTS.md里放一段“标准代码示例”展示你期望的代码风格。AI看到具体的示例之后模仿的准确率会大幅提升。比如你可以在AGENTS.md里放这样一段示例def get_user_by_id(user_id: int) - Optional[User]: 根据用户ID查询用户信息。 Args: user_id: 用户ID必须为正整数。 Returns: 找到的用户对象未找到返回None。 Raises: ValueError: 当user_id不是正整数时抛出。 if not isinstance(user_id, int) or user_id 0: raise ValueError(user_id must be a positive integer) return db.session.query(User).filter(User.id user_id).first()这段示例展示了命名规范、类型注解、docstring格式、错误处理方式、ORM查询方式。AI看到这个示例之后生成的代码就会向这个风格靠拢。5.3 常见问题速查表问题现象可能原因解决方法AI不遵守AGENTS.md文件位置不对或内容太长确认文件位置把关键约束放前面AI引入新依赖AGENTS.md没有明确禁止在禁止事项里明确列出“不要引入新依赖”AI过度设计缺少“简单优先”的约束在AGENTS.md里写明“优先使用最简单方案”AI生成的函数太长没有函数长度约束在AGENTS.md里写明“函数不超过50行”AI不写注释没有注释规范在AGENTS.md里写明“每个函数必须有docstring”AI用print调试没有日志规范在AGENTS.md里写明“使用logging禁止print”AI修改了不该改的文件没有文件范围约束在Prompt里明确指定“只修改XXX文件”AI返回格式不对没有返回格式说明在AGENTS.md里写明统一的返回格式Prompt被拦截包含敏感词或格式问题简化Prompt把详细约束放到AGENTS.md检查工具报错太多约束太严格逐步放宽约束先解决最严重的问题5.4 几个我踩过的坑第一个坑是AGENTS.md写得太抽象。我一开始写的是“代码要简洁”结果AI理解不了什么叫“简洁”。后来改成“单个函数不超过50行单个文件不超过300行嵌套不超过3层”AI就明白了。第二个坑是没有区分“必须”和“建议”。我在AGENTS.md里写“建议使用类型注解”结果AI有时候加有时候不加。后来改成“所有函数必须加类型注解”就再也没有遗漏过。第三个坑是忘了更新AGENTS.md。项目初期我禁止了某个库后来项目需要又把这个库加回来了但忘了更新AGENTS.md。结果AI一直不敢用这个库生成的代码绕来绕去很别扭。第四个坑是Prompt里放了太多代码。有一次我为了让AI理解上下文在Prompt里贴了500行现有代码。结果AI的注意力全被这些代码吸引了完全忽略了AGENTS.md里的约束。后来我改成只贴关键的函数签名和返回值格式效果就好多了。6. 把AI变成听话的“代码工人”6.1 核心思路回顾让AI写出符合预期的代码核心思路就是三个字给约束。AGENTS.md提供项目级别的约束Prompt提供任务级别的约束自动化检查工具提供验证级别的约束。三层约束叠加起来AI的“自作聪明”空间就被压缩到了最小。这个过程跟管理一个新人很像。你不能指望新人一来就懂你的项目规范你需要写文档、做培训、code review。AI也是一样的它不是不聪明而是太聪明了你需要用明确的规则把它框住。6.2 一个完整的协作流程我现在的工作流程是这样的第一步在项目根目录维护一份AGENTS.md随着项目迭代不断更新。第二步每次让AI写代码时用结构化的Prompt描述任务包含角色、任务、约束、示例、反面示例五个要素。第三步AI生成代码后自动运行pre-commit钩子进行检查。第四步如果检查不通过把错误信息翻译成自然语言反馈给AI让它重新生成。第五步人工review最终代码确认没有问题后合并。这个流程跑顺了之后AI生成的代码大概有80%可以直接用剩下20%需要微调。相比之前每段代码都要大改的情况效率提升非常明显。6.3 最后的经验分享我用了大半年时间打磨这套方法最大的体会是约束越具体AI越好用。你给AI的规则越明确它犯错的概率就越低。不要怕AGENTS.md写得太长宁可写详细一点也不要让AI去猜。另外一个小技巧是把AGENTS.md当成一个“活文档”来维护。每次AI犯了新的错误就把对应的约束补充进去。这样你的AGENTS.md会越来越完善AI也会越来越听话。还有一个经验是不要试图一次性约束所有东西。先解决最痛的问题比如“不要引入新依赖”“不要过度设计”等这些问题解决了再逐步添加更细的约束。一口吃不成胖子约束也是逐步加码的。最后分享一个我最近发现的技巧在AGENTS.md里加一段“如果你不确定怎么做先问我”的说明。这能有效减少AI的“自作主张”。当AI遇到模糊地带时它会先询问你的意见而不是自己拍脑袋决定。这个小小的改动帮我避免了好几次“AI自作聪明”的事故。