AI 写代码最常见的灾难

在一个十年的老系统上加一个新页面，AI 助手经常表现出令人不安的自信：引用一个代码库里不存在的公共组件，发明一套目录结构，用上代码库里从没出现过的第三方库，甚至「顺手优化」了两张核心表的结构。代码看起来漂亮，跑起来全断。更糟的是风格漂移：新代码和周围十年的代码长得不像一个项目，下一个人接手时要多读一倍注释。

这类灾难的根源只有一个：模型在凭对「好代码」的一般想象写代码，而不是在写这个系统的代码。逆向流水线把系统翻译成了文档资产（总览），feature-dev 是这些资产的正向消费者——它存在的意义，就是让 AI 在动手写之前，先被这个系统已有的约定约束住。

六条核心原则

技能的骨架是六条原则，每条都针对一种真实事故：

原则	防住的事故
先读后写，动手前必读相关代码	凭想象写代码
严格遵循既有模式和结构	风格漂移、自创目录
不引入任何新依赖	技术栈污染
不修改公共表结构和公共组件	影响面失控
不虚构任何组件、接口、目录	引用不存在的东西
全程记录开发日志	过程不可追溯

六条里有两条值得展开。不引入新依赖在老系统里几乎是铁律：引入一个新前端库，构建链、浏览器兼容、安全审计全部跟着变，这个代价模型评估不了，必须人来拍板。不虚构组件则是把大模型最典型的幻觉风险点直接圈出来点名禁止——组件名、接口路径、表名、目录，凡是代码库里的实体，一律以实际读到的为准。

第一步永远是技术栈识别

和逆向侧的 skill 一样，feature-dev 的第一步也是认栈。识别靠两条线索：构建文件（pom.xml、package.json、requirements.txt）和目录结构（src/views、controller、mapper）。认栈之后，行为被限定在该栈的分层约定里，技能为六类常见栈给了分层参照——RuoYi 系的 Vue2 前端加 MyBatis 后端、传统 JSP 加 Struts 的遗产栈、React 加 TypeScript 的新栈等，各有各的目录约定和代码组织方式。

认栈的意义在约束发挥空间。同样是「提交表单」，RuoYi 栈就该走 api/*.js 封装加 @RequestMapping 接口，模型不该在这里展示它对其他框架的了解。对的地方用对的方式，比任何单个技术选择都重要。

需求-实现映射表

feature-dev 的核心工作方法是一张映射表：把需求的每一项，映射到具体的界面元素、表字段、接口和函数上。输入可以是产品原型、功能需求文档、界面字段映射，也可以是状态机或控制逻辑描述；输出是一张逐项对应的清单。

需求项	界面元素	数据字段	接口/函数
录入合同编码	文本输入框	pbk_page.ht_bh	savePage
选择合同类型	下拉框	pbk_page.ht_type	queryDict
提交校验金额必填	校验逻辑	ht_je	handleSave 前置校验

这张表把「理解需求」变成可检查的动作。需求项有没有全部落地，一眼扫表就知道；映射到的字段和函数在不在系统里，去业务需求文档和数据字典里一查便知。逆向流水线攒的资产在这里第一次被正向消费：表字段来自数据字典，接口行为来自业务需求文档，页面上已有的功能来自链路图。写新代码的过程，就是在这张资产地图上连线。

项目级技术底座说明

六个逆向 skill 靠规则工作，feature-dev 还要吃一份项目配置：项目级技术底座说明。它把一个项目的隐式约定显式化，涵盖七项内容：前端框架与组件库版本、目录结构约定、后端框架与 ORM、数据库表结构、代码风格约定、API 设计规范、既有工具类与公共组件。

这份说明的价值在边际：第一次为项目配置它要花点工夫，此后每次开发都受益。没有它，模型每次都要现场推断「这个项目的 request 封装在哪」「日期格式化用哪个工具类」，推断错就是一次风格漂移；有了它，答案直接查表。它和逆向产物是互补关系——逆向资产说的是「系统现在长什么样」，技术底座说明说的是「在这个系统里该怎么写」。

交付前自检清单

写完代码不算完，feature-dev 要求过一遍交付前自检清单，共 11 项，覆盖从正确性到工程卫生的各个角落：映射表里的需求项是否全部实现、引用的表和字段是否与数据字典一致、是否真的没有引入新依赖、新代码与既有代码风格是否一致、必要的错误处理是否完整、开发日志是否落盘。

自检清单和输出质量控制讲的三层防线是同一个思路：把「交付质量」拆成可逐项核对的条款，不依赖模型的自觉。清单不长，过一遍成本极低，但它把「我觉得写完了」换成了「这 11 项都核过了」。

技能使用日志

每次开发会话结束，feature-dev 强制产出日志，禁止虚构：会话摘要记录做了什么决策、为什么这么做；代码列表记录新增和修改的每个文件；数据库变更单独成册，记录所有 SQL。日志落盘后，下一次开发、下一次评审、下一次回溯审计都有据可查。

数据库变更单独立册是个值得学的细节。代码变更看 diff 就有，数据库变更一旦执行就消失在库的当前状态里，不记下来，三个月后没人知道哪个字段是哪次需求加的。把 SQL 变更固化成册，等于给数据库也留了版本历史。

先查资产，再动手

feature-dev 与逆向流水线的衔接点写得很清楚：新功能开发前，先查业务需求库与数据字典。想知道这个功能系统里有没有类似实现，查模块索引；想知道要动的表有哪些字段、什么含义，查数据字典；想知道既有接口的行为边界，查业务需求文档。

逆向攒下的资产，正向开发的每一次查询都在回收成本。更重要的是回收安全感：在资产齐全的系统里，AI 写的每一行代码背后都有据可查的约定，人不再需要靠通读代码来信任它。

资产如何在日常运营中被持续消费、流水线自身怎么演进，是完结篇从逆向到正向的主题；这套流水线在三个完全不同的技术栈上的实战表现，见三栈实战复盘。