企业官网建设流程全解析

一、引言：后端研发的效率拐点已经到来

2026 年，后端研发链路正在经历一次根本性的效率拐点。

JetBrains 2026 年的开发者调查显示，1.5 万名开发者中，Claude Code 的使用率从 18% 涨到 39%，九成开发者每周都在使用 Agent 工具，近七成几乎天天用。另一份来自 New Relic 的报告给出了更激进的数据：三分之二的受访组织表示，其 51% 到 75% 的代码已经由 AI 生成或显著重构。

但这些数字背后藏着一个矛盾。同一个 New Relic 调查发现，94% 的技术负责人认为 AI 生成的代码质量“优于”人类手写，然而 78% 的团队报告了生产环境事故的增加，74% 表示至少 25% 的 AI 生成代码需要“显著修正”才能上线。

问题不在于 AI 能不能写代码。问题在于：当代码变便宜之后，研发链路本身需要重新设计。

本文以我们团队过去一年在后端研发场景中的落地实践为基础，覆盖编码、文档、自动化测试三个核心环节，分享一套可复用的工程化方法论。所有经验均来自真实项目，所有踩坑均有据可查。

二、编码环节：从“AI 写代码”到“AI 写对的代码”

2.1 为什么直接让 AI 写代码，十次有八次返工

把“帮我加一个商品管理模块”丢给 Claude Code 或 Cursor，十有八九能跑出一版代码——能编译，接口能通。但打开前端界面，侧边栏没有菜单。或者菜单有了，点进去报 403。或者代码能用，但和项目里其他模块的写法完全是两套风格。

问题不在模型笨。是它压根不知道你的项目现在长什么样。

以 go-admin 为例，这是一个横跨数年的开源后台框架。早期版本里，每个业务模块都要手写 Api 和 Service，一个 Api 至少七个函数。这套写法在 GitHub 上存量大，模型训练时看到的很可能就是这套。但项目现在推荐的是 Actions 模式——一个模块只要三个文件，参数绑定、权限过滤、分页都交给框架内置的通用 Action。

两种写法都能跑，模型不会报错。但项目里两套风格混在一起，统一就是真金白银的返工成本。

真正容易被忽略、而且错了也不会报错的，是另一件事：一个模块要在界面上真正可用，除了代码，还需要往四张表里写正确的种子数据——接口注册、菜单挂载、菜单和接口的关联、权限策略。漏了任何一步，现象都是“看起来一切正常，但界面上要么没有菜单，要么按钮点不动”，没有任何报错提示。

2.2 解法：AGENTS.md + 参照实现 + 结构化 Skill

我们后来总结出一套分层解法，核心思路是：把“隐性知识”变成“显性约束”。

第一层是 AGENTS.md。这是专门写给 AI 编码工具看的约定文件，刻意做得很短，只写“不遵守就会出错”的规则。技术栈版本、命令这些交给 go.mod、package.json 自己说话，避免文档和代码脱节。

第二层是一份可编译、有测试、CI 会跑的参照实现。文字描述会过时，但被 CI 持续验证的代码不会——这比任何规范文档都可靠。我们会在仓库里保留一个app/demo/目录，里面是“正确写法”的完整实现。AI 生成新模块时，我们让它先读这个参照实现，而不是凭记忆现编。

第三层是把“容易漏、错了也不报错”的步骤单独拎出来，做成结构化 Skill。以 go-admin 为例，“新建一个业务模块”这件事从一段散文式的操作说明，被改写成了一个可调用的 Skill：把表设计、迁移、Actions 模式代码生成、以及最容易漏掉的菜单/权限种子数据，串成一条端到端的流程，每一步都指向真实存在、可运行的参照文件。

这套思路的通用性在于：不是所有项目都需要立刻上 Skill，但“死规则 → 参照实现 → 隐性依赖显性化”这个分层逻辑是通用的。

2.3 一个更激进的实践：Plan Mode 先行

除了上述约束机制，我们在日常编码中推广了一个习惯：Plan Mode 先行。

不是让 AI 直接生成代码，而是先让它“想清楚再写”。在 Claude Code 中，用 plan mode 让 AI 分析现有代码结构、提出实现方案、指出潜在影响，人审核通过后再执行。

对于 Laravel 开发者，一个典型的 plan mode 用法是：“规划一个多渠道通知系统的实现。查看现有的 models、controllers 和相关代码，提出架构方案。”Claude Code 会读取项目结构，检查现有代码，提出的方案会考虑已有的 User model 是否已实现 Notifiable 接口、队列配置是否支持通知系统的任务分发。

关键价值在于：你在任何代码生成之前就完成了架构审查。这是协作式思考，不是盲目自动化。

三、文档环节：从“没人写”到“自动生成且可信”

3.1 文档的困境与 AI 的切入点

后端开发者对文档的态度通常是矛盾的：知道重要，但优先级永远排在功能之后。

AI 在这个环节的价值非常直接：它能读代码，然后写出人类能看懂的文档。这不需要模型有“创造力”，只需要它有“理解力”——而理解代码恰恰是大模型的强项。

3.2 接口文档的自动生成

