企业官网建设流程全解析

直接开门见山说个现象：最近各大群里聊AI编程，满屏都是“Cursor写了个接口贼快”“AI把我老代码重构了，一跑直接OOM”。但问十个用AI写Java的人，九个都遇到过同一个问题——小需求AI秒出活，业务一复杂，AI就给你编出根本不存在的类、凭空造方法、接口设计得让人血压飙升。原因很简单：你把AI当成了“一个懂Java的高级外包”，但它没人告诉你需求全貌，也没规则约束，更没人给它做架构评审。这不是AI不行，是你的工程方法不对。

这套东西我按标题里说的三件套拆完，亲测跑了几周：Spec规约解决“AI不知道干什么”，Agent Harness规则解决“AI怎么干活不被带偏”，架构评审标准解决“AI干完活怎么验收”。三件套叠起来，AI写Java代码的可用性，至少从“玩具水平”提到“能进代码评审”的程度，而且不依赖具体哪款AI工具——你在IDE插件、命令行Agent、甚至本地模型上，这套规则都通用。

这篇文章我直接把这套完整方案端出来，包括每条提示词怎么设计、为什么这么写、实际跑下来踩了什么坑，还有我改过N版的Harness规则脚本和架构评审清单。适合正在把AI编程往真实项目里塞的Java开发者，不管你是自己用还是想沉淀成团队规范，都能直接抄。

1. 核心思路拆解：为什么是“Spec + Harness + 评审”三件套

1.1 单靠一条提示词，为什么必然翻车

先说结论：“帮我写一个用户订单模块”这种提示词，AI能给出看起来完美、但工程上全是坑的代码。这不是概率问题，是必然结果。

原因有三层。第一层，AI是生成模型，它根据训练数据里的“平均规律”生成代码。你只说“订单模块”，它会把见过的订单模块特征全部平均一遍：字段叫orderId、status、createTime，接口有createOrder、cancelOrder、queryOrder，可能还给你加个没用上的设计模式。这些代码缝合得越“标准”，离你的真实业务越远。

第二层，Java工程和其他语言不一样，它的复杂度大头在类型系统、Spring容器、依赖管理、事务边界、异常体系上。AI单独看每个方法写得都对，但方法之间的协作、事务切面会不会拦截某个内部调用、懒加载会不会在序列化时炸掉、泛型擦除会不会让某个重载失效——这些“跨方法、跨类、跨层”的东西，单条提示词根本管不到，AI也看不到全貌。

第三层，也是最隐蔽的：AI没有“拒绝权”。你让它写代码，它会假设你说的就是全部需求。你没提事务，它就默认不需要；你没提并发，它就默认单线程；你没提幂等，它就默认调用方永远不会重试。而真实项目里，这些“你没提的东西”恰恰是上线才炸的雷。

所以，你需要把“需求、约束、验收”三件事前置给AI。Spec规约干的就是这件事。

1.2 Spec规约：把“脑子里想的”翻译成“AI能执行的”

我最初犯的错是写长篇大论的“需求文档”塞给AI，什么背景、目标、用户故事都写上，结果提示词又臭又长，AI照样瞎写。后来总结出来，Spec规约的精髓是去叙述化、去歧义化，只需要事无巨细地写清楚下面几层东西：

• 输入/输出契约：方法签名、参数类型、返回值、异常抛出。Java特有的：DTO/VO/PO怎么区分，用什么注解，序列化规则是什么。
• 状态与流转：实体的状态字段有哪几个值，什么条件下允许什么迁移。这个你不写死，AI就会自己发明状态机，而且大概率是错的。
• 约束与边角：哪些字段必填，哪些字段必须唯一，并发控制策略是什么，事务边界在哪里，操作是物理删除还是逻辑删除。
• 成功/失败语义：接口返回什么算成功，什么情况抛什么异常，错误码怎么编排。这决定AI会不会在业务失败时也返回200然后塞个errorCode，还是直接500。

说白了，Spec规约就是把“验收标准”和“契约”先钉死。AI拿到这份规约，它的自由度被约束在“怎么实现”上，而不是“设计成什么样”上。工程里最贵的部分不是编码，是设计决策，Spec就是把关键的决策先替你定掉。

1.3 Agent Harness：控制AI在代码库里的“行为边界”

有了Spec，AI知道“做什么”了。但还有一个致命问题：AI在真实工程里是“乱逛”的——它会顺手改掉你的pom.xml，因为“觉得某个版本太老”；会在写一个工具类的同时“顺手优化”你另一个私有方法；会在不确定某个API用法的时候，自己编一个出来，然后假装它能编译通过。

