企业官网建设流程全解析

1. 当AI进入你的代码仓库：先别急着谈生产力

先抛一个我自己的真实经历。团队引入AI辅助编程之后，头两周效率确实肉眼可见地提升，简单CRUD接口、单元测试、DTO转换这类“体力活”基本不用人工上手。但到了第三周，问题开始密集出现了——有人把AI生成的数据库连接串直接提交到了公开仓库，有人用AI重构了一段加解密逻辑但是把初始化向量写死成了全零，更有意思的是，同一个模块的三个不同文件，分别出现了三种截然不同的日志格式。那一刻我意识到：AI就像一个精力充沛但毫无经验的实习生，你让它放手去干之前，必须先给它一本完整的行为手册。

这个“行为手册”，就是标题里说的“给AI制定的代码规范”。它不是一份普通的编码风格指南，而是一套面向AI工具、AI辅助编程助手、自动化编码Agent的完整约束体系。核心目标只有一个：在享受AI效率红利的同时，把它的不确定性关进规则的笼子里。

有人可能会想：AI不是可以自动遵循项目的.editorconfig、ESLint配置吗？还需要专门给它定规范？这个想法大方向上没错，但现实远比这复杂。大家用得比较多的AI编程工具，往往能识别仓库里的配置文件，但这只能解决“代码长什么样”的问题，解决不了“什么能写、什么不能写、写到什么程度可以提交”的问题。举个最简单的例子：ESLint只能检查出变量定义了没用，但不能告诉你“这笔金额计算涉及资金安全，必须走财务模块封装好的接口，不得自行实现浮点运算”。而这一类语义层面的规则，恰恰是AI最容易踩坑的地方。

所以，这份代码规范本质上是给AI划定一个“能力边界”和“行为准则”。它配合工具链里的lint、测试、CI检查一起使用，各管一段。我的经验是，规范文本主要管住“AI不能做什么”和“AI应该怎么做”，工具链负责“AI做得不对时如何打回”。两者结合，才能真正让AI稳定输出高质量代码。

这篇文章我不会给你讲纸上谈兵的大道理，而是把我自己在项目中制定的这份AI代码规范，从设计思路、核心条目、落地方式到踩坑实录，完完整整拆开讲。无论你现在已经在用AI编程，还是正准备引入，这份规范都能直接拿来改改就用。

2. 为什么通用代码规范管不住AI：先搞懂AI犯错的底层逻辑

2.1 AI不是“会写代码的程序员”，而是“会补全上下文的概率模型”

要制定有效的AI代码规范，第一件事是纠正一个认知偏差：不要用管人类程序员的方式去管AI。

人类程序员读代码规范，理解的是“为什么”——为什么这里要用LRU缓存而不是简单的HashMap，为什么日志里不能打用户密码。即使规范没写全，一个有经验的开发者也能靠领域知识推断出该怎么做。AI不一样。它的工作方式是基于上下文做概率预测，给它看什么它就更倾向生成什么。如果团队里没有明确写出“金额计算统一使用BigDecimal”，AI极大概率会在新代码里用double，因为训练数据里75%的同类代码就是这么写的。

所以我制定规范时的第一原则是：把潜规则变成显式约束。团队默认“所有人都知道”的东西，恰恰是AI不知道的。规范的核心部分，不是怎么缩进、怎么命名，而是把所有沉淀在资深开发者脑子里的“工程判断”一条条写清楚。

2.2 AI在代码审查环节的“幸存者偏差”

另一个有意思的现象是，AI生成的代码会存在一种“看起来都对”的错觉。它们的代码风格可能完全符合项目里的ESLint规则，函数命名也符合驼峰命名法，注释写得比人写的还规整。但如果你仔细审查边界条件，会发现大量“默认输入合法”的假设。

我印象很深的一次：让AI生成一个文件上传功能，它用了几分钟就写出了完整代码，文件类型校验、大小限制、错误处理全都有。但审查的时候我注意到，它是直接用原始文件名拼接到存储路径里的，完全没考虑路径穿越攻击的问题。这类安全敏感点，通用规范里很少会具体写到，但AI的错误率相当高。

