企业官网建设流程全解析

1. 为什么内部项目改造要先写 intent.md

1.1 从“让 AI 写代码”到“让 AI 理解意图”的转变

过去一年，我参与过三个内部系统的 AIcoding 改造，从最初的“把需求丢给模型让它生成代码”，到后来逐渐摸索出一套相对稳定的流程，中间踩的坑足够写一本小册子。最开始大家的做法都很朴素：把一段需求描述粘贴到对话框里，等模型吐出代码，复制进项目，跑一遍测试，能过就提交。这个模式在 demo 阶段看起来很美好，一旦进入真实项目，问题就集中爆发了——生成的代码风格和项目现有约定不一致、边界条件处理缺失、命名习惯对不上、依赖引入混乱，最要命的是，你很难判断它到底“理解”了多少。

后来我们复盘发现，问题的根源不在于模型能力，而在于我们从来没有把“意图”显式地写下来。人类工程师接手一个陌生模块时，会先读 README、看目录结构、翻几个核心文件，脑子里建立一张“这个项目想干什么、怎么干”的图。而 AI 在单轮对话里拿到的上下文是残缺的，它只能靠猜。intent.md 就是为解决这个问题而生的——它是一份写给 AI 看的“项目意图说明书”，用结构化的方式把项目目标、约束、约定、边界条件讲清楚，让模型在动手之前先建立正确的心理模型。

我个人的判断是：在 AIcoding 的落地实践中，intent.md 的重要性甚至高于提示词技巧本身。提示词决定单次输出的质量，而 intent.md 决定整个改造过程的一致性和可维护性。它相当于给 AI 装了一个“项目大脑”，后续所有的代码生成、重构、评测都围绕这份意图展开。

1.2 intent.md 和 CLAUDE.md 到底有什么区别

很多人第一次听到 intent.md 会问：这不就是 CLAUDE.md 换了个名字吗？我一开始也这么以为，实际用下来发现两者定位完全不同，混用会出大问题。

CLAUDE.md 这类文件本质上是工具配置文件，它告诉 AI 工具“在这个仓库里你应该怎么工作”——比如用哪个包管理器、测试命令是什么、代码风格偏好、禁止修改哪些目录。它是面向工具行为的，偏操作性。

intent.md 则是面向业务意图的，它回答的是“这个项目为什么存在、要解决什么问题、有哪些不可违背的业务约束”。举个例子，CLAUDE.md 里会写“使用 pnpm，测试用 vitest”，而 intent.md 里会写“订单状态机只允许单向流转，任何回退操作必须走人工审核通道”。前者是工程约定，后者是业务铁律。

我的建议是两者都要有，而且要在 intent.md 里显式引用 CLAUDE.md，形成“意图层 + 执行层”的双层结构。这样 AI 在理解业务的同时，也知道该用什么工具、遵循什么规范。

1.3 一份合格 intent.md 的最小结构

经过多次迭代，我们内部沉淀出一个相对稳定的 intent.md 模板，包含六个必备区块。这不是拍脑袋定的，而是根据 AI 实际“读不懂”的高频问题反推出来的。

• 项目定位：一句话说清这个系统是干什么的，服务谁，不服务谁。这一条能挡掉大量“AI 自作主张扩展功能”的问题。
• 核心领域术语表：把项目里的黑话、缩写、业务概念定义清楚。AI 最怕的就是遇到“工单”“批次”“结算周期”这类词时按通用含义理解，结果全错。
• 关键业务规则：用“必须/禁止/仅当”这类强约束句式列出不可违背的规则。这是 intent.md 里价值最高的部分。
• 技术栈与架构约束：说明为什么选这个框架、哪些技术决策是历史包袱不能动。
• 边界与禁区：明确哪些模块 AI 不要碰，哪些改动必须人工评审。
• 验收标准：告诉 AI 什么样的输出算合格，最好能对应到具体的测试用例或检查项。

这六块写下来，一份 intent.md 大概在 800 到 2000 字之间。太短了信息不够，太长了 AI 注意力会被稀释。我实测下来，1500 字左右是性价比最高的区间。

2. 内部项目改造的完整落地流程

2.1 改造前的盘点：哪些项目适合 AIcoding

不是所有内部项目都值得做 AIcoding 改造。我们第一批试点选了五个项目，最后只有两个跑通了，另外三个中途放弃。复盘下来，适合改造的项目有几个共同特征。