这就是Agent Harness要管的。Harness的本意是“套具、操控装置”，在AI编程语境下，它是一套约束Agent行为的规则集和工作流框架，不直接生成业务代码，而是生成“Agent接下来可以碰什么文件、不可以碰什么文件、每一步之前必须先做什么、完成到什么程度才可以交付”这些行为边界。

标题里的“Agent Harness规则”，核心就是两件事：文件访问边界和步骤执行纪律。

文件访问边界解决的是“AI别乱改代码库”。你要明确告诉它：这个任务是新增代码，只允许新增在哪个包下，既有文件只读不改；这个任务是重构，只能改动哪些类，测试类不允许动；所有涉及数据库变更的，必须先给你看SQL脚本，等确认再执行。

步骤执行纪律解决的是“AI别跳跃式干活”。我见过最让人崩溃的场景：让AI写一个接口，它5秒后返回结果，打开一看，Service、Controller、Mapper、XML、DTO全给你写完了，但运行起来，Mapper的XML里namespace配错了，Controller没加@RestController，Service里事务注解漏了——从头错到尾，还错得特别均匀。后来我把步骤拆死：先给实现方案，再写接口定义，再写实现类，每一步都要进行编译验证，通过了才能进入下一步。有了这个“纪律”，AI的“自信”会被大大压制，开始老老实实干活。

1.4 架构评审标准：不让AI既当运动员又当裁判

AI写完代码，绝大部分人不会认真审查，看能编译、测试大概通过就收了。但AI生成代码的“表面正确”是极具迷惑性的。

最典型的问题：逻辑正确，结构崩坏。AI为了让“当前这个方法”看起来正确，会在一个类里堆上千行；为了让逻辑“好理解”，会复制粘贴大量重复代码；为了方便“测试”，会把依赖全怼到构造函数里，Setter一堆暴露，结果就是维护噩梦。

架构评审标准就是给“验收”立规矩的。它和常规Code Review不一样，评审对象不是“自然语言描述的需求”，而是对比Spec规约逐条核对——不关心AI写得漂不漂亮，只关心它有没有遵守契约、有没有突破边界、有没有引入架构上不允许的依赖关系。

我在这套方案里设计的评审分四层：

• 契约层：所有公开方法的签名、行为是否与Spec完全一致。
• 工程层：是否引入不符合项目结构的依赖，包依赖方向是否逆向（如Controller依赖了Repository），是否存在循环依赖。
• 质量层：重复代码率、异常吞掉率、资源释放、并发安全性。
• 领域层：业务规则是否被绕开，比如“订单超时未支付自动关闭”这种定时任务逻辑，是不是被AI塞进查询接口里了。

评审标准前置很重要——它在Spec阶段就定义好，AI写代码前就知道“什么叫验收通过”。这比写完代码再拿标准去卡，效率高得多，因为大部分不合规点AI在写的过程中就直接避开了。

2. 全套提示词与配置实录：直接可复制的方案

2.1 Spec规约提示词模板

这块我打磨了很久，目前用的版本长这样。不建议只发一次，建议以系统提示词或项目级文档形式挂载，让AI在做任何任务前都先读一遍。

【角色设定】 你是一个Java技术专家，擅长根据Spec规约编写高质量的生产级代码。 在写任何代码之前，你都必须先阅读理解Spec规约，并逐条确认无歧义。 【Spec规约定义】 以下是本次任务中必须遵守的规格说明。如果规约中有任何不清楚的地方， 你必须先向我提问确认，禁止自行假设后编码。 1. 业务目标：{在这里写清楚这个模块/接口要解决什么问题，最多五句话} 2. 输入契约： - 方法签名：{例：OrderResult createOrder(CreateOrderRequest request)} - 参数说明：{例：request.userId不能为空，request.items不能为空，且items.size>=1} - 预期异常：{例：参数非法抛IllegalArgumentException，库存不足抛StockNotEnoughException} 3. 输出契约： - 正常返回: {例：OrderResult包含orderId, orderStatus, totalAmount} - 错误返回: {例：系统异常统一包装为ErrorResult，错误码以A-开头} 4. 状态流转规则：{说明实体状态有哪些，什么操作把状态从什么变成什么，哪些是非法流转} 5. 数据约束： - 唯一性约束：{如订单号全局唯一} - 边界条件：{如金额必须大于0，小于等于999999.99} - 并发要求：{如库存扣减必须使用悲观锁或乐观锁} 6. 事务与副作用规则： - 哪些操作必须在一个事务里 - 哪些操作不能在事务里调用远程服务 - 是否允许写日志，日志级别要求 7. 建议实现方案：{这一步可选。如果我有明确的实现倾向，就写清楚；如果没有，留空让AI给方案}