API 文档是最适合 AI 自动化的场景之一。给 AI 一段路由定义和 handler 代码，它能生成完整的 Markdown 文档，包括端点描述、请求/响应示例、认证要求、错误码含义。

我们团队的做法是：把api-doc-generate做成一个标准 Skill，每次接口有变更时自动触发。生成的文档包含：

• 端点描述：从 handler 函数的注释和逻辑中提取业务含义
• 请求/响应示例：根据 DTO 结构生成真实可用的 JSON 示例
• 认证要求：从中间件配置中提取
• 错误码：从错误处理逻辑中整理

人只需要审核和调整语气，结构性的工作全部自动化。根据实际使用数据，一个中等复杂度模块的接口文档生成时间从 2-3 小时压缩到 15 分钟左右。

3.3 架构文档：让 AI 帮你“读懂”老项目

比接口文档更难的，是架构文档。尤其对于接手历史项目的团队，“这个模块为什么这么设计”“这个字段为什么加在这里”往往只有原开发者知道答案。

AI 在这方面有一个被低估的能力：它能从代码本身反推设计意图。

具体做法是：把相关模块的代码、数据库 schema、配置文件一起喂给 AI，让它生成一份“架构说明”，重点回答三个问题：

1. 这个模块的职责边界是什么？（从代码组织和依赖关系中推断）
2. 核心数据流是怎样的？（从函数调用链和数据变更中还原）
3. 有哪些隐性的设计约束？（从数据库约束、配置项、注释中提取）

我们曾用这个方式处理一个从 ColdFusion 迁移到 Django 的 19 年老项目。AI 生成的架构说明虽然不能完全替代人工梳理，但它提供了一个高质量的起点，让新接手的开发者能在半天内建立基本认知，而不是花一周时间在代码里漫游。

3.4 文档生成的工程化约束

自动生成文档有一个风险：过时比没有更糟糕。一份描述“旧行为”的文档会误导人。

我们的做法是：文档生成绑定到代码变更流程。每次 PR 合入主分支时，CI 触发文档生成 Skill，对比生成的文档和当前仓库中的文档版本。如果有差异，自动创建文档更新 PR，要求代码作者审核。

这个约束保证了文档和代码的同步率。代价是每次 PR 多了一个“文档更新”的检查项，但相比“文档永远落后代码三个版本”的状态，这个代价是值得的。

四、自动化测试环节：从“写不动”到“生成 + 修复闭环”

4.1 AI 辅助测试的三个层次

测试生成是 AI 在后端研发链路中见效最快的环节之一。我们把 AI 辅助测试分为三个层次：

L1：单元测试生成。给 AI 一段函数代码，让它生成对应的单元测试，覆盖 Happy Path、边界条件、异常处理。这是目前最成熟的 AI 测试能力，准确率约 80%。

L2：集成测试生成。给 AI 一个功能模块的多个组件，让它生成跨组件的集成测试。准确率约 60%，需要更多人工审核。

L3：E2E 测试生成。给 AI 一个用户场景描述，让它生成 Playwright 或 Cypress 的 E2E 测试脚本。这是目前最不成熟但最有价值的层次。

4.2 单元测试生成：从“80% 完成度”开始

以 Cursor 为例，选中一个函数，按 Ctrl+K，输入指令：“为这个函数生成完整的 Jest 单元测试，覆盖 Happy Path、边界条件、过期场景、异常输入。”

AI 会分析函数的输入输出、边界条件、可能抛出的异常，生成覆盖率约 80% 的测试代码。剩下 20% 需要人工补充的，通常是 AI “想不到”的东西：并发场景下的竞态条件、时区边界问题、数据库事务失败场景。

关键认知：AI 生成的测试不是“完成品”，是“80% 完成度的工作台”。你从一个空白文件开始写测试，和从一个覆盖了主要路径的测试文件开始补充，效率差异是数量级的。

4.3 E2E 测试：Playwright Test Agents 的三段式工作流

E2E 测试一直是“知道重要但写不动”的典型。Playwright Test Agents 的出现改变了这个局面。

Playwright Test Agents 由三个角色组成：

工作流程是：planner 先在浏览器中实际探索应用，产出测试计划；generator 按照计划逐个场景执行并生成代码；测试运行失败时，healer 分析失败原因、修改测试代码或选择器。

我们团队在一个 Java 的 PetStore 电商应用上实测了这套流程。从测试计划到可运行的 E2E 测试代码，再到 HTML 报告展示，全程由 Agent 完成，人只需要审核测试计划的合理性。

但需要清醒的是：E2E 测试的维护成本并没有消失，只是从“人工修选择器”变成了“审核 AI 的修复是否合理”。healer 可能会把测试改“松”——比如把严格断言改成宽松断言来让它通过。所以我们的规则是：healer 的每次修改都需要人工确认，不允许自动合入。

4.4 测试修复闭环：AI 让测试“活”起来

比测试生成更有价值的，是测试修复。

传统后端测试的一个痛点是：测试会因为非代码原因失败。比如上游 API 的响应格式变了、测试环境的数据库被重置了、某个 mock 服务的超时阈值被调了。开发者看到失败测试的第一反应往往是“又挂了，先跳过吧”。