第一，代码库规模适中。太小了没意义，太大了上下文塞不下。我的经验是 5000 到 50000 行之间最合适，这个量级既能体现 AI 的效率优势，又不会因为上下文超限导致理解偏差。

第二，业务规则相对稳定。如果项目还在需求剧烈变动期，intent.md 今天写完明天就过时，维护成本会吃掉收益。最好是那种核心逻辑已经稳定、主要工作是增量迭代和重构的项目。

第三，测试覆盖有一定基础。AI 生成的代码需要快速验证，如果项目本身没有测试，你只能靠人工 review，效率提升有限。哪怕只有 30% 的核心路径测试覆盖，也能显著加速验证循环。

第四，团队对 AI 工具有基本认知。这点经常被忽略。如果团队成员把 AI 当成“许愿机”，期望一句话生成整个模块，那改造必然失败。需要先做认知对齐，明确 AI 是“加速器”不是“替代品”。

我们当时用了一个简单的评分表来筛选项目，四个维度各 25 分，总分超过 70 才立项。这个门槛帮我们挡掉了不少冲动型改造。

2.2 第一步：把隐性知识写成 intent.md

写 intent.md 的过程，本质上是一次团队知识的显性化。我们第一次写的时候，发现很多规则大家心里都清楚，但从来没人写下来过。比如“用户余额扣减必须先冻结再扣款”，这种规则老员工习以为常，新人要踩坑才知道，AI 更是完全不知道。

具体怎么写？我的做法是先访谈再落笔。找两三个最熟悉这个项目的工程师，每人聊 30 分钟，问四个问题：这个项目最容易出错的地方在哪、有哪些看起来能做其实不能做的操作、有哪些历史遗留的坑、新人上手最容易误解什么。把答案整理出来，基本就是 intent.md 的雏形。

写的时候有个技巧：多用反例，少用正例。AI 对“禁止做什么”的敏感度远高于“应该做什么”。与其写“订单金额计算要精确”，不如写“禁止使用浮点数计算金额，必须用整数分单位”。前者 AI 可能理解成“注意精度”，后者它就知道具体该怎么做了。

还有一个坑要提醒：intent.md 不要写成需求文档。需求文档是给人看的，讲究完整和正式；intent.md 是给 AI 看的，讲究精准和可执行。我见过有人把 PRD 直接改个名字当 intent.md，结果 AI 读完还是不知道该干什么，因为 PRD 里全是“用户可以……”“系统支持……”这类描述性语言，缺少约束性表达。

2.3 第二步：用 CLAUDE.md 固化工程约定

intent.md 解决“做什么”，CLAUDE.md 解决“怎么做”。这两个文件配合使用，效果最好。

CLAUDE.md 的内容相对机械，主要是把团队已有的工程约定写清楚。我们内部的标准模板包含这几块：

# 工程约定 ## 包管理与构建 - 使用 pnpm，禁止 npm/yarn - 构建命令：pnpm build - 开发命令：pnpm dev ## 代码风格 - 使用 ESLint + Prettier，提交前必须通过 lint - 组件文件使用 PascalCase，工具函数使用 camelCase - 禁止使用 any，必要时用 unknown + 类型守卫 ## 测试 - 单元测试用 vitest，E2E 用 playwright - 新增功能必须附带测试，覆盖率不低于 70% - 测试文件与被测文件同目录，命名 xxx.test.ts ## 目录约定 - src/domain 存放领域逻辑，禁止引入 UI 依赖 - src/infra 存放基础设施代码 - 禁止跨层直接调用，必须通过接口 ## 禁区 - 不要修改 migrations 目录下的历史迁移文件 - 不要改动 .env 相关配置 - 涉及支付、权限的代码必须人工评审

这份文件写一次能用很久，维护成本很低。关键是它让 AI 的输出“像团队自己写的”，而不是“一眼看出是 AI 写的”。这一点在 code review 阶段特别重要，风格统一的代码 review 起来快很多。

2.4 第三步：小步快跑的改造节奏

改造节奏上，我强烈建议小步快跑，不要一次性让 AI 重构整个模块。我们的做法是把改造拆成若干个小任务，每个任务控制在 AI 单次能完成的范围内。

