1. 为什么内部项目改造要先写 intent.md1.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 里会写“订单状态机只允许单向流转任何回退操作必须走人工审核通道”。前者是工程约定后者是业务铁律。维度CLAUDE.mdintent.md面向对象AI 工具的执行行为项目的业务意图内容类型命令、路径、风格约定目标、约束、边界、术语变更频率低随工具链调整中随业务演进谁维护工程负责人产品 技术共同维护失效后果工具行为异常AI 生成方向性错误代码我的建议是两者都要有而且要在 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 类型守卫 ## 测试 - 单元测试用 vitestE2E 用 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 常见问题速查表问题现象可能原因排查方向解决建议AI 生成的代码风格不一致CLAUDE.md 缺失或未生效检查 CLAUDE.md 是否被正确加载补充工程约定确认工具配置业务逻辑理解错误intent.md 约束描述模糊检查相关约束是否用了强句式改用“必须/禁止”句式重写生成的代码破坏已有功能缺少回归测试检查测试覆盖情况补充测试启用单元测试评测同一任务多次生成质量波动大上下文不稳定检查任务描述和上下文长度固定上下文拆分任务意图一致性检查频繁失败约束本身有歧义检查约束的可执行性把模糊约束改成可验证的表述AI 修改了不该改的文件禁区未明确检查 intent.md 的边界描述显式列出禁止修改的目录这张表是我们踩坑踩出来的基本覆盖了 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 的瓶颈从来不在模型能力而在工程化程度。模型再强如果意图表达不清楚、评测跟不上生成质量就是上不去。反过来哪怕模型能力一般只要意图清晰、评测到位也能稳定产出可用的代码。这个认知转变是我们从“玩具阶段”走向“生产可用”的关键。