这背后的原因在于：AI的训练数据里，大量“简单示例代码”都是省略了安全处理的。它补全出来的内容，统计上更接近“大多数普通人的写法”，而不是“符合你们团队安全标准的写法”。所以，规范里就必须额外开辟一块安全边界的内容，把AI默认不会做、但项目里必须做的事情讲清楚。

2.3 规范不只是给AI看的，更是给人机协作流程定的

最后还要想清楚一个立场问题：这份规范是不是只约束AI？我实践下来不是。它实际上规范的是整个“人机协作流程”。

因为AI生成的任何代码，最终责任人是提交它的工程师。规范必须明确：哪些环节必须人审、哪些步骤允许AI独立完成、什么情况下可以信任AI输出、什么情况下必须打断。这不是对AI的不信任，而是对工程质量的基本尊重。把流程定义清楚之后，好处是双向的——人知道自己在什么节点该切入，AI也能在最大自主空间内干活。

我在规范的第一页就写着：本规范约束的对象，是所有AI辅助编码工具（如自动补全、代码生成对话、智能Agent）在参与本项目开发时的行为，以及开发者在使用这些工具时的操作流程。

3. AI代码规范的核心设计：五个维度一个都不能少

3.1 边界维度：明确AI“能做什么”和“绝不能做什么”

这是整个规范里最重要的部分。我在设计时把所有开发任务分成三个区间：允许AI独立完成、AI辅助人类完成、完全禁止AI参与。

允许AI独立完成的任务，一般是低风险、高模式化的工作。比如，为已有函数补充单元测试、生成VO/DTO之间的转换代码、编写简单的CRUD接口、根据注释生成工具函数等。这些任务即使AI写得有瑕疵，后果也可控，代码审查能轻松兜住。

AI辅助人类完成的任务，是需要人主导、AI当助手的场景。典型代表是模块重构。这个时候，AI负责分析调用关系、生成重构建议方案，但最终的拆分逻辑、接口设计必须由人拍板。还有一个常见场景是代码解释和排查问题，AI可以帮忙梳理调用链、做个初步的根因分析，但修复动作必须人来做。

完全禁止AI参与的任务，我用红色标注了：涉及密钥和凭证的代码、加解密实现、支付和金额计算逻辑、数据迁移脚本、用户隐私数据处理、权限控制核心。这些领域一旦出错，损失不可逆，而且AI生成的代码往往“看起来没问题但经不起推敲”，风险系数太高。比如密钥管理，AI很容易生成硬编码的密钥，这在开发测试阶段问题不大，但一旦误提交几乎就是安全事故。

3.2 上下文维度：让AI“说人话”的提示词工程来兜底

有了边界，接下来要解决“怎么让AI每次生成代码前都记住规矩”。我的方案是：在项目根目录维护一份特殊的规范文件，用AI最擅长理解的Markdown结构化格式书写。文件命名为AI_CODING_RULES.md，固定在项目根目录，确保AI在读取上下文时可以自动加载到。

这份文件不能太长，我压到50行以内。太长AI会“选择性地遗忘”，关键信息反而抓不住。结构上采用极简的“正/反”清单形式：

# 项目AI编码规则 ## 必须遵守 - 金额相关计算一律使用BigDecimal，禁止使用double/float - 所有日期操作使用Java 8+ Time API，禁止使用SimpleDateFormat - 日志使用SLF4J门面，禁止直接使用log4j/Log4j2的API - 对外接口入参一律使用DTO对象，禁止直接暴露实体类 - 数据库操作必须走MyBatis-Plus内置方法或自定义Mapper，禁止JdbcTemplate混用 ## 禁止事项 - 禁止在代码中硬编码任何密钥、Token、数据库连接串 - 禁止引入项目依赖中不存在的第三方库 - 禁止使用Thread.sleep进行异步等待，使用async工具或消息队列 - 禁止在循环中调用远程接口或执行SQL

这份文件同时还会作为AI辅助工具的system prompt注入，双保险。在各家AI编程工具里都可以设置项目级自定义规则，指向这个文件即可。

另有一个关键点，规范文件里的每一项都必须“可检查”，不能写模糊感受。比如，“代码质量要高”这种话等于没说，AI不知道具体怎么做是“高”。而“金额计算用BigDecimal”就是可检查的，团队成员也知道怎么在代码审查时对照。

