企业官网建设流程全解析

1. 内容整体设计与改造思路

先说结论：AIcoding 工具本身不难接，难的是怎么让它在内部项目里真正干活儿，而不是每天生成一堆看似合理、实则跑不通的代码。我所在的小组从前年年底开始把 AIcoding 引入日常开发，前后试过直接把 Copilot 类插件塞给全员，也试过自建一套基于大模型的代码生成服务，最后都卡在同一个地方——模型根本不了解我们这个项目的来龙去脉。

当时的典型场景是这样的：一个跑了三年多的内部订单处理系统，代码量十几万行，模块之间耦合严重，业务规则散落在各个 Service 和存储过程里。你把 AIcoding 工具接上 IDE，让它"给订单导出功能加一个按渠道筛选"，它能在几秒钟内生成一段看起来很完整的代码，但十有八九会漏掉我们自定义的权限注解，或者直接把底层查询写成全表扫描。原因是它只看到了当前文件，看不到整个项目的约束。

后来我们把"项目说明文档"这件事捡了起来，但这次不是给人写的那种冗长的架构设计文档，而是专门给 AIcoding 工具看的、高度结构化的意图文件，也就是标题里提到的 intent.md。这个东西本质上是一份"AI 行为契约"，它告诉 AIcoding 你在什么技术栈里工作、有哪些必须遵守的规范、哪些边界绝对不能碰、完成一个任务通常要动哪几个文件。有了它之后，AI 生成的代码不再是"看起来对"，而是"真的能合进主干"。

内部项目改造这件事，最忌讳的就是把 AIcoding 当成 IDE 的一个插件开关，装上就当落地了。真正的改造至少包含三层：第一层是上下文工程，也就是把项目知识结构化，让模型能读懂；第二层是流程改造，把"人写代码"变成"人审代码 + AI 写代码"；第三层是评测闭环，你得有办法知道 AI 改完的代码到底行不行。这篇文章主要讲第一层和第三层，也就是 intent.md 怎么写、持续评测怎么做，这两件事做好了，中间那层流程改造自然水到渠成。

2. intent.md 的核心细节与实操要点

2.1 intent.md 到底是什么，跟文档有什么区别

我最早接触 intent.md 这个概念的时候，第一反应是：这不就是 README 吗？后来发现完全不是一回事。README 是给人类看的，它讲究背景交代、功能描述、架构图，甚至还有一段欢迎语。intent.md 是给 AIcoding 工具吃的，它讲究的是"可执行的约束"。

举个例子，我们 README 里写"本系统采用 Spring Boot + MyBatis，数据库为 MySQL 8.0"，这句话信息密度太低。AIcoding 读完只知道技术栈，不知道"MyBatis 的 mapper 必须放在 repository 包下""所有查询必须走自定义的分页拦截器，不能直接用 PageHelper""订单状态字段千万不能改，改了会触发一堆历史逻辑"。这些内容写进 README 里会显得很啰嗦，但写进 intent.md 里就是救命稻草。AI 在生成代码时，每多知道一条约束，踩坑概率就低一截。

我现在习惯把 intent.md 比作"带新人的第一课"。组里来了个新同事，你不会直接丢给他代码仓库让他读，你会先讲半小时项目背景、约定、红线。intent.md 就是把这半小时的谈话内容文本化、结构化，只是这次讲述对象不是人，是 AIcoding 模型。

2.2 intent.md 的推荐结构与内容字段

不同团队对 intent.md 的内容组织不太一样，我见过有人把它写成大纲式的纯文本，也有人做成带表格的严格模板。我的建议是：字段可以灵活，但必须有五个核心块。

第一个是"项目背景与定位"。这块不需要长，三到五行就够，说明这个系统是干嘛的、服务谁、最核心的业务链路是什么。AIcoding 模型读到这里，会建立一个基本的业务心智模型，后续生成代码时更容易贴合业务语义。比如"这是内部工单系统，核心链路是工单创建 -> 自动分单 -> 处理 -> 回访 -> 归档"。

