1. 从一个内部项目改造说起为什么我们需要 intent.md去年下半年我接手了一个内部工具平台的改造任务。这个项目不算大后端六个服务前端两个仓库加上一些定时任务和脚本代码总量大概在八万行左右。团队一共四个人工期给了六周。按照以前的节奏这种规模的改造至少需要十周才能稳定上线但这次我们决定把 AIcoding 真正引入到日常开发流程里而不是像之前那样只是偶尔用用代码补全。结果六周下来我们不仅按时交付而且线上事故率比以往同类项目低了将近一半。这个过程中最关键的两个东西一个是intent.md另一个是持续评测机制。今天我就把这两个东西掰开揉碎讲清楚包括我们踩过的坑、试过的错、最后沉淀下来的模板和流程。先说清楚这篇文章适合谁看。如果你是一个技术团队的负责人正在考虑怎么把 AIcoding 落地到实际项目里或者你是一个一线开发者已经用过一些 AI 编程工具但觉得效果不稳定、不知道怎么系统化使用再或者你在准备 AIcoding 相关的面试题想搞清楚 intent.md 和持续评测到底是什么、怎么用——那这篇内容应该能给你不少直接能抄的作业。核心关键词我先自然带出来AIcoding、intent.md、持续评测、CLAUDE.md、SDLC。这几个词后面会反复出现每一个我都会给出具体的操作方法和实际案例。2. 先搞清楚 AIcoding 在 SDLC 里的真实位置2.1 AIcoding 不是代码补全是流程重构很多人对 AIcoding 的理解还停留在“帮我写个函数”“补全这段逻辑”的层面。这其实是最浅的一层。真正把 AIcoding 用出效果你会发现它改变的是整个SDLC软件开发生命周期的节奏。传统 SDLC 是需求分析 → 设计 → 编码 → 测试 → 部署 → 维护。每个阶段之间有明确的交接点文档是交接的载体。但 AIcoding 引入之后编码阶段的效率提升会倒逼其他阶段也跟着变。如果编码速度提升了一倍但需求理解和测试验证还是老样子那瓶颈就转移了整体效率反而可能下降。我们当时的做法是把 AIcoding 的介入点前移到需求理解阶段用intent.md来承载“意图”而不是等到编码时才让 AI 参与。这个思路的转变是后面所有操作的基础。2.2 intent.md 和 CLAUDE.md 的分工这里要区分两个东西intent.md和CLAUDE.md。很多人会把它们混在一起其实它们解决的是不同层面的问题。CLAUDE.md更像是给 AI 的“项目说明书”。它告诉 AI 这个项目用什么技术栈、目录结构长什么样、有哪些约定俗成的规范、哪些文件不要动。它是一个相对静态的配置文件放在项目根目录AI 每次进入项目时都会读取。intent.md则是“任务意图书”。它描述的是当前这次改造要达成什么目标、涉及哪些模块、有哪些约束条件、验收标准是什么。它是动态的每个任务或每个迭代周期都可以有一份。打个比方CLAUDE.md 是员工手册告诉你公司怎么运转intent.md 是项目任务书告诉你这次要做什么、做到什么程度算合格。两者配合使用AI 才能既懂规矩又懂目标。我们内部项目改造时CLAUDE.md 在项目启动第一天就写好了后面基本没大改。intent.md 则是每个改造模块写一份六周里一共写了十一份。2.3 为什么不用传统需求文档替代 intent.md有人会问需求文档不也是描述目标的吗为什么还要单独搞一个 intent.md区别在于读者不同。传统需求文档是给人看的人可以理解模糊表述、可以脑补上下文、可以靠经验补全缺失信息。但 AI 不行AI 需要明确、结构化、无歧义的输入。intent.md 的本质是“把人类意图翻译成 AI 能精确执行的结构化描述”。我们试过直接把需求文档丢给 AI结果它经常抓错重点或者在一些边界条件上做出错误假设。后来改成 intent.md 的格式之后AI 输出的代码一次通过率从大概四成提升到了七成以上。这个提升非常明显。3. intent.md 到底怎么写结构、模板与实操要点3.1 一份合格 intent.md 的六个核心字段经过多次迭代我们沉淀下来的 intent.md 包含六个必填字段。少一个都会导致 AI 理解偏差。第一个字段是 task_scope任务范围。用一句话说清楚这次要改什么不要超过两行。比如“将用户认证模块从 session 机制迁移到 token 机制涉及登录、登出、鉴权三个接口”。第二个字段是 affected_modules影响模块。列出所有会被改动的文件或目录精确到路径。这个字段的作用是给 AI 划定边界防止它改着改着跑到别的模块去了。第三个字段是 constraints约束条件。包括技术约束和业务约束。技术约束比如“不能引入新的第三方依赖”“必须兼容现有数据库 schema”业务约束比如“登录接口的响应时间不能超过 200ms”“不能改变现有 API 的返回结构”。第四个字段是 acceptance_criteria验收标准。这是最关键的字段。要写成可验证的条件而不是模糊描述。比如不要写“性能要好”要写“在 100 并发下 P99 延迟低于 300ms”。第五个字段是 reference_implementation参考实现。如果项目里有类似的模块已经实现了类似功能把路径贴进来让 AI 参考现有代码风格和模式。这个字段对保持代码一致性非常有用。第六个字段是 out_of_scope明确排除项。明确告诉 AI 哪些东西不要碰。比如“不要修改数据库迁移脚本”“不要动前端代码”。这个字段能避免很多意外改动。3.2 一个真实 intent.md 示例下面是我们当时改造认证模块时实际使用的 intent.md 内容做了脱敏处理# Intent: Auth Module Migration ## task_scope Migrate user authentication from session-based to token-based. Affects login, logout, and auth-check endpoints. ## affected_modules - src/auth/login.py - src/auth/logout.py - src/auth/middleware.py - src/models/user_session.py (deprecated, keep for rollback) - tests/auth/ ## constraints - No new third-party dependencies - Must maintain backward compatibility with existing API response format - Token expiry must be configurable via environment variable - Must not modify database schema ## acceptance_criteria - Login returns a valid JWT token with 24h expiry - Logout invalidates the token server-side - Auth-check middleware validates token on every protected route - All existing auth tests pass without modification - New tests cover token expiry and invalid token scenarios ## reference_implementation - See src/payment/token_handler.py for token generation pattern - See src/utils/middleware_base.py for middleware structure ## out_of_scope - Do not modify frontend code - Do not change database migration scripts - Do not alter user registration flow这份 intent.md 写完之后我们把它和 CLAUDE.md 一起放进项目根目录的.ai/文件夹里。每次让 AI 执行任务时只需要说“按照 intent.md 执行”它就能准确理解要做什么。3.3 写 intent.md 时最容易犯的三个错误第一个错误是范围写太大。一开始我们试图用一份 intent.md 覆盖整个改造项目结果 AI 处理起来顾此失彼改 A 模块的时候把 B 模块的逻辑也带偏了。后来改成每个模块一份每份只聚焦一个明确目标效果立刻好转。第二个错误是验收标准不可验证。比如写“代码质量要高”“逻辑要清晰”这种描述 AI 无法判断是否达成。必须写成可以跑测试验证的条件。我们后来要求所有 acceptance_criteria 都必须能对应到至少一个测试用例。第三个错误是忘记写 out_of_scope。这个字段看起来可有可无但实际上非常关键。有一次我们没写排除项AI 在改造认证模块时顺手把用户注册流程也“优化”了一遍结果引入了一个边界条件的 bug。从那以后out_of_scope 成了必填项。提示intent.md 写完之后建议先让 AI 复述一遍它的理解确认没有偏差再开始执行。这个习惯能省下大量返工时间。4. 持续评测让 AIcoding 的输出质量可量化4.1 为什么一次性评测不够AIcoding 有一个特点它的输出质量会随着上下文变化而波动。同一个任务今天跑和明天跑结果可能不一样。如果只在任务完成后做一次评测你只能知道“这次行不行”但不知道“为什么行”或“为什么不行”更不知道下次怎么稳定复现好的结果。持续评测的核心思路是把评测嵌入到整个开发流程里每次 AI 输出都自动跑一遍评测集记录结果形成趋势。这样你才能看到质量是在提升还是在下降哪些类型的任务 AI 表现好哪些容易出问题。我们在项目里搭了一个简单的持续评测流水线每次 AI 生成代码后自动触发。流水线包含三个层次单元测试层、集成测试层、意图一致性层。4.2 三层评测体系的具体实现单元测试层是最基础的。每次 AI 生成或修改代码后自动跑该模块的所有单元测试。这一层主要验证语法正确性和基本逻辑正确性。我们用的是项目原有的 pytest 框架没有额外引入新工具。集成测试层验证模块间的交互。AI 有时候会改对一个模块的内部逻辑但破坏了它和其他模块的接口约定。这一层跑的是跨模块的集成测试用例。我们当时有大概四十个集成测试用例覆盖了认证、支付、用户管理三个核心链路。意图一致性层是最有特色的一层。这一层不跑代码而是让另一个 AI 实例来检查生成的代码是否符合 intent.md 里定义的约束和验收标准。具体做法是把 intent.md 和生成的代码 diff 一起发给评审 AI让它逐条检查 acceptance_criteria 是否满足constraints 是否被违反。这一层听起来有点“用 AI 评测 AI”的意思但实际效果很好。我们统计过意图一致性层能捕捉到大约 15% 的单元测试和集成测试覆盖不到的问题主要是“代码能跑但不符合业务约束”的情况。4.3 评测结果的记录与分析每次评测的结果我们都会记录到一个简单的 JSON 文件里包含时间戳、任务 ID、各层评测的通过率、失败用例列表。积累了两周之后我们就能看出一些规律。比如我们发现涉及数据库操作的模块AI 的一次通过率明显低于纯逻辑模块。后来我们在 intent.md 里针对数据库操作增加了更详细的约束描述通过率就上来了。再比如当 intent.md 的 acceptance_criteria 超过八条时AI 的遗漏率会上升。于是我们养成了拆分任务的习惯每份 intent.md 的验收标准控制在五到八条之间。这些规律如果只做一次性评测是发现不了的。持续评测的价值就在于它能积累数据让你从“感觉 AI 还行”变成“知道 AI 在什么条件下行、什么条件下不行”。4.4 评测流水线的自动化配置我们的评测流水线跑在 CI 里配置大概长这样# .ai/eval-pipeline.yml stages: - unit_test - integration_test - intent_check unit_test: script: - pytest tests/unit/ --tbshort allow_failure: false integration_test: script: - pytest tests/integration/ --tbshort allow_failure: false intent_check: script: - python .ai/scripts/intent_checker.py --intent .ai/intent.md --diff HEAD~1 allow_failure: true注意 intent_check 这一层我们设了allow_failure: true因为它偶尔会有误报不适合作为硬性门禁。但它的输出会记录到评测日志里供人工复查。注意持续评测的评测集本身也需要维护。如果评测用例过时了评测结果就会失真。我们每周会花半小时 review 评测用例把不再适用的删掉把新发现的边界条件补进去。5. 内部项目改造的完整实操流程5.1 改造前的准备工作项目启动前我们花了大概两天做准备工作。这两天看起来没有产出代码但后面六周的效率提升全靠它。第一步是写CLAUDE.md。内容包括项目技术栈、目录结构说明、代码风格约定、常用命令、禁止事项。这份文档大概一千字左右写完之后让 AI 试着描述一遍项目结构确认它理解正确。第二步是搭建持续评测流水线。把现有的单元测试和集成测试接入 CI加上 intent_check 脚本。这一步大概花了半天主要是调试 intent_checker.py 的 prompt。第三步是选定第一个改造模块写第一份 intent.md。我们选的是相对独立的日志模块风险低适合用来磨合流程。5.2 一个模块的完整改造过程以认证模块为例完整流程是这样的第一步写 intent.md。按照前面说的六个字段填写大概花了四十分钟。写完之后让 AI 复述理解确认无误。第二步让 AI 生成改造方案。不是直接让它写代码而是先让它输出一个改造计划包括要改哪些文件、每个文件改什么、顺序是什么。这一步的输出我们会人工 review确认方案合理后再进入下一步。第三步分文件执行改造。每次只让 AI 改一个文件改完立刻跑评测。如果评测不通过把失败信息反馈给 AI让它修正。修正后再跑评测直到通过为止。第四步模块级集成验证。所有文件改完后跑一遍完整的集成测试和意图一致性检查。这一步通过后才算完成一个模块的改造。第五步记录评测数据。把这次改造的评测结果记录到评测日志里包括一次通过率、返工次数、主要问题类型。这些数据后面用来优化 intent.md 的写法。整个认证模块改造花了大概三天其中写 intent.md 和 review 方案占了半天实际编码和调试占了两天半。如果按传统方式做这个模块大概需要五到六天。5.3 改造过程中的关键决策点有一个决策点值得单独说什么时候让 AI 自主决策什么时候人工介入。我们的原则是涉及架构变更、接口约定、数据 schema 的改动必须人工确认方案后再让 AI 执行。涉及模块内部逻辑实现、代码风格调整、测试用例补充可以让 AI 自主决策评测通过即可。这个原则的底层逻辑是AI 在局部优化上很强但在全局一致性上容易出问题。把全局决策权留在人手里局部执行交给 AI是目前比较稳妥的分工方式。另一个决策点是评测不通过时是让 AI 重试还是人工修改。我们的经验是如果连续两次 AI 重试都失败就转人工。因为这说明 intent.md 的描述可能有问题或者任务本身超出了 AI 当前的能力边界。继续让 AI 重试只会浪费时间。6. 常见问题与排查技巧实录6.1 AI 输出偏离 intent 怎么办这是最常见的问题。表现是AI 生成的代码能跑测试也过但仔细一看它做的事情和 intent.md 里描述的不完全一样。比如 intent 要求“保持现有 API 返回结构不变”但 AI 悄悄加了一个字段。排查思路分三步。第一步检查 intent.md 里的 constraints 是否写得足够明确。很多时候偏离是因为约束描述有歧义。第二步检查 intent_checker 的 prompt 是否覆盖了这条约束。如果评测层没检查AI 就没有反馈信号。第三步如果前两步都没问题那就是 AI 的理解能力边界问题需要把任务拆得更细。我们的经验是大部分偏离问题都能通过细化 intent.md 解决。真正需要人工介入的情况不到两成。6.2 评测通过但线上出问题这种情况我们也遇到过两次。一次是 AI 生成的代码在测试环境跑得好好的上线后在高并发下出现了竞态条件。原因是评测集里没有覆盖并发场景。这件事给我们的教训是评测集的覆盖度决定了 AIcoding 的质量上限。评测集覆盖不到的场景AI 就不会去考虑。后来我们在评测集里补充了并发测试、边界值测试、异常注入测试这类问题就少了很多。另一个教训是intent.md 里的 acceptance_criteria 要尽量包含非功能需求。比如“在 100 并发下 P99 延迟低于 300ms”这种虽然写起来麻烦但能逼着 AI 考虑性能问题。6.3 常见问题速查表问题现象可能原因排查方法解决措施AI 输出偏离 intentconstraints 描述模糊逐条对照 intent.md 检查细化约束描述增加示例评测通过但线上出问题评测集覆盖不足复盘线上问题场景补充评测用例增加非功能验收标准AI 反复重试不通过任务粒度过大检查 intent.md 的 task_scope拆分为更小的子任务代码风格不一致CLAUDE.md 缺少风格约定对比现有代码和 AI 输出在 CLAUDE.md 中补充风格示例意图一致性检查误报prompt 过于严格查看 intent_checker 日志调整 prompt增加容错判断评测流水线跑得太慢评测集过大统计各层评测耗时分层执行快速反馈层优先6.4 几个独家避坑技巧技巧一intent.md 里加一个“反例”字段。我们后来在 intent.md 里增加了一个 optional 字段叫anti_patterns用来描述“不要做成什么样”。比如“不要把 token 存在 localStorage 里”“不要用同步方式调用外部服务”。这个字段对防止 AI 做出常见错误决策非常有效。技巧二评测日志要带上下文。只记录“通过/不通过”是不够的还要记录当时的 intent.md 内容、AI 的 prompt、生成的代码 diff。这样出问题的时候才能回溯。我们用的是简单的文件存储每次评测生成一个带时间戳的文件夹里面放所有相关文件。技巧三定期做“盲测”。每隔两周我们会挑一个已经改造完的模块让 AI 在不看 intent.md 的情况下重新做一遍然后对比两次的输出。如果差异很大说明 intent.md 的约束力不够需要加强。这个做法能有效防止 intent.md 变成“摆设”。技巧四把评测结果反馈到 intent.md 的迭代里。每次评测发现的遗漏点都要反哺到 intent.md 的模板里。比如我们发现 AI 经常忘记处理空值就在模板的 constraints 里加了一条“所有外部输入必须做空值检查”。这样下一个任务就不会再犯同样的错误。7. 关于 AI-native SDLC 的一点个人体会有人问ai-native sdlc playbook到底是什么的缩写其实它不是缩写而是一个概念把 AI 原生地嵌入到软件开发生命周期的每一个环节而不是把 AI 当成一个外挂工具。我们这六周的实践让我对这个概念有了具体的感受。最核心的变化是文档的读者变了。以前写文档是给人看的现在写 intent.md 是给 AI 看的同时也要让人能 review。这要求文档既要结构化、无歧义又要保持可读性。这个平衡点我们还在摸索但目前的做法是intent.md 用结构化字段CLAUDE.md 用自然语言加示例。另一个感受是评测比生成更重要。生成代码的成本在 AIcoding 时代大幅降低了但验证代码正确性的成本没有降低甚至因为生成量变大而增加了。所以持续评测体系的建设优先级应该高于 prompt 调优。我们后来把更多精力放在评测集维护和评测流水线优化上整体效果比单纯调 prompt 好得多。还有一个体会是人的角色在变化。以前开发者大部分时间在写代码现在更多时间在写 intent.md、review 方案、维护评测集。这不是坏事因为这些工作更接近“定义问题”而不是“解决问题”而定义问题的价值往往更高。最后分享一个我们内部的小习惯每次改造完成后团队会花十五分钟做一个简短的复盘只讨论三个问题——这次 intent.md 哪里写得好、哪里写得不好、下次怎么改。这个习惯坚持了六周我们的 intent.md 模板迭代了四个版本AI 的一次通过率从最初的不到五成提升到了七成五以上。这个提升不是靠换更好的模型而是靠把意图描述和评测反馈这两个闭环做扎实了。