AI写代码越快，项目越乱？YOLO视觉智能体Vol.19的工程治理六层解法

AI写代码的速度越来越快，加一个页面、加一个接口似乎都是一瞬间的事。但许多开发者发现，功能增长之后，生成代码越来越容易，放心修改却越来越难。在B站UP主"YOLO视觉智能体"系列视频第19期中，作者分享了自己在第二季项目中如何通过一套工程规则来约束AI，让快速生成的代码依然可维护。

问题：AI让功能跑起来容易，让修改放心难

作者举了一个很典型的例子：项目中有大量弹窗组件。如果让AI单独再写一套弹窗，单看都能工作。但忙碌的时候能否关闭？用户能否连续点两次关闭？关闭后焦点回到哪里？这些行为可能各有各的写法。接口和业务逻辑也一样，没有明确边界时，完成当前任务最直接的办法可能就是再写一份。

这不是说AI写的代码天然更差，而是功能增长以后，规则和验证也要跟上——AI需要知道项目已经有什么，以及这次不应该再创造什么。作者从六个方面管理这些改动：规则、工作步骤和任务记录负责把改动组织起来，前端、后端和验证负责把代码落到明确边界里。

第一层：把项目约束写进AGENTS文件

以前很多要求只存在于和Codex的聊天中，这次提醒附用某个组件，下次提醒不要跨层调用，换一个任务又要解释一遍。现在作者在根目录、前端、后端分别维护AGENTS文件，记录全局业务边界、页面组件状态和API约定、领域服务异常规则等。

根目录的AGENTS文件相当长，涵盖了技术栈、环境约束、目录约束、后端设计原则、数据规范、业务工具规范以及AI编程工具的使用规则。由于不只使用Codex，还会用Cursor、opencode等工具，这个文件是写给所有AI编程工具看的。作者强调，AGENTS是指导，不是权限系统也不是测试，它要解决的是让AI知道项目有哪些约定，以及去哪里找依据。

AGENTS文件是AI编程工具生态中逐渐形成的一种约定，类似给AI看的README。它在项目根目录或子目录中存放，AI工具在会话开始时会自动读取，从而获得项目的技术栈、目录结构、编码规范和业务边界等上下文。与传统的贡献指南不同，AGENTS更强调可执行的约束和指引，例如“不要跨层调用”“优先复用某组件”，帮助AI在生成代码时避开项目已知的禁区。多个工具如Cursor、Codex、opencode都支持或兼容这一约定，使得同一份规则可以跨工具复用，减少重复解释的成本。

第二层：用Skill组织改动步骤

有了AGENTS的规则后，还需要把一次改动的步骤组织起来。作者最初使用super powers，但感觉越来越臃肿，于是自己做了一套轻量工作流，用两个skill替代：task brief和finish review。

task brief放在复杂任务动手之前，先核对已有实现，再明确目标、范围、风险和验收条件。比如统一的确认弹窗到底改哪些页面，只是接入EO组件还是修改公共行为，哪些接口不能顺手改，这些要先说清楚。finish review放在交付之前，回到同一份要求检查实际差异和验证结果：有没有漏要求、有没有扩大范围、测试实际跑了吗、还有什么没有验证。

作者还配合了planning with files这个skill使用。skill的价值是让容易遗漏的步骤有固定的入口，如果只是简单改个文案，就不必走这么完整的规划。

Skill在AI编程工具语境中，通常指一段可复用的提示词或工作流脚本，把多步操作封装成一个可调用的命令。它不同于普通的聊天指令，而是有固定输入输出和步骤顺序的“技能包”，例如“先核对已有实现，再列出目标与风险，最后输出验收条件”。Skill的价值在于把容易遗漏的检查点固化成入口，降低对模型临场发挥的依赖。轻量工作流通常只包含两三个关键skill，避免像super powers那样因功能堆叠而臃肿。开发者可以根据任务复杂度选择是否调用，简单改动不必走完整流程。

第三层：文件化计划，给长任务留下可恢复的记录

如果确认行为涉及很多页面、很多模块，需要分阶段实现，仅靠聊天记录是不够的。planning with files把计划、发现和进度落到文件里：计划记录准备怎么做，发现记录实现差异和兼容约束，进度记录已经处理了什么以及验证结果。

这三份文件不是重复写需求，而是与task brief和finish review配合。task brief明确改动计划，过程继续记录，finish review再回到同一份验收要求。换一个编程工具比如Cursor，也能读取对应的计划、发现和进度。文件化计划提供的是可恢复、可核对的工作记录。

第四层：前端治理，关注状态而非文件行数