第二个是"技术栈与架构约束"。这一块要列出语言、框架、ORM、数据库、缓存、消息队列，以及它们的版本。更重要的是，要写明架构层面的硬约束，比如"所有对外接口必须走网关层""领域模型禁止直接暴露给 Controller""服务间调用必须用内部 RPC，不能用 HTTP"。这些约束直接决定了 AI 生成的代码结构是否合规。

第三个是"代码风格与工程规范"。命名规范、包结构、异常处理方式、日志规范、测试要求、提交信息格式，全都可以写进来。有些团队觉得这些太琐碎，但恰恰是这些琐碎的东西，决定了 AI 生成的代码能不能过 Code Review。比如我们要求所有新代码必须有单元测试，覆盖率不低于 70%，intent.md 里写了这条之后，AIcoding 在生成功能代码时会主动带上测试文件，这一点非常神奇。

第四个是"红线与禁止事项"。这是 intent.md 里最重要的部分。我们项目里有一条红线："禁止在事务方法内调用远程服务"，原因是历史上有过一次因为远程调用超时导致数据库连接池被占满的线上事故。把这类教训写进红线区，AIcoding 在生成涉及事务的代码时，会自动绕开这个雷区。这部分的写法要非常明确，最好直接用"禁止""不要""Never"这类强否定词，因为模型的指令遵循能力对明确的否定词响应更好。

第五个是"常见任务与改动模式"。这其实是把团队积累的开发经验结构化。比如"新增一个查询接口需要改动哪些文件""新增一个定时任务需要注册到哪个配置类"。每写一条，AIcoding 在接到类似任务时就直接知道要动哪些文件，而不是打开一个文件就开始写。

2.3 intent.md 的编写技巧和迭代方式

intent.md 不是一蹴而就的，它需要随项目演化持续迭代。我建议分成三个阶段先搭框架，用最小可用版本上线，然后基于实际效果反馈来完善细节。

起步阶段，花半天到一天时间把五个核心块都填上，每块不求全，三到五条即可。上线后观察一周，记录 AIcoding 生成代码时犯的典型错误，每周定期整理反馈，把错误对应的规则补进 intent.md。这个过程我们内部叫"喂教训"。

一个容易忽略的点是：intent.md 本身也要做版本管理。每次修改 intent.md 后，AIcoding 的行为会发生变化，这直接影响持续评测的结果。所以我们后来把 intent.md 放进了独立仓库，主仓库的代码每次发版时固定引用某个版本的 intent.md，保证评测结果可复现。这个操作一开始觉得多此一举，但真到排查模型回归问题时，才发现版本对应关系有多重要。

另外，intent.md 不要写得像散文。模型对结构化内容的理解能力远强于自由文本。你会发现同样的意思，用短句 + 条目写出来，AIcoding 的遵循率能提高不少。我们后来把 intent.md 里所有的长句子都拆成"指令 + 说明"的格式，效果立竿见影。

3. 持续评测体系搭建与落地过程

3.1 为什么静态接入了 intent.md 还不够

intent.md 写好了，AIcoding 生成代码的质量确实会上一个台阶，但新的问题马上出现了：你怎么知道它在项目改造过程中的表现是进步还是退步？AI 模型的更新、intent.md 的改动、项目本身代码结构的变化，都会影响生成质量。如果没有一套客观的评测机制，你就只能靠团队成员的体感来判断"最近 AI 写得好不好"，这太主观了。

我们决定上持续评测，目标很简单：每次对 intent.md 或 AIcoding 配置做改动后，能用一个相对标准化的流程跑一遍测试，用数据说话。

开始的时候，团队里有人质疑必要性，觉得这是在给 AIcoding 落地增加成本。但踩了两次坑之后，所有人都同意了。第一次是升级 AI 模型版本后，原来能稳定生成的代码突然开始出现低级错误；第二次是扩大 intent.md 内容后，一部分任务的生成质量反而下降了。这两次问题如果靠人工 review 发现，至少晚一周，而且很难定位根因。

3.2 评测集怎么设计，以及跟"笔试题"的关系

持续评测的第一步是准备评测集。很多人知道要建评测集，但把评测集做成了"让 AIcoding 做算法题"，这就跑偏了。我注意到网上有人问 aicoding 笔试题怎么写，这是个好问题，但答案不是 leetcode 题。