3.3 技术栈维度：锁死依赖，防止AI“自由发挥”

引入AI之后，一个非常头疼的问题就是它会自由发挥引入新依赖。有一次我在审查AI生成的Excel导入功能时，发现它自动引入了一个POI的封装库，功能确实好用，文档也齐全，但这个库的出现意味着项目多了一个需要维护的第三方依赖，而且和团队自研的基础组件功能重叠。这不是一个简单的“这个库能不能用”的问题，而是项目治理的问题。

所以规范里专门有一条：AI生成的代码中，凡涉及新增第三方依赖，必须由人工确认并走依赖引入评审流程，AI不能自行在构建文件中添加依赖坐标。不过这条规范在实践中遇到了新的挑战——很多AI工具为了追求效果，会自动帮你改构建文件并添加依赖。因此我们不得不在更底层做限制：在CI配置里增加依赖白名单检查，发现新依赖直接构建失败。当AI发现添加依赖这条路被“物理性堵死”之后，它会主动改用项目已有的工具类实现，这比任何提示词都管用。

技术栈锁死的另一个维度是框架版本。上下文不同，AI补全的API可能属于完全不同的版本。比如在Spring Boot 2.7的项目里，它经常补出3.x才有的新方法。规范里我会写明通用配置文件位置和版本约束，要求AI在生成代码前先查看项目构建文件的版本信息。

3.4 架构维度：强制分层，让代码待在它该待的地方

代码架构是AI最容易搞砸的地方。人类程序员写代码时脑子里有分层意识——Controller层只做参数接收和响应封装，Service层只做业务逻辑，DAO层只做数据访问。AI没有这个意识，它纯粹在“最小上下文窗口”里做题，经常把业务逻辑直接写在Controller里，或者在Service里直接new一个Mapper。短期看功能是通的，长期必然变成一座活火山。

我在规范里固定了几条架构硬约束：

• 禁止在Controller中出现业务逻辑，只能调用Service并做响应转换
• 禁止在Service层出现SQL语句或查询条件封装，应下沉到DAO层
• 禁止跨层调用，Controller不允许直接注入Mapper
• 涉及外部接口调用的逻辑必须统一走独立的Client类，禁止散落各处

这类约束在实际落地时经常遇到AI工具不听话的情况。毕竟架构约束不像“用BigDecimal”那样是单一代码层面的规则，它需要AI理解一个类在项目里的“角色”。我的办法是在规则文件里加一条硬要求：“生成代码前先查看目标目录的包结构，确认类所属层次”。同时在审查时把“分层是否清晰”列为第一检查项，一旦发现越层直接打回。

3.5 测试维度：不能让AI只“写功能”，不“写验证”

最后是测试。AI最让人省心也最让人担心的地方，是它几乎不排斥写测试。让它写单测，它能给你洋洋洒洒生成几十个用例。但问题在于，它写的测试通常都是“证明代码能跑”的测试，而不是“证明业务逻辑是对的”的测试——大部分断言都在验证正常路径的返回值，而极少覆盖异常分支和边界条件。

规范里的测试要求有三条：

• AI生成的功能代码，必须同时生成对应的单元测试，测试代码和功能代码一起提交
• 测试用例必须覆盖正常路径、异常路径、边界条件三个维度，缺失任一维度需要补充
• Mock外部依赖时，必须验证关键交互参数，而不只是mock后返回固定值

我在实际执行时发现，让AI写边界测试是最划算的——它对“极端但合法”的输入往往能产生意想不到的思路，而人最容易忽视的恰好就是这类场景。比如为空字符串、最大长度、时区影响、闰年2月29日等。这些用例如果靠人写，容易陷入思维定式，AI反而能补盲。

4. 不只是“规则文本”：把AI规范固化到工具链里的实操方案

4.1 规则文件如何组织才能被AI稳定读取

规则文件是整份规范的载体，组织方式非常有讲究。比例失衡会让AI抓不住重点，过于冗长它会按照“统计概率”选择性遗忘。我的做法是“金字塔式”三层结构：

第一层，项目级AI编码规则（AI_CODING_RULES.md），50行以内，包含“必须遵守”和“禁止事项”清单，这份文件是最高优先级，任何AI生成代码前都必须读取。