作者曾经也把前端治理理解成文件太长就拆成几个文件，但把整个页面搬进一个大hook，或者把全部状态传给组件，复杂度并没有真正减少。现在他更关注：页面负责编排，业务hook管理相关状态和动作，业务组件负责对应区块，公共UI负责基础行为。

更容易出问题的是状态。比如保存场景：点击保存时提交的是草稿A，请求还没回来用户又编辑成B，这时候A的保存响应返回了。保存成功只能说明提交出去的内容得到服务端确认，不能把后来输入的B覆盖掉，也不能把B误认为已经保存。后台刷新也不能不经处理就覆盖未保存输入。这比减少文件行数更重要。弹窗也不是统一颜色就结束了，焦点、嵌套弹层、盲录状态都要有明确约定。

第五层：后端治理，统一能力归属而非堆砌工具类

后端同样如此。页面加一个入口、智能体加一个工具、Workflow加一个节点，如果每个入口都重新训练、导出或数据写入，就会出现几套相似但不一致的逻辑。入口可以不同，核心业务能力尽量复用：API处理参数健全和响应，领域service处理业务规则与任务创建执行，执行器真正运行训练推理或导出。

API做了健全不代表工具或Workflow就可以绕过权限，不同入口仍然要遵守同一套权限和数据边界。共享能力也要明确归属，图片入库由谁负责、YOLO结果解析由谁维护，需要统一的是同一项能力，不是把所有相似代码都塞进一个越来越大的Utils。错误处理上，项目用App Error表达预期业务失败，HTTP边界映射状态码，未知异常内部细节留在服务端日志里。但作者提醒，整理时要核对旧接口的错误结构和导入路径，移动文件不等于完成重构，真正要收敛的是能力归属、依赖方向和调用契约。

App Error是一种应用层错误类型，用于表达可预期的业务失败，例如参数不合法、资源不存在或权限不足。它与未知异常（如空指针、数据库连接失败）区分开，前者可以安全地映射为HTTP状态码返回给客户端，后者则应记录详细日志而不暴露内部细节。在分层架构中，API层负责把App Error转换为对应的4xx响应，领域服务层负责抛出这类错误，执行器层则不直接处理HTTP。这种约定让错误处理有统一入口，避免每个接口各自拼装错误结构，也便于前端根据错误码做针对性提示。

第六层：检查与验证，区分"通过"与"未验证"

前端已经有UI契约守护检查，检查未定义的CSS Token、公共组件类型或API层反向依赖的页面。但命令叫同一个名字，不代表检查范围一样，当前标准构建入口与已经接入UI契约的检查要分别核对，检查失败时是否真的阻断了后续流程也要确认——终端打印了错误不等于构建已经真正停止。

后端领域的归属、兼容导出和异常边界则对应测试另行验证，不能用前端一屏通过代表后端也通过了。浏览器加剧类型检查不等于真实浏览器操作已经通过，类型检查不能替代行为测试，构建成功不能证明按钮不会重复提交。保存响应回来以后输入还在不在、保存失败能不能重试、弹窗重渲染会不会抢焦点，这些需要对应测试和实际操作。交付时要区别通过、失败、环境跳过和尚未验证，不能把测试建议写成测试结果。

结语：AI Coding需要工程判断

回到最初的弹窗例子：弹窗改动先要明确哪些页面要调整、哪些行为必须保持，再找到项目规则、已有组件和调用位置；需要分阶段迁移就记录计划和发现；没涉及后端就保持既有接口，不为了治理完整顺手重写后端；最后核对差异、测试和页面行为。

这六方面不是一次打卡，它们共同帮助一次改动从生成一段代码，变成有范围、有边界、也有完成证据的工程行为。作者也坦言，AI coding不是装几个skill项目就一定不会乱，规则、计划、组件和检查也不能替代工程判断。真正希望做到的是，每一次AI改动都能回答三个问题：为什么改、改到哪里、凭什么认为已经完成了。AI加速代码生成，工程治理决定这些代码能不能长期留下来。

下一期作者将转向视觉任务：没有足够标注时，视觉检测还能怎么做，分别介绍开放词汇检测和工业异常检测两条路线。

背景补充

UI契约守护检查是一种静态或构建时的校验机制，用于确保前端代码遵守约定的UI规范。例如检查是否使用了未定义的CSS Token、公共组件的类型是否正确、页面是否反向依赖了API层等。这类检查通常接入构建流程，失败时阻断构建，防止不合规代码进入主分支。但命令名称相同不代表检查范围一致，不同入口可能只覆盖部分规则，因此需要分别核对实际检查项和阻断行为。终端打印错误不等于构建真正停止，必须确认退出码和后续流程是否被中断。