AI 说问题修好了。我打开应用检查，界面符合预期，运行也正常。直到准备提交代码时，我才发现，真正应该交付的源码没有被正确修改。
这件事发生在公司的一个桌面软件项目里。项目由主程序和多个功能插件组成，插件安装后，会留下一份供应用运行的代码副本。AI 找到了这份副本，也确实把眼前的问题修好了。
但修复没有回到源码。下一次重新构建、安装，改动就可能被覆盖；其他人拿到仓库里的代码，也得不到这次修复。
页面上的结果是真的，修复无法可靠交付也是真的。 这次返工让我意识到，判断 AI 有没有完成开发，不能只看它最后展示了什么，还要看这个结果是怎么来的。
需求说清楚了，仍然可能改错地方
我后来改造 Spec Kit，起点就是这个问题。
在这次实践中，我借用了 Spec Kit 从需求出发组织开发的思路：先说清楚要解决什么、做到什么程度，再制定方案、拆分任务，最后实现。[1] 它帮助我把模糊的想法变成可以讨论和验收的要求。
不过，需求说明很难独自回答项目里的另一类问题：这个界面属于哪个插件？哪个目录才是源码？改完以后要怎样构建、安装，应用才能加载到它？
我们的项目还要通过 Gerrit 做代码评审，界面需要在真实的桌面应用里检查。通用流程里的部分联网和 GitHub 集成步骤，并不适合直接搬过来。即使需求写得足够清楚，AI 缺少这些背景，仍然可能沿着一条错误的路径完成任务。
所以，我需要补齐的是三个彼此相连的环节：需求让 AI 知道要做什么，项目知识让它知道去哪里做，验证则要证明交付的确实是这次改动。
流程的长短，要跟着问题走
把流程补完整，很容易变成另一个问题：每次改动都要先写一大堆文档。
修改一句提示文案，和调整多个插件之间的数据传递方式，显然不需要同样多的准备。前者范围清楚，后者可能牵涉接口、状态和多个模块。让它们走同一套完整流程，会让简单任务也承担复杂任务的成本。
我在入口按任务的规模和复杂程度选择流程。范围小、原因明确的修复，记录改什么、怎么改、怎样验证以及最终结果；复杂变更，再补齐需求说明、开发计划和任务清单。最后的代码提交仍然需要授权。
原因没查清楚时，就先调查。重试、清理或回退以后问题暂时消失，只能说明当前现象缓解了，还不足以判断根因已经解决。
可以缩短准备过程，但不能把调查和验证一起省掉。 这是我保留的底线。
我也删减了当前团队不需要的联网、GitHub 集成和多个 AI 协同执行等部分。这些选择服务于当时的项目环境，换一个团队，未必需要做相同的删减。
项目知识要能找到，也要有人维护
开头那次错误，暴露出一个很具体的缺口：AI 动手前，没有掌握源码、构建产物和运行副本之间的关系。
我先整理仓库地图，标明各部分代码的位置和用途，再把构建方法、安装步骤、调试入口、日志位置和历史问题放进项目知识库。对于不能直接修改的运行副本，也需要明确说明。
这些内容可以全部塞进给 AI 阅读的项目说明文件 AGENTS.md，但随着项目变大，维护会越来越吃力。每次任务都读取全部材料，也未必能帮助 AI 找到当前最需要的信息。
我的做法是按任务需要分层：开始时先读基本规则，准备修改某个插件时，再查这个插件的说明。知识库在这里更像一套有入口的项目手册，要能引导 AI 找到相关材料，而不只是存着很多文档。
团队协作还多了一层要求：不同人使用的说明，不能各自停在不同版本。我把知识、配置、操作说明和脚本整理成可安装的能力包，支持打包、版本发布、安装、更新和卸载。项目经验发生变化后，再更新并分发。
这也带来了持续的维护成本。源码位置、构建方法或调试入口变了，说明就要跟着变；过期的项目知识，同样会让 AI 沿着错误的路径做事。
验证要追到应用实际运行的那份代码
知道源码在哪里，还只能解决一部分问题。源码改好了，如果应用仍然加载旧产物，界面检查也不能说明这次修复有效。
因此，我需要把修改、构建、安装和验证连起来：先确认改动留在源码中，再确认应用运行的是对应产物，最后检查目标问题是否解决。这几步中间缺了一环，最后看到的结果就可能和准备提交的代码没有关系。
这个项目使用 Electron 构建桌面应用，界面由 Chromium 内核运行。我接入了 CDP，也就是 Chrome 开发者工具协议。通过这条调试通道，AI 可以在真实应用里操作界面、读取页面状态、检查元素和样式，并保存截图。
但能操作、能截图，并不等于已经验收通过。我希望进一步做到的是对照明确基准检查布局和视觉差异；缺少基准或必要证据时，就要说明哪些地方没有验证，不能直接给出“像素级验收通过”的结论。
以修复按钮错位为例，下面只是说明流程的简化示例，不是新增的项目实测记录：先明确按钮在哪种状态下偏离了预期位置，再找到负责这个界面的插件源码；修改后重新构建、安装，在应用中进入对应状态，检查位置并保留证据。如果问题还在，就结合页面状态和日志继续定位。
这里真正需要回答的，始终是三个问题：改动有没有留在源码里，应用有没有运行这份改动，证据能不能说明目标问题已经解决。
页面之外的问题还要依靠模块日志。只看截图，无法知道一次操作背后的数据和状态发生了什么。日志是否完整、入口是否清楚，也会影响 AI 能把调查推进到哪一步。
能连续完成任务，靠的是这些具体条件
在这次项目实践里，我已经基本能做到：一次需求澄清后，由 AI 连续完成实现和自验，再交给我验收。
这是当前项目和已有知识积累下的使用感受，没有统计成通用的成功率，也不能据此承诺换一个仓库仍有同样表现。遇到新模块、验证环境缺失，或者需求中途变化，仍然需要补充条件。
我也在持续完善项目知识，跟进官方 Spec Kit 的变化，再决定哪些改进适合吸收。[2] 这套流程需要维护；项目说明、日志入口和验收基准都不会因为接入 AI 就自动保持准确。
回到开头，AI 修改运行副本之所以容易让人误判，是因为它交出了一个很像完成的结果：问题消失了，应用也能运行。准备提交时，源码里的缺口才暴露出来。
这次改造让我更在意的是，眼前有效的结果，能不能沿着源码、构建和验证的过程，被可靠地交给其他人。 对这个项目来说，只有把这些环节接起来，我才有依据判断一次修复可以验收、可以提交。
来源与项目
[1] GitHub Spec Kit：本文沿用原稿记录的使用思路，不是对其最新版本功能的评测。https://github.com/github/spec-kit
[2] 我的 Spec Kit 改造仓库：具体实现及版本以仓库记录为准。https://github.com/liuminxin45/spec-kit