你可能会问：为什么要搞这么固定格式？直接对话说不也一样吗？区别在于：自然语言对话，AI理解到的约束散落在上下文里，后面写代码时很容易“遗忘前面说过的一句话”。而固定模板相当于“契约绑定”，你在Spec里声明过的东西，AI会当作约束处理，而不是当背景知识处理。

2.2 Agent Harness规则脚本实例

Harness规则是我迭代最痛苦的环节。AI编程工具大多有自己的Agent模式，比如Cursor的Agent、Codex的Agent模式，但默认规则偏通用，不管你的工程结构。我自己写的这套Java专用Harness规则，核心是三大纪律。

纪律一：文件访问边界

【文件访问边界规则】 1. 只读文件目录：src/main/resources/、src/test/resources/、docs/、.github/ ——这些目录下任何文件，未经确认禁止修改。 2. 可读可新建目录： - src/main/java/{当前业务包根} - src/test/java/{当前业务包根} ——只允许在本次任务指定的包根下新增或修改文件。 3. 禁止触碰目录： - pom.xml、build.gradle（除非任务明确声明需要改依赖） - src/main/java/config/、src/main/java/common/ 下的公共配置和基类 - 任何Name以Test结尾的文件（除非任务明确要求写测试） 4. 任何需要修改上述禁区的操作，必须先打印“潜在违规操作”并等待确认， 未经确认直接修改，视为违规。

这条规则的背景特别真实：我踩过AI改我pom.xml，把Spring Boot版本从3.x悄悄降到2.7，因为“AI训练数据里2.7的例子更多”；也踩过AI把我一个公共的HttpClient工具类“优化”了一下，优化完，另一个没在本次改动范围内的服务直接编译失败。

纪律二：步骤执行顺序

【步骤执行纪律】 每次任务按下列固定步骤执行，每一步都必须在完成后输出结果，才能进行下一步： 1. 理解与确认（Step 1）： - 阅读Spec，用自己的话复述业务目标与关键约束 - 列出你需要修改/新增的文件清单 - 明确是否有歧义点并提问 2. 方案设计（Step 2）： - 输出类结构设计，包含类名、职责、关键方法签名 - 输出涉及到的数据库表变更SQL（如果有） - 等待确认后才能进入下一步 3. 编码实现（Step 3）： - 按包顺序实现，优先写接口定义，再写实现类 - 每写完一个文件，都检查该文件是否可以被正确编译 - 所有编译错误立即修复，修复后列出修复记录 4. 自测（Step 4）： - 写出简单的自测代码（main方法或JUnit均可） - 执行测试，给出测试结果 - 若无法执行（缺环境、缺依赖），必须说明原因 5. 最终交付（Step 5）： - 汇总本次新增/修改的文件清单 - 输出变更说明，包含影响范围与潜在风险

为什么要这么“机械”？因为AI在自由巡航时，最常见的翻车是跳跃执行：需求理解还没有确认，就开始改代码；方案设计是错的，但代码已经写了一堆，推倒重来成本极高。固定五步后，AI每一步都“说人话、给人看”，就算它中间有错，你也早发现早纠偏，而不是等它写完全部才看到灾难现场。

纪律三：输出风格与代码规范

【代码风格规范】 1. JDK版本：以项目实际配置为准，默认JDK 17+。 2. 禁止Lombok：不要在实体上使用@Data/@Builder。 3. 命名规范：类名名词，方法名动词；布尔方法以is/has/can开头。 4. 异常处理：禁止catch后静默吞掉，禁止catch后只打日志不抛；不得catch Throwable/Error。 5. 空值安全：所有外部参数与方法参数必须做null判断，返回不允许null集合。 6. 格式化：采用项目已有格式，缩进为4空格。 7. 约束优先：优先使用javax.validation注解做参数校验，不手写if判断。 8. 依赖方向：Controller不能直接依赖Repository/Mapper，遵循分层架构。

这里特别说下“禁止Lombok”这条，很多人可能觉得我在抬杠。实际上，我在团队里推AI编程时，最先遇到的就是Lombok问题：AI生成的@Getter/@Setter用的贼欢，但它不知道项目里的Lombok插件在编译环境里没配好，或者实体类需要自定义getter逻辑的，它也只会一味加注解。这种“团队技术栈上没有的东西AI乱用”的情况非常普遍。所以我把这类“千行代码能用但不符合团队规范”的点全部列成硬约束，让AI没法钻空子。

