AI代码规范约束实战：从提示词到自动化校验的完整方案

1. 为什么AI写的代码总是“差点意思”

团队里最近流行用AI Agent辅助写代码，效率确实上来了，但新的麻烦也跟着来了。最典型的一幕是：Agent生成的代码逻辑跑得通，单元测试也能过，可一旦提交到代码评审环节，资深同事一眼就能挑出一堆毛病——命名风格跟项目里其他模块格格不入、异常处理直接吞掉、日志打得随心所欲、目录结构放错位置。更让人头疼的是，同一个Agent在同一个项目里，今天写的代码符合规范，明天又“放飞自我”，仿佛完全没记住昨天刚被纠正过的问题。

这个现象背后其实有个很朴素的原因：AI Agent默认追求的是“功能正确”，而不是“工程正确”。它被训练的目标是让代码能运行、能通过测试，至于这段代码放在你们团队里是否“合群”，它并不天然关心。你如果只是丢一句“帮我写个用户注册接口”，它就会按自己见过的海量开源代码的平均风格来写，而这个“平均风格”跟你们团队的规范大概率对不上。

所以问题就变成了：怎么把团队沉淀下来的代码规范，变成Agent每次生成代码时都绕不开的硬约束。我拿手头一个叫Pi Agent的智能编码助手做了几轮实验，从最粗暴的提示词约束，到配置文件注入，再到自动化校验闭环，踩了不少坑，也总结出一套相对稳的做法。这篇就把整个思路和实操细节摊开讲，适合正在把AI编码工具往团队工作流里塞的开发者、技术负责人，以及被AI代码评审折磨过的同学参考。

需要先说明一点：不同Agent的底层能力差异很大，有的支持自定义规则文件，有的只能靠提示词，有的能挂载外部工具。下面讲的方法论是通用的，但具体落地时你得根据自己用的Agent做适配。Pi Agent在这里只是作为一个具体样本，方便把细节讲透。

2. 先搞清楚Pi Agent到底“听谁的话”

在动手约束之前，得先弄明白一个Agent的决策链路。很多人一上来就写一大堆规则丢给Agent，结果发现它该违反还是违反，然后就下结论说“这Agent不行”。其实问题往往出在你没搞清楚它的规则优先级。

2.1 Agent的三层指令来源

以Pi Agent为例，它在生成代码时，实际会参考三类信息，优先级从高到低大致是这样：

• 系统级预设：Agent出厂时内置的行为准则，比如“优先保证代码可运行”“遵循主流开源风格”。这一层你基本改不动，只能通过后面的层去覆盖。
• 项目级配置：放在项目根目录下的规则文件，比如.pi/rules.md或类似的约定文件。这一层是团队能掌控的核心抓手，也是本文重点。
• 会话级提示：你在当次对话里临时说的话，比如“这次用函数式写法”。这一层灵活但易失，下次开新会话就没了。

关键结论是：想让规范稳定生效，必须把规则沉淀到项目级配置，而不是靠每次对话临时叮嘱。会话级提示只适合处理一次性特殊需求，指望它来维持长期一致性，等于每天重新教一遍新人。

2.2 为什么“写清楚规则”比“写更多规则”重要

我一开始犯的错，是把团队代码规范文档整篇复制进规则文件，洋洋洒洒几千字。结果Agent的表现反而更差，因为它抓不住重点，规则之间还互相打架。后来我做了个减法，只保留三类内容：

1. 硬性禁止项：比如禁止使用某类被团队淘汰的写法、禁止在业务层直接拼接SQL。
2. 必须遵守的结构约定：比如目录分层、文件命名、导出方式。
3. 风格偏好：比如命名用驼峰还是下划线、注释语言、日志格式。

这三类里，前两类是“红线”，必须让Agent无条件执行；第三类是“倾向”，允许在特殊场景下灵活。把红线和倾向混在一起写，Agent就会分不清轻重，遇到冲突时随机选一个，表现自然不稳定。

提示：规则文件不是越长越好。经验值是控制在500到800字以内，超过这个量级，Agent的遵循率会明显下降。宁可分多个小文件按模块加载，也不要堆成一篇长文。

2.3 一个容易被忽略的细节：规则的“可执行性”

规则写得再漂亮，如果Agent没法判断自己有没有遵守，那也白搭。比如“代码要优雅”这种话，对Agent来说等于没说，因为它没有“优雅”的判定标准。有效的规则必须是可判定的，比如“函数参数超过4个时必须用对象传参”“所有对外接口必须有入参校验”。这类规则Agent能在生成时自查，也能被后续的自动化工具验证。