第二层，技术栈与架构说明（TECH_STACK.md），200行以内，包含项目技术栈版本、分层架构约定、模块职责说明。这份文件供AI理解项目全貌，适合在让AI参与较大模块开发时引用。

第三层，具体模块的领域知识文档，放在对应目录下（如ORDER_SERVICE.md），描述该模块特有的业务规则、常见坑位、不可变约束。这部分只有在AI处理该模块时才会被引用。

三层文件的逻辑关系是：第一层是“法律”，强制执行；第二层是“宪法”，指导方向；第三层是“案例库”，辅助理解。实际使用中，AI工具到底能不能自动加载这三份文件，取决于你用的工具类型。有些工具会自动读取项目根目录的Markdown文件，有些不支持。我用的组合是一部分依赖工具自身的文档加载功能，一部分在对话时手动@指定文件。这块没有统一标准，常见做法是把规则文件内容嵌入到AI工具的“自定义指令/系统提示”配置项里，保证每次对话都生效。

4.2 CI流水线：让规范校验从“自觉”变“强制”

规则写好了，AI也可能不执行。人的记忆会衰减，AI的概率模型更难保证稳定。所以CI阶段必须有一道强制的“物理防线”。

我在流水线里接了三道检查：

第一道是风格与静态检查。ESLint、Checkstyle、golangci-lint这类工具在原有配置基础上，增加了一组专门针对AI生成代码常见问题的规则。比如禁止硬编码密钥的正则检查、禁止过时API调用检查等。

第二道是依赖白名单检查。前文说过的，AI自己加依赖会导致构建失败。这块用脚本实现，解析构建产物中的依赖列表，与项目锁定的白名单比对，不在白名单里直接fail。

第三道是AI生成代码标识检查。要求开发者在提交信息里注明哪些文件是AI生成的（例如带上[ai-gen]标记），CI根据这个标记对相关文件做更严格的检查项。这个看起来像形式主义，实际价值很大——它让“AI参与度”可度量、可追溯，后面会细说。

注意：第三道检查最好做善意提醒而不是强制拦截，否则开发人员会有逆反心理，刻意去掉标记，反而让数据失真。我的经验是：标注出自AI代码的提交，审查优先级提高；标注的开发者，每周可以得到AI协作效率的数据反馈。正向激励比负向惩罚效果好得多。

4.3 给AI配几个固定搭档：从“一次性生成”到“可复用流程”

代码规范文档只是“静止的规矩”。真正让我体会到质变的，是把AI的工作流从“一次生成完事”改造成“固定角色分工”的模式。我在项目里配置了四个固定的AI Agent角色：

• 代码审查员Agent：拿到提交代码后，先检查是否符合AI_CODING_RULES.md，输出违规清单
• 文档生成员Agent：负责为接口生成API文档，为复杂函数生成注释和示例
• 测试补全员Agent：分析已有代码，找出缺失的测试分支，生成补充用例
• 重构建议Agent：在代码审查通过后，分析重复代码和坏味道，给出重构建议

这一套角色分工的好处是，每个Agent的职责单一、上下文聚焦，规范落地更容易。代码审查员Agent的规则文件就是那份50行的AI_CODING_RULES.md，它不需要了解整个业务，看到违反规则的点直接输出警报即可。这样即使主编码Agent偶尔“犯浑”，审查Agent也能把住最后一道关。

这一套角色分工的好处是，每个Agent的职责单一、上下文聚焦，规范落地更容易。代码审查员Agent的规则文件就是那份50行的AI_CODING_RULES.md，它不需要了解整个业务，看到违反规则的点直接输出警报即可。这样即使主编码Agent偶尔“犯浑”，审查Agent也能把住最后一道关。

4.4 从一个人遵守到一群人遵守：规范和知识库联动

规范的落地还有一个隐藏保障——和团队知识库联动。AI是概率模型，它回答“项目里金额用什么类型”这种问题时，可能从训练数据里“见过”类似的项目结构，但并不能肯定你们项目的具体约定。所以我在搭建规则体系时，刻意把规范条目和知识库里的详细文档做了映射。比如规则说“金额计算用BigDecimal”，知识库里就有“为什么不用double”的详细分析文章，包括浮点数表示原理、线上事故案例、替代方案对比。