AIcoding 笔试或评测题的设计思路，应该是"真实业务改造任务的缩略版"，而不是"算法能力的考察"。

我设计评测集时遵循三个原则：

第一，每个评测任务都必须有明确的"正确性判定标准"。这个标准可以是编译通过、单元测试通过、代码风格检查通过，也可以是人工 review 后打出的质量分。依赖于代码评审等方式来做质量评分，评测过程要记录为"实际目标"而非"理论目标"。

第二，评测任务要覆盖不同类型的编码活动。我们分了四类：新增功能、缺陷修复、重构改造、测试补全。这四类几乎覆盖了内部项目改造中的全部 AIcoding 使用场景。每类下面准备三到五个任务，整个评测集大概二十个任务。

第三，评测任务必须包含"反向题目"。也就是那些故意设置了陷阱的任务，比如"请在这个方法里加上重试机制，但注意不要违反项目里关于重试次数的统一约定"。这类题目能有效检验 AIcoding 是否真的读懂了 intent.md 中的红线条款，而不只是照猫画虎。

具体写题的时候，把任务描述得尽量接近真实业务的口吻，比如"工单列表页的查询很慢，请在保持接口返回结构不变的前提下，将子订单的状态过滤下推到 SQL 层"。这句话里藏着两个约束：接口返回结构不变、SQL 层下推。AI 要是没读 intent.md，很可能直接在内存里做过滤。

3.3 评测运行机制与打分维度

评测集设计好之后，就要解决"怎么跑、怎么打分"的问题。

我们搭了一套半自动化的评测流程。每次触发评测时，自动读取当前最新的 intent.md 和评测集，逐一将任务发送给被测 AIcoding 服务，再把生成的代码自动拉入一个隔离分支，执行编译、单元测试、静态检查，最后把结构化结果汇总到一张报表里。

打分不只看通过率，还看几个更细的维度。正确性是最基本的，编译不通过直接零分。规范遵循度看生成的代码是否遵守了 intent.md 中的约束，比如包路径、命名方式、注解使用。业务完成度看任务描述中的关键诉求是否都被满足，比如"保留接口返回结构不变"这条是否做到。最后一个是代码可维护性，这个维度没法完全自动化，我们会每周安排一名资深工程师把评测集里的生成代码人工 review 一遍，给出一个参考分。

从执行结果来看，引入打分维度之后，模型质量的评价才变得立体。只看通过率的时候，AI 有时候为了通过测试会写出很丑的硬编码；加上了规范遵循度和可维护性维度之后，团队能清楚地看到它在哪个方面偷懒。

3.4 评测结果如何反馈回 intent.md

持续评测的真正价值不在于评分表本身，而在于把评测结果反哺给 intent.md 和 AIcoding 配置。

我们每次评测完，都会开一个半小时的复盘会。逐条过那些"生成质量较低"的任务，分析原因。原因一般有三种，找到之后分别处理。

第一种是 intent.md 缺少必要约束。比如一个任务里要求"新加的定时任务必须注册到 JobCenter 配置类"，AIcoding 没做到，因为 intent.md 里根本没提这条。这种反馈直接补进"常见任务与改动模式"章节。

第二种是 intent.md 写得不够明确。比如写"查询要注重性能"，这个描述太模糊，AIcoding 不知道什么叫注重性能，后来改成"所有列表查询必须包含分页参数，单次查询数据量不得超过 5000 条"，遵循率立刻上来了。

第三种是评测集本身设计有问题。任务描述有歧义，或者判定标准和项目的实际约定不一致。这种情况我们会修改评测集并注明修订日期，避免后续评测结果失真。

这样跑了一个月后，我们的评测集、intent.md、AIcoding 配置形成了一个三角循环：评测发现问题，问题驱动 intent.md 更新，更新后的 intent.md 又通过下一次评测验证效果。这套机制跑顺之后，AIcoding 在内部项目改造中的输出质量有了肉眼可见的提升。

4. 常见问题与排查技巧实录