我在规则文件里专门加了一节叫“自查清单”，把最容易被违反的几条列成问句形式，比如“我有没有在catch块里只打日志不处理？”“我有没有把工具函数直接写在业务文件里？”实测下来，这种问句形式比陈述句更能触发Agent的自我检查行为。

3. 把规范“焊死”进Pi Agent的配置里

搞清楚优先级之后，接下来就是具体怎么配。这一节讲的是项目级规则文件的写法，以及怎么让Agent在每次生成时都真正读到它。

3.1 规则文件的目录结构与加载时机

Pi Agent默认会扫描项目根目录下的.pi/文件夹，里面的rules.md是主规则文件。但如果你把所有规则都塞进这一个文件，维护起来会很痛苦。我的做法是按维度拆成几个文件：

.pi/ rules.md # 主入口，只放全局红线 rules-naming.md # 命名与目录约定 rules-error.md # 异常处理与日志规范 rules-api.md # 接口层专项规范

然后在rules.md里用引用语法把它们串起来。这样拆分的好处是，当团队只调整了接口规范时，你只需要改rules-api.md，不用动其他文件，降低误改风险。

加载时机上有个坑要注意：Pi Agent只在会话启动时读取一次规则文件。也就是说，如果你在会话进行到一半时改了规则，当前会话不会生效，得重开。所以团队协作时，规则文件的变更最好集中在一天工作开始前完成，避免有人用着旧规则、有人用着新规则，产出风格打架。

3.2 命名与目录约定的具体写法

命名这块是最容易出问题的，因为不同人偏好差异大。规则文件里不能只写“用驼峰命名”，得给出明确边界。我实际用的写法是这样的：

## 命名规范 - 变量与函数：小驼峰，如 getUserInfo - 类与类型：大驼峰，如 UserService - 常量：全大写下划线，如 MAX_RETRY_COUNT - 文件名：小写中划线，如 user-service.ts - 禁止：拼音命名、单字母变量（循环下标 i/j/k 除外） ## 目录约定 - 业务逻辑放 src/services/ - 纯工具函数放 src/utils/，且必须无副作用 - 类型定义放 src/types/，禁止在业务文件里内联复杂类型 - 测试文件与被测文件同目录，后缀 .test.ts

这里有个细节值得说：“禁止拼音命名”这条一定要写。Agent在中文语境下训练，偶尔会冒出yonghu、dingdan这种命名，评审时非常尴尬。明确禁止后基本就绝迹了。

另外“单字母变量除外循环下标”这个括号补充也很关键。如果不写，Agent会矫枉过正，把for (let i = 0; ...)改成for (let index = 0; ...)，虽然不算错，但跟团队既有代码不一致，反而制造了新的风格分裂。

3.3 异常处理与日志的硬约束

异常处理是AI代码的重灾区。Agent特别喜欢写这种：

try { await doSomething(); } catch (e) { console.log(e); }

吞掉异常、只打日志、不区分错误类型，三宗罪占全了。规则文件里必须把这块写死：

## 异常处理 - 禁止空 catch 块，禁止只 console.log 不处理 - 业务异常必须抛出带错误码的自定义错误类型 - 底层异常向上抛时，必须补充上下文信息 - 日志使用统一 logger，禁止直接 console.log - 日志级别：debug 用于开发排查，info 用于关键流程，error 用于可恢复错误

光写规则还不够，我还在规则里加了一段“反例展示”，直接把上面那段错误代码贴进去，标注“这是禁止的写法”。Agent对具体例子的敏感度远高于抽象描述，加了反例之后，吞异常的情况下降了大概八成。

3.4 用“生成后自查”指令收口

规则写得再全，Agent也可能在生成长代码时“写着写着忘了”。所以我在规则文件末尾加了一段固定指令，要求它在输出代码后附上一段自查说明：

## 输出要求 生成代码后，请附上以下自查结果： 1. 命名是否符合规范（逐项确认） 2. 是否有未处理的异常路径 3. 新增文件是否放在了正确目录 4. 是否引入了规则中禁止的写法

这段自查说明看起来是形式主义，但实际作用很大。因为Agent在“生成自查”这个动作时，会重新过一遍自己的输出，相当于强制它做了一次代码评审。我对比过，加了自查指令后，明显违规的数量能再降一截。而且自查说明本身也方便人类评审时快速定位问题，一举两得。

4. 光靠提示词不够，得加自动化校验这道闸