一个典型的任务粒度是这样的：改造一个函数、修复一类 bug、补充一组测试、抽取一个工具方法。每个任务完成后立刻验证、提交，然后再进行下一个。这样做的好处是，一旦 AI 跑偏，损失可控，回滚成本低。

我们内部有个不成文的规矩：单次 AI 生成的代码不超过 200 行。超过这个量，review 成本急剧上升，而且出错的概率也明显增加。如果任务确实需要更多代码，就拆成多个子任务串行执行。

改造过程中还有个细节：每次让 AI 动手前，先让它复述一遍 intent.md 里的相关约束。这个动作看起来多余，但实测能显著降低跑偏率。因为模型在复述的过程中会“激活”相关上下文，后续生成时更可能遵守这些约束。这个技巧我们叫“意图预热”，成本很低，收益很高。

3. 持续评测：让 AIcoding 质量可量化

3.1 为什么一次性评测不够

很多团队做 AIcoding 评测，就是改造完成后跑一遍测试，过了就完事。这种做法的问题在于，AI 的输出质量是波动的。同一个 intent.md，同一个任务，今天生成的代码可能很好，明天因为模型版本更新或者上下文细微变化，质量就下降了。一次性评测只能反映某个时间点的状态，无法持续保障质量。

持续评测的核心思路是：把评测变成常态化流程，而不是一次性动作。每次 AI 生成代码后，自动跑一组评测，把结果记录下来，形成质量趋势。这样一旦质量下滑，能第一时间发现。

我们内部把持续评测分成三个层次，从快到慢、从粗到细。

3.2 三层评测体系的设计

第一层是静态检查，秒级完成。包括 lint、类型检查、格式检查、依赖检查。这一层主要挡掉低级错误，比如语法问题、类型不匹配、引入了禁止的依赖。成本极低，每次生成后必跑。

第二层是单元测试，分钟级完成。跑项目现有的测试套件，看 AI 的改动有没有破坏已有功能。这一层能挡掉大部分回归问题。我们要求 AI 生成代码后必须跑通全部单元测试，跑不通就回退重来。

第三层是意图一致性检查，这个是我们自己设计的，也是最有价值的一层。具体做法是：把 intent.md 里的关键约束提取成一组检查项，用脚本或者另一个 AI 来验证生成的代码是否满足这些约束。

举个例子，intent.md 里写了“订单状态只允许单向流转”，那我们就写一个检查项：扫描代码里所有修改订单状态的地方，验证是否存在回退操作。这种检查用传统静态分析很难做，但用 AI 来做反而很合适，因为约束是自然语言描述的。

这三层配合下来，基本能覆盖 AIcoding 的主要风险点。第一层和第二层可以完全自动化，第三层需要一些人工设计，但一旦设计好，后续维护成本很低。

3.3 意图一致性检查的具体实现

意图一致性检查是这套体系里最“非标准”的部分，我详细说说我们是怎么做的。

核心思路是把 intent.md 里的强约束句式转成可执行的检查项。intent.md 里我们要求用“必须/禁止/仅当”这类句式，就是为了方便后续转检查项。每条这样的约束，对应一个检查脚本或者一段检查提示词。

比如 intent.md 里有这么一条：“禁止在 domain 层引入任何 infra 层的依赖”。对应的检查就是扫描 domain 目录下所有文件的 import 语句，看有没有指向 infra 的路径。这个用简单的 AST 分析就能做。

再比如：“金额计算必须使用整数分单位，禁止浮点数”。对应的检查是扫描所有涉及金额的变量声明和运算，看有没有 float/double 类型。这个稍微复杂一点，需要结合类型信息和变量命名来判断。

最难的是那种涉及业务语义的约束，比如“退款操作必须先校验原订单状态”。这种用静态分析做不了，我们的做法是用另一个 AI 实例来做检查：把 intent.md 的相关约束和生成的代码一起喂给检查 AI，让它判断是否满足。这个方案不完美，但实测准确率能到 85% 以上，作为辅助手段足够了。

提示：意图一致性检查的检查项不要贪多，先覆盖最高频、最致命的 10 到 15 条约束，跑顺了再逐步扩展。一上来就搞几十条，维护不过来，最后会变成摆设。

3.4 评测数据的沉淀与复盘

持续评测的价值不仅在于“发现问题”，更在于“沉淀数据”。我们每次评测的结果都会记录到一个简单的表格里，包含时间、任务、评测层次、通过情况、失败原因。积累一两个月后，就能看出一些规律。

