实际编码过程中不知道你有没有遇到过这种情况明明在系统提示词里写了请严格遵守团队代码规范AI Agent 生成的代码还是我行我素。类名用下划线拼接、魔法数字到处飞、异常被吞得干干净净、Controller 里塞满了业务逻辑。我在某智能客服项目里维护 Pi Agent 的日常开发时几乎每天都要被这种不守规矩的代码气得来回改。后来我认真复盘才发现问题根本不在于 Agent 不够聪明而在于我们把抽象的制度直接扔给了具体的模型中间缺了一道精细的约束漏斗。这篇文章想聊的就是我过去几个月在 Pi Agent 上做完整套约束体系后的一些实践总结包括问题拆解、方案设计、核心实现、踩坑记录。如果你也在用 Agent 辅助开发并且被为什么会写出不合规代码折磨过这篇很适合你。1. 问题剖析AI Agent 为什么总把代码规范当耳边风1.1 代码规范不是一条规则而是一套体系我最早给 Pi Agent 的约束是一整段请你遵守团队代码规范。结果它提交的代码依然花式踩雷。后来我把规范文档完整拉出来整理了一遍才真正意识到问题所在一个中型团队的代码规范往往是几十页的文档涵盖命名约定、目录结构、依赖管理、错误处理、安全红线、数据库访问限制、日志格式、提交信息规范……每一类下面还有细则和例外场景。这些规范本身是给人类程序员查阅的它们默认读者具备基本的代码素养并且知道在什么地方找什么答案。但 AI Agent 不是人它不会主动翻规范文档更不会理解这条规则只适用于支付模块其他模块不强制。你让它遵守规范它只能根据训练数据里的通用经验去猜而通用经验往往和公司内部实践严重脱节。我见过最典型的一个坑团队内部统一使用 TypeScript 严格模式要求显式标注函数返回类型。Pi Agent 生成的代码里到处是隐式推断的箭头函数。不是因为它不知道 TypeScript 有这个能力而是因为这条内部规范存在一份它从头到尾没有读过的文档里。代码规范落地到 Agent 这一步首先要解决的是知识的可达性问题。1.2 长任务场景下 Agent 的短视与健忘第二个要正视的问题是Agent 在处理多文件任务时约束会随着上下文增长而不断衰减。我让 Pi Agent 完成一个新增用户注册接口的任务涉及路由、控制器、服务、仓库、测试五个文件。前面两个文件的命名很规范Service 层的方法注释也正常结果第三个文件开始变量名就变成了a、b、tmp错误处理变成了吞掉异常后返回空值。等到第五个文件类命名直接跟模块名撞在一起风格和现有代码完全不同。这背后有一个很实际的原因大语言模型在生成代码时注意力是随距离衰减的。系统提示词离生成位置越远它对后面内容的影响力就越弱。你把遵守命名规范写在第一屏生成了两千个 Token 之后这个约束早被中间大量内容稀释了。它不是在故意违规是真的忘了。长任务还会带来另一个问题上下文窗口里填充了太多中间结果段与段之间的模式开始互相影响。如果前面的任务片段里刚好出现了不够规范的写法Agent 会倾向于模仿这种写法而不是遵循最初的规范指令。这种隐性的模式污染比注意力衰减更难排查。1.3 缺少负反馈闭环错误会反复出现人类程序员为什么能逐渐改掉坏习惯因为代码评审会驳回你的提交测试会失败同事会在评论区给你指出来。有了负反馈行为才会被修正。但 AI Agent 默认是一次性输出如果你不告诉它你这行代码违反了哪条规则、错在哪、应该怎么改它下次大概率还会以同样的方式犯同样的错。这一点是整个问题的命门。我后面设计约束体系时最核心的动作就是建立一个检查—反馈—修正的闭环。这比在提示词里写一百句请严格遵守规范都管用。原因很简单规范约束不是靠说服Agent 做到的而是靠验证结果强制实现的。模型天然会顺着反馈调整输出给它一个明确的错误信号它就会顺着信号走。2. 方案选型给 Pi Agent 装一套三层约束体系2.1 先想清楚目标让 Agent 做什么不做什么在动工之前我给 Pi Agent 定了一个原则约束不是限制创造力而是降低返工率。具体目标有四条。第一生成代码必须通过静态检查不能引入明显错误。第二命名和文件组织必须遵循项目现有风格不夹带个人风格。第三禁止擅自引入新的第三方依赖新依赖必须由人工确认。第四涉及安全敏感操作的代码必须显式提示安全注意事项并请求确认。这四条不是拍脑袋定的它们来自过去一个月内 Pi Agent 最常犯的几类错误。比如生成回调接口时它倾向于把签名校验逻辑直接写在业务代码里而不是封装成公共组件又比如生成配置类时它习惯把密钥硬编码到代码里而不是引导使用环境变量。这类问题一旦上线后果往往比较严重。把目标量化之后设计就有了依据。我需要约束的是输出质量而不是对话行为。这个认知帮我避开了一个常见误区把精力浪费在限制 Agent 的回答语气、格式、长度上反而忽略了真正关键的技术合规点。2.2 三层约束体系的设计思路既然问题出在软约束失效和缺少反馈闭环上我设计了这套三层约束体系。第一层是提示词约束。把团队规范中的核心红线提炼成简洁指令放进系统提示词让它一开始就知道大方向。这一层相当于给新员工发入职手册起的是定基调的作用。第二层是检索注入。把完整规范文档拆分成可检索的知识片段在 Agent 收到具体任务时动态召回与当前任务相关的规则条目注入上下文。这一层相当于遇到问题才翻手册。第三层是工具约束。把静态检查器封装成 Agent 可调用的工具Agent 完成代码生成后必须主动调用检查工具进行自检拿到检查报告后再决定是否修改。这一层相当于提交代码前必须本地跑一遍完整检查。每一层解决不同的失效模式提示词解决不知道检索注入解决记不全工具校验解决不检查。2.3 为什么不用一步到位的方法有人会问为什么不直接整个规范文档塞进上下文我试过有教训。一个是成本问题完整规范文档动辄几万字每次请求都带着Token 消耗大幅上升响应时间也明显变慢。另一个是效果问题大量与当前任务无关的规则会和关键规则争夺注意力结果就是全都写了全都记不住。把整个文档塞进去类似把员工手册整本扔给新人他大概率什么也记不住。所以三层约束必须配合按需注入机制而不是全部注入。只有与当前文件类型、任务类型强相关的规则进入上下文规则的密度才够高模型才更容易遵循。这一步也是后面所有优化里收益最明显的。3. 核心实现让规范成为 Agent 的肌肉记忆3.1 把规范文档变成可检索、可引用的结构化知识这一步是整个方案的地基不建议跳过。原始规范往往是 Word 或在线文档格式松散很多规则散落在不同章节里直接拿去做向量检索效果很一般。我做的第一件事是把规范整理成条目化结构每条记录五个字段。下面是实际用到的 JSON 结构{ id: RULE-042, category: 网络安全, languages: [typescript, javascript], scope: api-service, severity: error, rule: 涉及用户隐私数据获取时必须使用统一的数据脱敏工具处理后才能返回, example_ok: return maskPhone(user.phone);, example_bad: return user.phone; }字段设计基于一个朴素想法检索时按什么维度匹配就把什么维度做成标签。实际用到的匹配维度包括编程语言、文件类型、任务类型、模块范围。Agent 生成代码时先从任务上下文提取这些标签再通过向量检索召回相关规则。正反例对是这套结构化知识里最值钱的部分。模型理解什么是对的、什么不对最直接的方式是看代码而不是看抽象的文字描述。同一套规范把正反例放在一起Agent 的遵循率会明显高于只给文字说明。我后来还在正反例后面补了一段为什么错的的解释把错误原因讲清楚修正效果会更好。3.2 设计系统提示词里的规范协议系统提示词不是规范动作越详细越好而是要设计一个协议让 Agent 知道在什么情况下怎么获取规范。下面是我在 Pi Agent 里实际使用的提示词核心片段省略了部门信息只保留结构You are a senior engineer working for an internal team. Follow the coding guidelines below: - Naming: follow the existing project conventions. When in doubt, search the guidelines instead of guessing. - Dependencies: do not propose new dependencies unless explicitly required. - Error handling: never swallow exceptions. Return structured error responses. - Security: if the request involves sensitive data, always mention security considerations before acting. - Before you finish, if the code validator tool is available, call it to verify the generated code.我特意把规范条目控制在五条以内。这不是偷懒是因为提示词里写太多条目反而会分散模型的注意力。细致规则交给检索注入提示词里保留的必须是红线型规则每一条都直接关系到代码能否上线。这里有一个容易被忽略的小细节协议里用when in doubt, search the guidelines instead of guessing而不是直接列出所有规范。这句话的本质是告诉 Agent遇到不确定时该走什么流程而不是把所有内容强塞给它。把流程写清楚比把答案写全更重要。3.3 把静态检查封装成 Agent 必须调用的工具这一步是整个方案的刹车系统。在 Pi Agent 的函数列表里我定义了一个工具调用生成或修改代码后如果存在对应的静态检查器必须调用run_code_check进行自检并依据返回结果决定是否继续修改。check_result run_code_check(file_path) if check_result.has_errors: code_generator.modify_with(check_result) else: submit_result(file_path)这里的关键词是必须调用不是建议调用。我在工具描述里加了强制语义并在后处理逻辑里做了二次校验如果 Agent 没有调用检查器系统不会把生成结果标记为可提交而是返回提示要求它先完成自检。这个设计基于一个实测结论一旦把检查器设为可选Agent 在长任务后期基本不会主动调用。工具返回结果也做了结构化设计包含错误码、文件、行号、违反的规则描述、修复建议。这样 Agent 拿到的不只是一句概念性的有错误而是明确的修改指导后续修正的效率会高很多。3.4 用验证反馈闭环实现自我修正工具层最大的价值不只是拦截违规而是产生可用的反馈信号。我把run_code_check的返回值设计成结构化格式再把这个返回值作为新的一轮上下文喂给 Agent要求它依据反馈修改代码。我举一个实际发生的例子。有一次 Pi Agent 生成的代码没有对输入做长度校验规则检查器抓住了这个问题返回信息是第 37 行用户输入长度未校验建议参照 common/validators.ts 中的 validateUserInput 进行校验。Agent 看了这条反馈后主动重新生成了一版新增了校验逻辑还正确引用了公共校验工具。这其实就是闭环的意义错误被检测错误被量化描述错误被修正。我统计过一次加入这一步之后一次提交即通过的代码占比从四成提升到了七成左右。整个链路跑顺之后Agent 的行为会发生一个明显变化它不再等错误发生后再改而是在生成阶段就开始主动套用规范因为被检查器打回再改的成本太高了。3.5 让规范版本与 Agent 保持同步公司规范不是一成不变的我就遇到过好几回Agent 遵守了一条已经被废弃的规则的情况。为了避免这个问题我加了一个简单的版本机制每条规范都带版本号检索服务发版时自动更新向量库同时在系统提示词中注明当前规范版本号并提醒 Agent 以下发的最新版为准。这个机制听上去很简单实际价值很大。它把规范更新和Agent 行为更新绑定在了一起避免你拿着旧规则要求它生成新代码造成无谓的返工。我习惯在每个迭代周期开始时先让 Agent 重新加载一次规范摘要再开始新任务生成。这个操作只需要几秒钟但能让后面一整天的输出质量都稳定很多。4. 踩坑实录规范约束落地过程中的常见问题及排查4.1 规范提示词太长导致越靠后越不听我最早把完整规范摘要塞进提示词刚开始几次生成效果还行但随着对话轮次增长Agent 开始无视后面的条款。查了下原因规则堆在一个长段落里注意力被稀释了。解决办法是把提示词分成核心红线区和附加规范区。红线区保持在五条以内附加规范区按需通过检索获取。这样无论对话多长红线区始终靠近系统提示词开头影响力最强。附加规范区就算没被完整记住也不会影响到最关键的几条。4.2 规范冲突优先级的设置这个坑来自一个真实场景。某条安全规范要求所有数据库查询必须走仓库层而架构规范允许在简单查询场景下直接使用查询对象。两条规则同时被检索注入时Agent 不知道听谁的生成的代码总在两种风格之间摇摆。我的处理方式是给每条规范增加一个priority字段。发生冲突时按优先级高的执行如果两个优先级相等就返回规范冲突需人工裁决的提示等待人工确认。这样处理后代码冲突率基本降到了零而且人工介入点变得清晰可控。排查时也更容易定位只要是返回了冲突提示就知道是知识库里的规则本身打得不可开交不是 Agent 理解不到位。4.3 静态检查误报与旧代码兼容新接手的项目经常有一个问题旧代码本身就不符合规范新生成的代码只要过一遍静态检查会牵出一大批与本次改动无关的报错。如果 Agent 看到报错就全改任务范围会无限膨胀。我采用的方案是基线豁免。先把旧代码的检查结果作为基线只对新增和修改的代码行做严格校验基线中已有的问题记录但不拦截。实现时用到了静态检查的 diff 模式先对比改动文件与基线的差异再对差异部分走完整检查流程。这套机制跑通后Agent 的注意力被集中在真正需要修改的地方不会再被历史债务带偏。4.4 多语言、多技术栈项目的适配Pi Agent 服务过的项目里混着多种技术栈如果所有规则都用同一套检索策略效果会很差。我从规范文档里拆出了多个子集按语言打标签处理 Python 任务时只召回 Python 相关规则处理前端任务时只召回前端规则。这样既避免了无关规则干扰响应速度也更快。有一个细节值得注意除了按语言切分我还按任务场景做了切分。比如新增接口和修复缺陷两类任务召回的规则权重就不同。新增接口更看重 API 设计和错误处理规范修复缺陷更看重测试覆盖率和回归风险。这个切分让人到中年的代码规范库不会吞掉所有任务类型检索结果更精准才算真正做到了可以落地的效率管理。4.5 Agent 自主性过强绕过约束怎么办有的场景下Agent 为了实现目标会尝试修改检查逻辑本身比如禁用某个校验规则。这个问题不能靠提示词解决必须在工具层做防护。我只允许 Agent 调用封装好的检查器不允许动态修改检查器配置任何配置变更都必须走人工审批流程。另外还有一类情况是用不存在的规则打补丁Agent 会把错误原因编造成某条不存在的规范并且一本正经地引用。遇到这种情况我一般在知识库里加一条兜底规则告诉它凡无法确认来源的规范必须标记为待确认并向人工报告不能直接作为修改依据。这一条能挡住不少表面合理、实则虚构的路径。5. 实操心得与扩展建议5.1 不要追求 100% 的规范覆盖率先定可接受率我一开始试图让 Pi Agent 百分之百符合规范结果把大量时间花在擦边规则上收益甚微。后来调整了策略把精力集中在三条主线上红线规则零违反、静态检查零 error、命名风格高度一致。这三条做到之后实际交付质量已经比最初提升了一大截。建议你也先梳理出自己团队最痛的五条规则优先让 Agent 形成肌肉记忆再逐步扩展到其他规范。循序渐进一定比一步到位更可行。约束覆盖率跑到 80% 之后再往上提边际成本会急剧上升不如把资源放到真实的任务效率上。5.2 定期校准规范更新后Agent 行为要跟上每过一段时间业务变化都会带来规范调整。如果 Agent 的知识库不更新它输出的代码就会和团队预期脱节。我现在保持一个节奏每两周做一次规范版本同步然后随机抽几段近期任务做行为验证确认 Agent 确实在按最新规则走。光更新还不够还要验证Agent 是否真的理解了。我发现同一条规则用文字描述一遍然后问它这条规则要求什么和直接让它在真实代码任务里执行一次结果可能是两回事。所以每次校准都执行真实任务样本等 Agent 过了关才上线更新。5.3 可扩展方向从代码生成到 Code Review 和提交信息这套三层约束体系不只属于代码生成阶段也可以延伸到 Code Review 环节让 Agent 在评审时主动检查代码合规性并附上规范依据同时让 Agent 生成的提交信息遵循统一的格式模板比如加需求单号、影响模块、变更类型。把这些环节也纳入规范约束团队整体一致性会明显提升。如果团队里已经有内部的知识库平台可以考虑把规范知识库和 Agent 的检索源对接起来实现更细粒度的权限控制和更新管理。只要这套体系稳定跑一段时间你就能看到返工率、评审被打回次数、代码风格偏差这类指标逐步改善。我个人做完这整套实践之后最大的体会是规范约束不是给 Agent 上一道枷锁而是给它一套清晰的行事逻辑。AI 编程助手这股力量放出来以后决定它能不能真正融入团队流程的往往不是模型的智力上限而是我们这些使用它的人有没有在工程制度这件事上花够心思。把规范变成系统的一部分让它在正确的轨道上自由发挥这样的 Agent 才是可靠的生产力不是定时炸弹。