当AI在对话中触发了某条规则，而开发者想进一步了解背景时，AI工具可以基于知识库内容生成更完整的解释。这种做法既保证了规则的执行力度，又方便团队新人在阅读代码时理解“为什么这么写”，最终让规范从一份“死文档”变成团队共识的载体。我第一次把知识库链接加到规范里的时候，团队里有位老同事说：“这终于解决了‘我按规范写了但又不知道为什么’的痛点。”

5. 规范推不下去？问题很可能出在流程和授权

5.1 没有“否决权”的规范等于白写

规范写得再完备，如果没有配套的裁决机制，AI根本不会怕。这里说的裁决，不是“审查人发现违规打回修改”，而是当AI的行为超出规范边界时，团队有一套响应流程。

举例来说，AI在写某个功能时，发现自己需要调用一个项目里不存在但训练数据里很常见的库。规范要求它“停下来问人”，但AI无法主动停下来。它要么硬着头皮用已有工具实现，要么生成代码后Crash。理想的情况是：AI生成代码不通过CI检查，提交失败，开发者收到报错，然后开发者手动决定是改代码还是调整依赖白名单。这套“AI尝试-检查拦截-人工决策”的闭环，本质上就是给规范装上了“牙齿”。

另一个“牙齿”是代码审查的人工抽查。我们规定了一个硬性比例：AI生成的代码，前25个PR必须100%人工审查；之后可以根据AI的表现动态调整，但抽查比例不低于50%。低于这个比例，你就是在拿生产稳定性赌AI的表现。

5.2 权限精细化：哪些模块允许AI动

不仅是“什么代码AI可以写”，还有“哪些文件AI可以改”。我把项目的目录权限分成了三档：

第一档是AI可自由编辑区，比如测试目录、DTO/VO目录、工具方法目录，这些地方变更影响面小，允许AI独立提交代码。

第二档是AI可辅助修改区，比如Service实现类、Controller层，允许AI生成代码，但必须有人共同修改、确认逻辑。

第三档是AI禁止修改区，包括数据库迁移脚本、核心交易流程代码、权限校验代码、配置中心相关代码。这些目录在AI工具的配置里直接设为忽略，即使AI生成了相关文件也不得保存到仓库。

这个权限分级的价值在于，它把“AI能做什么”从一个模糊的伦理议题变成了工程上的访问控制问题。不需要每个人自觉“不让AI碰敏感代码”，AI工具本身就会自动避开。顺着这个思路，团队内部复盘时能少扯很多皮。

5.3 规范也要版本化：记好每一次修改的原因

最后一条比较容易被忽略：AI代码规范本身也是需要版本管理的。我把这份规范放在独立的Git仓库里维护，每次都走PR流程，每次修改都要注明原因。例如：

• v1.2版本增加“禁止在循环中调用远程接口”，原因是订单批量处理时，AI生成了一段逐个调用库存服务的代码，导致接口响应时间从200ms飙升到15秒。

• v1.4版本新增“所有日期时间必须存储UTC时间戳”的规则，源于一次跨境订单时间错乱事故——AI在生成逻辑时直接用了服务器本地时间，导致美国和欧洲用户看到的订单时间不一样。

版本化的好处是，每个团队成员能清楚看到规范的演进脉络，理解每条规则背后的代价。对新加入的人来说，读规范的过程也是一次浓缩的“踩坑教育”。

6. 踩坑实录：那些规范没堵住的问题

6.1 AI的“过度自信”：不存在的依赖和错误的方法签名

最常见的翻车现场，不是AI写不出代码，而是它写出的代码“看起来完全正确”但实际上编译不过。AI工具的特点是会“模拟”出它认为最可能的API签名，而这个签名在真实环境里可能根本不存在。有一段时间我花了很多工夫在编译错误处理上，因为AI生成的一个加密工具类引用了某个库并不存在的AES-GCM辅助类，而它给出的解决办法是“请添加某某依赖”。