比如我们发现，涉及状态机的任务失败率明显高于其他任务，因为状态流转的约束多，AI 容易漏掉边界情况。针对这个发现，我们专门在 intent.md 里加强了状态机相关的约束描述，失败率就降下来了。

再比如，模型版本更新后的头几天，失败率会有一个小高峰。这提醒我们，模型更新后不要立刻全量使用，先在小范围任务上验证，稳定了再推广。

这些规律单看某一次评测是发现不了的，只有持续记录、定期复盘才能看出来。我建议每个做 AIcoding 的团队都建立这样一个简单的数据记录机制，成本很低，价值很高。

4. 踩过的坑与实战经验

4.1 intent.md 写得太“完美”反而有害

这是我最想强调的一个坑。刚开始写 intent.md 的时候，我们追求“完整、严谨、面面俱到”，结果写出来一份 5000 多字的文档，把能想到的都写进去了。结果 AI 读完之后，生成质量反而下降了。

原因很简单：上下文是有预算的。intent.md 太长，会挤占代码本身的上下文空间，导致 AI 对具体代码的理解变浅。而且过长的文档里，关键约束会被淹没在大量次要信息中，AI 抓不住重点。

后来我们做了减法，把 intent.md 压缩到 1500 字左右，只保留最核心的约束，效果立刻好转。intent.md 不是越全越好，而是越准越好。宁可漏掉一些次要约束，也要保证核心约束足够突出。

4.2 不要让 AI 同时做“理解”和“生成”

早期我们习惯把 intent.md 和任务描述一起丢给 AI，让它直接生成代码。后来发现，让 AI 分两步走效果更好：第一步只让它读 intent.md 和任务描述，输出一份“我理解的任务是什么、有哪些约束、打算怎么做”的说明；第二步再基于这份说明生成代码。

这个两步法看起来多了一轮交互，但实际总耗时反而更短，因为返工少了。第一步的输出相当于一次“意图对齐”，如果 AI 理解偏了，在这一步就能发现并纠正，不用等到代码生成完再回退。

我们内部把这个做法叫“先对齐再动手”，现在已经是标准流程了。特别是涉及复杂业务逻辑的任务，这一步几乎不能省。

4.3 评测失败后的处理策略

评测失败是常态，关键是怎么处理。我们总结了三种处理策略，根据失败类型选择。

第一种是自动重试。适用于静态检查失败这类低级错误。把失败信息反馈给 AI，让它重新生成，通常一两次就能过。重试次数上限设为 3 次，超过就转人工。

第二种是回退重来。适用于单元测试失败这类回归问题。直接回退到上一个可用状态，重新拆解任务，换个角度让 AI 再做一次。不要试图在失败的代码上修修补补，越修越乱。

第三种是人工介入。适用于意图一致性检查失败这类方向性问题。说明 AI 对业务的理解有偏差，需要人工介入，要么补充 intent.md 的约束描述，要么直接人工完成这部分。

这三种策略要提前定好，不要每次失败都临时决策。我们把这些策略写进了团队的 AIcoding 操作手册，新人上手时照着做就行。

4.4 常见问题速查表

这张表是我们踩坑踩出来的，基本覆盖了 80% 的常见问题。遇到新问题先查表，查不到再深入分析。

4.5 关于 ai-native SDLC 的一点个人理解

最近“ai-native SDLC playbook”这个词挺火，很多人问这到底是什么的缩写。SDLC 是 Software Development Life Cycle，软件开发生命周期。ai-native SDLC 指的是从设计之初就把 AI 作为一等公民纳入的开发流程，而不是在传统流程上“打补丁”加个 AI 工具。

我个人的理解是，ai-native SDLC 的核心变化在于：意图表达成为流程的起点。传统 SDLC 从需求文档开始，ai-native SDLC 从 intent.md 开始。需求文档是给人看的，intent.md 是给人和 AI 共同看的。这个转变看似小，实际上会带动整个流程的重构——评测要围绕意图做、代码评审要对照意图查、甚至任务拆分都要按意图边界来切。

我们目前的实践还只能算“AI-assisted”，离真正的“ai-native”还有距离。但 intent.md 和持续评测这两块，我觉得是通往 ai-native 的必经之路。先把这两块做扎实，后续再逐步把 AI 融入到更多环节。