规则文件能解决大部分问题，但你不能把宝全押在Agent的自觉性上。真正稳的做法，是在Agent输出之后、代码合入之前，加一道自动化的校验闸门。这道闸门不依赖Agent是否听话，只认客观标准。

4.1 校验工具链的选型思路

校验工具的选择要跟团队现有技术栈对齐，不要为了校验单独引入一套重家伙。我的选型原则是三条：

• 能复用现有配置：如果项目已经有ESLint配置，就直接用，别另起炉灶。
• 能给出可操作的错误信息：报错要具体到行和规则名，方便Agent和人都能看懂。
• 能集成到提交钩子：校验必须自动触发，靠人手动跑迟早会漏。

以JavaScript/TypeScript项目为例，我用的组合是ESLint加Prettier，再配一个自定义的规则插件来检查那些ESLint覆盖不到的团队约定，比如“工具函数不能有副作用”这种语义级规则。

4.2 把校验结果反哺给Agent

校验工具跑出错误之后，关键一步是把结果喂回给Agent让它自己修。Pi Agent支持接收外部命令的输出作为上下文，所以我在工作流里加了一个环节：

# 生成代码后自动跑校验 npx eslint src/ --format json > lint-result.json # 把结果作为上下文传给 Agent，要求它修复

Agent拿到lint结果后，会针对每一条报错去改代码。实测下来，一轮修复能解决大约七成的违规，剩下的三成通常是规则冲突或者Agent理解偏差，需要人工介入。

这里有个经验：不要一次性把所有报错都丢给Agent。如果报错超过20条，Agent容易顾此失彼，改了这个忘了那个。我的做法是分批，每次只喂5到8条，改完再跑一次校验，循环直到清零。虽然多跑几轮，但最终质量明显更高。

4.3 提交钩子里的“最后一道防线”

Agent修完之后，还得有一道不依赖Agent的防线。我在Git的pre-commit钩子里挂了校验脚本，任何提交前都必须过。这样即使Agent某次“偷懒”没改干净，也会在提交时被拦下来。

#!/bin/sh npx eslint src/ --max-warnings 0 if [ $? -ne 0 ]; then echo "代码规范校验未通过，请修复后再提交" exit 1 fi

--max-warnings 0这个参数很关键，它把警告也当成错误处理。因为Agent生成的代码里，警告往往比错误还多，如果只拦错误，警告会越积越多，最后规范形同虚设。

注意：提交钩子只在本地的开发环境生效，如果团队有人绕过钩子直接推代码，还是会有漏网之鱼。所以有条件的话，在持续集成环节再加一道同样的校验，双保险。

4.4 校验规则的“版本对齐”问题

这里有个隐蔽的坑：Agent读的规则文件和校验工具用的配置，如果不同步，就会出现“Agent以为合规、校验却报错”的尴尬。比如规则文件里写“函数不超过50行”，但ESLint配置里是80行，Agent按50行写，校验按80行放行，看起来没问题，但团队标准其实已经乱了。

我的解决办法是让规则文件和校验配置共用一份数据源。具体做法是把关键阈值抽到一个JSON文件里，规则文件生成时引用它，ESLint配置也引用它。这样改一处，两边同步更新，杜绝了不一致。

5. 实测中那些规则管不住的“灰色地带”

前面讲的是能靠规则和工具解决的硬问题。但实际用下来，还有一类问题特别难缠——它们不违反任何明文规则，却让评审的人浑身难受。这类“灰色地带”才是真正考验约束方案的地方。

5.1 逻辑正确但“不合群”的代码

最典型的是抽象层次不一致。比如项目里其他模块都是“服务层调仓储层”，Agent却在一个服务函数里直接写了数据库查询。它没违反任何命名或异常规则，但破坏了架构分层。这种问题靠ESLint查不出来，靠规则文件也很难描述清楚。

我的应对办法是在规则文件里加一段“架构约束”，用自然语言描述分层关系，并且给出正反例。比如：

## 架构约束 - 服务层只能调用仓储层和工具层，禁止直接访问数据库连接 - 正例：userService.getUser() 内部调用 userRepo.findById() - 反例：userService.getUser() 内部直接写 SQL 查询

自然语言规则对Agent的约束力弱于硬性规则，但配合正反例，还是能覆盖大部分场景。剩下的漏网之鱼，就靠人工评审兜底。我的心态是：不追求100%自动化，追求的是把人工评审的精力从“抓低级错误”转移到“看架构合理性”上，这本身就是巨大的效率提升。

5.2 Agent的“过度发挥”与“保守不动”