这个问题靠规范文本解决不了，只能靠“编译检查+AI自我修正循环”。现在我们在开发流程里约定了一个硬步骤：AI生成代码后必须先在本地或CI环境执行编译，失败信息反馈回去要求修正。不经过编译验证的AI代码，不允许进入人工审查环节。

6.2 上下文遗忘：长对话里的“记忆衰减”

AI工具处理长对话时，存在明显的“上下文遗忘”现象。对话前20轮还能严格遵循规范，到了第80轮，生成代码的风格和质量就开始漂移了，之前约定的命名规则、异常处理模式都不再稳定。

应对办法是拆分任务，不建议让AI在一次对话里连续生成多个模块的代码。我现在的习惯是：每个功能模块单独开启一次新的对话，每次对话开始时重新粘贴一遍核心规范片段。这个习惯看着麻烦，但在质量上的收益非常明显。

6.3 规范冲突时的“危险沉默”

当AI收到的指令与现有代码出现冲突时，它倾向于“沉默地选一个它认为合理的方案”，而不太会主动提醒。这在工程上是致命的。比如说，项目里的订单号生成逻辑原本是“日期+随机数”，但AI在学习已有代码时发现某个工具类里有UUID的用法，于是自作主张在新代码里用了UUID格式的订单号。单体看新代码完全没问题，但对老系统来说，订单号的格式关联到了数据统计、报表导出、客服查询等多个模块，改格式等于捅马蜂窝。

规范里我加了一条：“当已有代码中的写法与本规范不一致时，以已有代码为准，并提醒开发者确认。”谁来决定？永远是人。AI只有建议权，没有决策权。

7. 度量AI协作质量：用数据判断规范要不要收紧

规范落地两个月后，我建立了一套简单的度量指标，用数据回答“这份规范到底起没起作用”。分享几个核心指标：

• AI生成代码的通过率：AI生成的PR中，一次通过审查的比例。如果这个比例低于50%，说明规范过严或者AI工具和项目匹配度不够。
• 审查返工率：平均每个AI生成PR被要求修改的次数。和人类写的代码对比，看差值是否在缩小。
• 规范违规类型分布：按违规类型统计，比如“依赖新增违规”“硬编码密钥”“分层越界”。这个指标能告诉团队规范里的哪条规则最需要加强或调整。
• 缺陷逃逸率：合入主分支后，AI生成代码中被发现线上缺陷的概率。这是最终的“成绩单”，也是评估整个AI协作模式是否可持续的关键。

用数据说话的好处是，可以避免围绕“AI到底行不行”展开无休止的争论。数据说不行，就去看规范哪里没堵住；数据说行，就适当放宽边界，给AI更大的发挥空间。规范的松紧应该像调PID参数一样，根据系统反馈动态调整，而不是一劳永逸。

8. 当“给AI的规范”变成“团队习惯”：文化建设比文档更重要

到最后，有一个问题想特别说说。我见过不少团队把AI代码规范写完之后，往仓库里一放就再也不看了。原因很简单：大家觉得“自己又不是AI，为什么要读给AI的规范”。这种想法我能理解，但实际上是浪费了规范的最大价值。

一份高质量的AI代码规范，是团队所有隐性工程知识的显性化沉淀。“金额用BigDecimal”背后是浮点数误差的教训，“禁止在循环里调接口”背后是性能问题的血泪，“禁止在Controller里写业务逻辑”背后是架构腐化的痛苦。这些知识一直存在，只是从未被系统梳理成文。给AI写规范的过程，等于逼着团队把脑子里“默认你会懂”的东西写出来，这对人也是极大的提升。很多资深开发者在完成规范文档后的反馈是“从来没想过我们项目里的规矩这么多”。

所以我最后的建议是：不要把AI代码规范单纯看作给工具用的配置文件，把它当成团队工程文化的一次集体反思。执行层面可以靠CI、权限、检查这些工具，但认同层面一定靠人对“代码质量和可维护性”的共同追求。AI是队友还是对手，归根结底取决于你给它划的跑道和共同目标。

如果你正在经历“AI代码满天飞，团队心里都发慌”的时期，试试按这套框架梳理一份你自己的AI代码规范。从50行的规则清单开始，到CI检查落地，再逐步补充上下文和权限控制，你会发现AI带来的不只是效率，还有一次重新审视工程标准的机会。