5. 一些实操层面的补充建议

5.1 团队协作中的 intent.md 维护

intent.md 不是写完就完事的，它需要持续维护。我们的做法是把 intent.md 纳入 code review 流程：任何涉及业务规则变更的 PR，都必须同步更新 intent.md 的相关条目。这样能保证 intent.md 和代码始终一致。

维护责任上，我们指定了一个“意图守护者”的角色，由最熟悉业务的人担任，负责审核 intent.md 的变更。这个角色不需要全职，但要有明确的负责人，否则 intent.md 会逐渐腐化，最后变成没人看的摆设。

还有个细节：intent.md 的变更要记录 changelog。我们用一个简单的表格记录每次变更的时间、内容、原因。这样当 AI 生成质量出现波动时，可以回溯是不是 intent.md 的某次变更导致的。

5.2 不同规模项目的适配策略

intent.md 和持续评测这套方法，不是所有项目都照搬。根据项目规模，需要做适配。

小型项目（5000 行以下）：intent.md 可以精简到 500 字以内，只写最核心的约束。持续评测可以只做静态检查和单元测试，意图一致性检查可以省掉，因为项目小，人工 review 成本不高。

中型项目（5000 到 50000 行）：这是这套方法收益最大的区间。intent.md 按标准模板写，三层评测全上。我们跑通的项目基本都在这个量级。

大型项目（50000 行以上）：intent.md 需要按模块拆分，每个模块一份，避免单份文档过长。持续评测要引入分层机制，核心模块严格评测，边缘模块放宽标准。大型项目还要注意上下文管理，可能需要引入检索机制，让 AI 按需加载相关部分的 intent.md。

5.3 工具选型的一些考量

工具选型上，我的建议是不要过度追求“专用工具”。很多团队一上来就想找现成的 AIcoding 平台，结果发现平台的功能和自己的流程对不上，反而增加摩擦。

我们目前的工具链很朴素：intent.md 和 CLAUDE.md 就是普通的 Markdown 文件，放在仓库根目录；评测脚本用 Node.js 写，跑在 CI 里；意图一致性检查用了一个简单的 CLI 工具，调用模型 API 做检查。整套下来没有引入任何重型依赖，维护成本很低。

工具选型的核心原则是可替换、可组合。每个环节都用最简单的方案，需要升级时单独替换，不影响其他环节。这样能避免被某个平台绑定，也能根据实际需求灵活调整。

5.4 关于 aicoding 笔试题的一点经验

最近有不少人问 aicoding 笔试题怎么写，我结合自己的经验说几句。这类题目通常不是考你“能不能让 AI 生成代码”，而是考你**“能不能让 AI 生成正确的代码”**。

我的建议是：先写意图，再写代码。拿到题目后，不要急着让 AI 生成，先花几分钟把题目的核心约束、边界条件、验收标准理清楚，写成一份简短的 intent。然后再让 AI 基于这份 intent 生成代码。这样生成的代码质量会明显更高，也更容易通过评测。

另外，要展示你的评测思路。笔试题往往不只看最终代码，还看你有没有验证意识。哪怕题目没要求，也主动跑一下测试、检查一下边界条件，把验证过程写进答案里。这个习惯在实际工作中同样重要。

5.5 后续可以扩展的方向

这套方法跑通之后，我们还在探索几个扩展方向。一个是把 intent.md 和需求管理系统打通，让需求变更自动触发 intent.md 更新。另一个是把持续评测的结果可视化，做成一个简单的看板，让团队随时能看到 AIcoding 的质量趋势。还有一个是把意图一致性检查的检查项做成可复用的库，不同项目之间共享。

这些扩展都还在早期阶段，没有成熟的经验可以分享。但方向我觉得是对的：让意图表达和持续评测成为 AIcoding 的基础设施，而不是每次都要重新搭一遍。基础设施建好了，AIcoding 才能真正规模化落地，而不是停留在个别项目的试点阶段。

我在实际使用中最大的体会是：AIcoding 的瓶颈从来不在模型能力，而在工程化程度。模型再强，如果意图表达不清楚、评测跟不上，生成质量就是上不去。反过来，哪怕模型能力一般，只要意图清晰、评测到位，也能稳定产出可用的代码。这个认知转变，是我们从“玩具阶段”走向“生产可用”的关键。