4.1 intent.md 更新后 AIcoding 行为反而变差

这是我们在持续评测中最常遇到的情况。明明往 intent.md 里加了一堆新规范，结果跑评测时整体通过率不升反降，甚至原来能过的任务也开始失败。

排查后发现，问题出在"意图过载"。intent.md 里的内容太多，模型的处理能力有限，新增的规范把之前本来就有的关键指令"挤"出了有效上下文。AIcoding 模型对过长的上下文存在注意力衰减，新加入的规则如果恰好覆盖了某个高频任务的关键约束，旧的关键约束就可能被忽略。

解决思路有两个，方向完全相反。一是删减非核心内容，只保留与高频任务直接相关的规则，把通用规范移到单独的 reference 文档中，只在意图文件里写索引。二是按任务类型拆分多个意图文件，比如 intent-query.md、intent-job.md、intent-api.md，AIcoding 在执行具体任务时只加载对应文件。我推荐先试前者，因为拆文件会增加检索复杂度，小团队维护起来有负担。

另一个附带的好处是，一旦发现评测结果波动，排查范围更小了。如果 intent.md 是一次比较大的更新，尽量分成多次小更新，每次更新后都跑一遍评测集，这样可以精确定位是哪条改动导致了行为变化。

4.2 评测集与真实业务的偏差

我们曾经历过一个尴尬的局面：AIcoding 在评测集上表现得非常好，通过率超过 90%，但在真实项目改造任务里还是频繁出问题。后来发现，评测集和真实业务之间存在两层偏差。

第一层是复杂度偏差。评测集里的任务通常是从真实需求简化来的，少了很多边界条件和上下文依赖。真实业务任务往往要跨多个模块、读多个表，AIcoding 在评测集里做得顺，不代表在复杂场景下也能做好。

第二层是上下文偏差。评测执行时，AIcoding 能拿到完整的 intent.md 和任务描述，但真实场景下，工程师可能只贴了一段需求文本，意图文件加载不全，甚至根本没加载。我们后来在评测流程里加了一个"上下文完整性检查"环节，模拟工程师最常用的使用方式，而不是理想状态下的使用方式，这样得出的评测结果才更有参考价值。

4.3 评测自动化程度的选择

到底要不要全套自动化？我的看法是分步走。第一步先做半自动，评测任务可以批量触发，但结果判定靠人工 + 编译检查，跑起来先积累数据。第二步再把单元测试、静态检查、规则校验做成自动化流水线，最后才考虑引入模型评分。

一步到位搞全自动化的团队，大概率会在评测集和判定逻辑上耗费大量时间，反而忽略了真正重要的 intent.md 迭代。持续评测的核心是"快速反馈、闭环迭代"，不是一个多么豪华的自动化平台。我们内部最开始就是一个 Python 脚本加一个 Markdown 表格，跑了两个月才逐步替换成正式的评测服务。

还有一点，评测结果的记录格式要统一。我们吃过一次亏，早期评测记录有人用 Excel，有人用在线文档，还有人直接发群里，结果两周后想对比数据完全没法对。后来统一成 JSON 格式存储，每一次评测都带上 intent.md 的版本号、模型版本、评测集版本，这样回归分析才有依据。

5. 一点个人经验收尾

做了一年的 AIcoding 落地改造，我最大的体会是：这个领域的门槛不在工具，而在你能不能把项目知识结构化成模型能理解的东西。intent.md 和持续评测表面上是一份文档加一套流程，实际上是在逼团队把过去只存在资深工程师脑子里的项目细节全部显性化。这个过程本身的价值，可能比 AIcoding 带来的编码效率提升还大。

最后再分享一个小技巧。intent.md 不要写在项目根目录然后就不管了，把它当成一等公民来维护。每次重要的代码结构变动，比如拆服务、换 ORM、引入新的中间件，都同步更新 intent.md。组里如果来了新同学，让他从读 intent.md 开始了解项目，反响比读 README 加架构文档好得多。AIcoding 是跟着 intent.md 走的，intent.md 维护得好，模型才能成为真正懂你项目的帮手，而不是一个偶尔靠谱的代码生成器。