另一个灰色地带是Agent的发挥程度。有时候你让它改一个小bug，它顺手把周围代码重构了一遍，美其名曰“优化”，结果diff大得没法评审。有时候又相反，你让它加个功能，它只加了个空函数，剩下让你自己填。

这两种极端都源于规则里没有界定“改动范围”。后来我在规则里加了一条：

## 改动范围 - 只修改与当前任务直接相关的代码 - 发现无关问题时，在回复中提出建议，但不要直接改 - 新增功能必须完整实现，禁止留 TODO 占位

这条规则加上之后，Agent的diff大小明显收敛，评审负担小了很多。特别是“发现无关问题只提建议不改”这条，避免了很多“顺手重构”引发的争议。

5.3 规则冲突时Agent怎么选

当两条规则打架时，Agent的选择往往是随机的，这是最让人抓狂的。比如规则A说“工具函数必须无副作用”，规则B说“缓存读写放在utils里”，而缓存读写本身就是有副作用的。Agent遇到这种场景，有时按A写，有时按B写，完全看运气。

解决思路是给规则排优先级。在规则文件开头明确写：

## 规则优先级 当规则冲突时，按以下顺序取舍： 1. 安全与正确性相关规则 2. 架构分层规则 3. 命名与风格规则 4. 性能优化建议

有了优先级，Agent在冲突时就有了决策依据。虽然不能保证每次都选对，但至少行为可预测了，评审时也能理解它为什么这么选。

5.4 规则文件的“腐化”与定期维护

规则文件不是写完就一劳永逸的。项目在演进，规范也在变，如果规则文件长期不更新，就会出现“规则说的和实际做的不一样”的情况，Agent遵循的是一套过时标准，产出自然越来越偏。

我的做法是把规则文件纳入代码评审范围，任何规范变更都必须同步更新规则文件，并且指定一个负责人定期（比如每季度）review一遍。同时，我会记录每次Agent违规的案例，如果某个违规反复出现，说明规则描述有问题，需要针对性改写。这个反馈循环跑起来之后，规则文件的质量会越来越高，Agent的表现也越来越稳。

6. 一套可复用的落地清单

把上面这些串起来，其实形成了一套可以复用的落地流程。我把它整理成清单形式，方便你对照自己项目的情况逐项落地。

6.1 从零搭建的步骤顺序

不要一上来就追求完美，按这个顺序推进，每一步都能看到效果：

1. 先写最小规则集：只覆盖命名、异常处理、目录约定这三块，控制在300字以内。
2. 跑一周观察违规模式：记录Agent最常犯的错，作为规则补充的依据。
3. 接入ESLint校验：复用现有配置，先只拦错误不拦警告。
4. 加提交钩子：把校验挂到pre-commit，强制生效。
5. 加自查指令：在规则文件末尾要求Agent输出自查说明。
6. 补架构约束和优先级：等基础规则稳定后，再处理灰色地带。
7. 建立维护机制：指定负责人，定期review规则文件。

这个顺序的核心逻辑是先解决高频硬问题，再处理低频软问题。很多人反过来，一上来就纠结架构分层这种难描述的规则，结果基础命名都没管住，得不偿失。

6.2 常见问题速查表

6.3 几个反直觉的经验

最后分享几个我踩坑之后才明白的反直觉点，可能对你有用。

第一，规则不是越严越好。我一度把规则写得极其严格，结果Agent为了遵守规则，生成了一堆过度设计的代码，可读性反而下降。后来我放宽了一些风格类规则，只死守安全和架构红线，整体产出质量反而更高。约束的目的是让代码“合群”，不是让代码“完美”。

第二，人工评审不能省。我试过完全依赖自动化校验，结果发现校验能过的代码，在可维护性上依然可能很差。自动化解决的是“一致性”问题，解决不了“设计合理性”问题。把人工评审的精力集中在设计层面，才是人机协作的正确分工。

第三，规则文件要写给人看，不只是给Agent看。我后来发现，新同事入职时读一遍规则文件，比读几千字的规范文档上手更快。因为规则文件是被Agent“逼”着写具体的，没有空话套话，反而成了最好的团队规范入门材料。这个意外收获，算是约束Agent过程中的额外红利。

整套方案跑下来，我们团队AI生成代码的一次性评审通过率从最初的三成左右，提升到了七成以上，剩下三成主要是架构层面的调整，属于正常的人工介入范围。更重要的是，评审时的争论从“你怎么又用console.log”这种低级问题，转移到了“这个抽象是否合理”这种有价值的讨论上。如果你也在为AI代码的规范问题头疼，不妨从最小规则集开始试起，跑上两周，应该能看到明显变化。