2.3 架构评审标准的完整清单

AI交付代码后，评审人群的区分点在于：新人评审只看“能不能跑”，架构师评审看“改了会不会炸”。我的评审标准专门设计成五张清单。

清单一：契约一致性核对表

这个表格是评审时最优先去看的，直接拿Spec逐条对。

清单二：依赖与结构审查项

清单三：质量与隐患扫描项

清单四：领域逻辑与业务规则审查项

清单五：可测性与可维护性

3. 实操过程：从零到一跑通一次完整AI编程交付

3.1 准备环境：选定工具与挂载配置

先说我现在的常用组合：Cursor的Agent模式+命令行Codex辅助（CLAUDE.md方式挂Harness规则），或者如果是在纯命令行环境，就把Harness规则写到项目根目录的AGENTS.md里让工具自动读取。目前主流AI编程工具都支持项目级规则文件，所以这套方案对工具其实不挑。

具体做三件事：

• 项目根目录创建一个SPEC.md，把Spec规约模板按当前任务填好。
• 项目根目录创建一个AGENTS.md（或你所用工具对应规则文件），把本文第二节的“文件访问边界”和“步骤执行纪律”贴进去。
• 项目根目录创建一个ARCH_REVIEW.md，把五张评审清单贴进去，作为任务完成后的验收标准。

这个做法的好处是：这些文件本身纳入版本管理，团队其他人clone下来也能直接复用同一个规矩。而且当Agent在上下文中看到这几个文件时，它的“行为模式”会立刻切换——从一个“写代码的模型”变成一个“遵守项目纪律的工程师”。

3.2 示例流程：让AI实现一个“优惠券核销”接口

用一个贴近业务的例子走一遍，让大家看看三件套是这么互相配合的。

第一步：填Spec规约

我在SPEC.md里写清楚以下内容要点：

• 业务目标：核销一张优惠券，扣减一次使用次数，记一条核销流水。
• 输入契约：CouponUseResult useCoupon(CouponUseRequest request)，参数包含couponId、orderId、userId，三者均不能为空。
• 输出契约：正常返回核销信息；优惠券不存在/已过期/已被使用/不属于该用户，分别抛不同业务异常。
• 状态流转规则：优惠券状态有UNUSED、USED、EXPIRED、DISABLED，只有UNUSED允许流转到USED，其余流转非法。
• 数据约束：核销必须幂等——同一orderId对同一coupon只能核销一次；金额精度用BigDecimal；所有数据库操作在同一事务内。
• 事务规则：禁止核销事务内调用远程接口；禁止catch后吞异常。

第二步：Agent按纪律执行

按Harness规则，Agent执行Step 1时，先用自己的话复述需求，然后提问：“订单状态是已支付才能核销吗？还是创建就能核销？”——这个问题很关键，因为Spec里确实漏了，AI能识别出来并问，而不是自己拍脑袋默认“必须支付成功”，说明Spec搭配“有疑必问”的步骤纪律，确实能提升AI追问意识和确认习惯。

Step 2方案设计它输出后，我扫了一眼，发现它想把优惠券表、核销流水表都设计成一个字段超多的“大宽表”，我直接在方案阶段拦下来了，让它拆成用户侧查询和运营侧查询分开的字段结构。这个调整放在以前“直接生成代码”的模式下，AI已经写好几百行再让你推翻了。

Step 3编码实现时，由于Harness里规定“每写完一个文件必须检查编译”，我观察到AI在多文件场景下，编译错误的自我修复率明显高了。以前一气呵成写10个文件，最后由30个编译错误集中爆发；拆步骤后，基本每次只爆发一到两个错误，而且是前一个文件修完了才写下一个文件，错误不会滚动累积。

第三步：跑架构评审

编码完成、自测通过后，我拿着ARCH_REVIEW.md的五张清单逐条核对。实际发现的问题相当典型，写出来给大家参考：

• 契约一致性：发现AI把正常返回的CouponUseResult里多塞了一个couponName字段。这本身没什么，但成功后AI有个隐蔽做法——它自作主张把错误响应里的错误码统一加了个“前缀”，这和前端对错误码的解析规则不一致。如果没有契约核对表，这个坑会直接流到联调阶段，还是那种特别难定位的“对不上字段”的坑。
• 依赖与结构：发现AI在Service里直接注入了CouponMapper并直接做查询，绕过了我设计的Repository层。这个如果不抓，后续所有类似代码都会效仿，分层结构直接烂掉。
• 并发安全：检查扣减次数的代码，发现AI用的是“先select再update”的检查型写法，没有加锁，也没用乐观锁版本号。这在低并发下不会出错，但压测一上就必炸。我要求改用UPDATE ... WHERE used_count = ?的CAS写法并返回影响行数，AI修改得很快，因为Spec里的“并发要求”字面上满足，实际上需要评审来发现实现不符合高并发场景。