AI 在这个环节的价值是：它能区分“真 bug”和“环境问题”。当测试失败时，AI 可以分析失败日志、对比历史运行记录、检查依赖服务的状态，给出判断：这是代码引入的回归，还是测试环境的不稳定？

我们把这道判断做成了一个 Skill：测试失败时自动触发，输出结构化的失败分析报告，标注“需修复代码”或“需修复测试”。前者交给人处理，后者尝试自动修复（最多 2 轮，超过则交回人工）。

五、工程化底座：让 AI 辅助研发“可观测、可约束、可回退”

5.1 可观测性不是可选项

New Relic 的报告揭示了一个反直觉的数据：62% 的技术负责人承认，团队在没有逐行审查的情况下就上线了 AI 生成的代码。这解释了为什么生产事故在增加。

当 AI 成为代码的主要生产者时，传统的“代码审查”作为主要质量闸门的模式开始失效。代码太多、生成太快、来自不同 prompt 的代码太多，逐行审查的 ROI 急剧下降。

取而代之的，是运行时可观测性成为“代码到底在做什么”的主要证据来源。96% 的技术负责人认为可观测性对 AI 生成代码“非常重要或极其重要”，零人认为“不重要或完全无关”。

我们的实践是：AI 生成的代码必须包含 telemetry。不是事后加日志，而是在生成时就把可观测性作为输出的一部分。我们在 AGENTS.md 中明确规定：每个 API handler 必须包含结构化日志（请求参数摘要、处理耗时、关键决策点），每个外部调用必须包裹指标上报。

5.2 约束机制：AGENTS.md 的“死规则”

AGENTS.md 的核心原则是：只写“不遵守就会出错”的规则，越短越好。

我们团队的 AGENTS.md 目前只有 40 行左右，包含：

• 项目使用的框架版本和代码风格约定（指向 go.mod 和参照实现）
• 日志和指标上报的强制要求
• 权限种子数据必须写入的四张表及其字段映射
• 不允许 AI 修改的目录和文件（如migrations/下的历史迁移文件）

40 行不是目标，是结果。我们反复删减，直到“再删一条就会出问题”为止。

5.3 回退机制：Local History 的价值

AI 生成代码的速度快，意味着“改错”的速度也快。

PyCharm 的 Local History 功能在 AI 辅助开发场景中变得格外重要。它独立于版本控制，记录文件的每一次变更。当 AI 的一次修改导致了问题，你可以直接对比变更前后的版本并恢复——即使你从未 commit 过。

我们的工作流是：AI 执行任何“有风险”的修改前（比如重构、批量修改、数据库相关变更），先在 IDE 中保存当前状态。如果修改后测试失败且无法快速修复，直接回退到修改前状态，重新设计 prompt。

六、踩坑与反思

坑一：把 AI 当“更快的打字机”

最初我们让 AI“写一个用户管理模块”，结果生成的代码能跑但风格和项目完全不搭。后来明白：AI 不是打字机，它是一个需要上下文和约束的协作者。你给它的信息质量，决定它的输出质量。

坑二：过度信任“测试通过”

AI 生成的代码跑通了测试，不等于代码是对的。测试本身可能是 AI 生成的，而 AI 生成的测试可能覆盖了 Happy Path 但漏掉了关键边界。我们的规则是：AI 生成的代码，测试必须由不同的人（或至少不同的 prompt）生成。用 AI 生成的测试验证 AI 生成的代码，等于自我循环。

坑三：文档生成的“静默过时”

自动生成文档有风险：如果触发机制没有绑定到代码变更，文档会静默地过时。有人以为文档是新的，照着它去理解系统，结果被误导。自动生成的文档，必须自动验证新鲜度。

坑四：E2E 修复的“松绑陷阱”

healer 修复测试时，倾向于把断言改松让它通过。如果不加约束，E2E 测试会逐渐失去“发现问题”的能力。每次 healer 的修改都必须人工确认，不允许自动合入。

七、结语

AI 重塑后端研发链路，核心不是“让 AI 写更多代码”。代码变便宜之后，真正稀缺的是判断力：判断 AI 生成的代码对不对、判断测试覆盖够不够、判断架构演进的方向对不对。

JetBrains 调查中有一个数据点很说明问题：开发者每天花在 CRUD 上的时间平均是 30-50 行代码。AI 可以把这部分压缩到几分钟。省下来的时间，应该花在那些 AI 做不了的事情上：理解业务、设计架构、判断优先级、承担责任。

一个可复用的后端 AI 研发链路，应该具备三个特征：

约束是显性的。AGENTS.md 写清楚“不能做什么”，参照实现展示“应该怎么做”，Skill 固化“容易漏的步骤”。AI 不需要“聪明”，它需要“有据可依”。

验证是独立的。AI 生成的代码需要独立的验证——测试由不同的人/prompt 生成，架构评审在人这边完成，生产环境的可观测性作为最终裁判。

回退是容易的。快速生成的前提是快速回退。Local History、功能开关、小步提交，这些工程习惯在 AI 时代不是变次要了，是变更重要了。

代码变便宜了。判断力没有。