这个示例大致就是完整过程。你会发现，最容易出质量问题的三个环节分别是方案设计时的数据模型粗心、编码时的越层依赖和高并发场景的安全意识。这三个都不是“编译错误”，而是“架构错误”。架构评审清单存在的意义，就是专门抓架构错误。

3.3 与人协作的“提示词管理”技巧

这套方案用顺之后，我强烈建议你把“提示词本身”当成代码一样管理——版本化、评审、回滚。我在团队里推了一套简单流程：

• 每一条新的提示词模板，先在小项目里试三次，记录翻车点，再迭代入模板库；
• 模板库用Git管理，每次改动必须写commit message说明“为什么改”；
• 模板库里每条规则都必须注释“解决过什么问题”，防止后人看不懂就删掉。

比如我在Harness规则里那条“每写完一个文件必须检查编译”，注释里就写着：“解决AI一次性生成多文件时，同名导入冲突和编译错误滚雪球问题”。有理由的规则，维护者才愿意留。没理由的规则，早晚被当垃圾删掉。

4. 常见问题与排查技巧实录：填平AI编程的那些坑

4.1 问题速查表

参考了社区里大量讨论，以及我自己跑下来的高频问题，整理成表。

4.2 高频翻车点实录

翻车一：AI自己造了一个“不存在但看起来合理”的Spring注解。

有一次让它实现一个定时任务，它直接在方法上加了个@Scheduled(cron = "...")，但项目里根本没有启用@EnableScheduling。它没查配置，也没问，核心业务倒是实现了，但定时任务从头到尾没跑过。后来Harness规则里加了“状态确认”这一步：“写任何需要配置类支撑的注解前，先确认项目里是否已有相关开关配置”。

翻车二：AI把“业务正确”与“代码正确”混为一谈。

有次让它实现“优惠券已使用则不能再次核销”，它写的代码在单线程下看起来没问题，但并发请求同时进来，两次请求都通过了“检查状态”这行代码，然后双双更新了数据库。这完全可以用乐观锁解决，但AI就是不会主动“预防未来”，因为它没见过你的压测报告。架构评审里的并发安全这关就是为这个专门设置的。

翻车三：AI特别喜欢“过度设计”。

模块只有一个接口，三个实现类，硬套一个策略模式，还加了一个AbstractFactory。你问它为什么，它的回答是“为了可扩展性，将来可能有更多实现”。这句话听着耳熟吧？跟刚入行的同事写代码一个毛病。架构评审里有一条：“如果当前只有一个实现类，禁止引入接口+S实现+工厂三件套，等第二个实现出现再说”。这条能帮团队省下来大量无谓的抽象和阅读成本。

4.3 我的改进心得

这套方案迭代到当前版本，最大的几个变化：

• 最早版Harness规则我写得像“宪法”，几十条规则密密麻麻，结果AI频繁违反，因为上下文太长它记不住。现在改成三个纪律，每条纪律下最多三到五条子规则，简洁到AI能在每次任务开头把它完整读一遍。规则数量过载比没有规则更糟糕。
• Spec规约从“写一段话”变成了“填表格”。AI对结构化信息的遵从度远超对叙述性文字的遵从度。这可能和训练数据里“接口文档都是结构化格式”有关。
• 架构评审从“凭感觉看”变成了“核对表勾选”。这个最重要，因为AI输出的东西，你盯着看会“顺眼”，但用核对表去查的时候，很多问题就自己浮出来了。

最后说一个最拗但最有效的习惯：每次让AI交付完成后，追问一句“你这次自己对照Spec检查过哪些内容？还有哪些没检查？”别看它答案可能是“检查了契约一致性，没检查并发安全”，这句话的价值是让AI把自我评估的黑盒过程变成白盒过程，你可以直接基于它的回答去做二次检查。这个做法，是我这段时间用下来，性价比最高的一个举动。

如果你现在项目里也在用AI写Java，真心建议你别再“裸奔”式提问了。把Spec、Harness和评审清单拉到项目里，跑一个完整任务对比试试，体感差异会非常明显。后续如果你们团队有什么好使的新规则，也欢迎交流，这套东西本来就是越迭代越有生命力。