AI编码助手开发小说项目：3条工程约定减少返工

在互动小说这类状态多、分支复杂的项目中，让AI直接根据一句需求生成代码，短期看似省事，后续却可能因命名、存储方式和复用规则不一致而付出更多排查成本。一次Trae协作开发经历表明，真正影响产出质量的往往不是生成速度，而是项目是否提前建立了可执行的工程约定。

上周我让 Trae 帮我迭代一个互动小说项目的分支剧情模块，本以为半小时能搞定，结果 AI 生成的代码反复出现变量命名混乱、上下文丢失，折腾两小时才跑通。后来才看清，问题不是 AI 能力不够，是我一开始没把项目的工程约定给 AI 讲清楚。用 AI 编码助手做项目，工程约定不是「可选项」，而是「必选项」。

为什么「直接扔需求」不行

很多人用 AI 的逻辑是：直接扔需求，等它生成，有问题再改。但 AI 没有你项目的长期上下文——它不知道你当初为什么选了某个状态管理方案，不知道团队约定变量用 camelCase，更不知道哪些核心逻辑不能随便动。我之前做这个互动小说项目，一开始没给任何约定，第一次生成的角色状态代码，一会儿用全局对象存，一会儿硬编码进 localStorage，后来改剧情时频繁出现角色好感度重置、道具丢失，排查了半小时才发现是生成的代码不符合项目存储规范。

两个真实案例，让我把约定钉死

两个真实案例让我下决心把约定钉死。

案例一：角色状态管理的统一

案例一是角色状态管理的统一。互动小说的核心是角色状态：每个角色有心情、好感度、持有道具、剧情进度等属性。没约定时，AI 生成的状态存储逻辑五花八门——有的塞进全局 window 对象，有的写死在剧情判断里，还有的用不同的 key 存同一个角色的状态，跨剧情跳转时状态经常丢。

我花 10 分钟整理了第一条核心约定：所有角色状态必须封装进统一的 StateManager 类，存储 key 统一用 role_${角色ID}_${属性名} 格式，持久化只走项目统一的 storage 模块，禁止在业务逻辑里直接读写 localStorage。之后 AI 生成的状态代码自动合规，再没出现过状态丢失。

案例二：分支剧情的复用

案例二是分支剧情的复用。这个项目有上百个剧情分支，没约定时 AI 每生成新分支都重写一遍条件判断，比如「角色好感度大于 80」这个条件在不同分支里被重复写了 17 次，代码重复率高达 62%，后来改一个条件要改 17 处，效率极低。我加了第二条约定：所有分支剧情条件必须封装成独立的 Condition 类，已有的公共条件直接复用，禁止在业务逻辑里硬写判断。之后 AI 自动复用 Condition 类，重复率降到 12%，改剧情的效率提了 3 倍。

给 AI 定工程约定的几条原则

踩完这两个坑，我总结给 AI 定工程约定的几条原则。约定要具体到能执行，别写「代码要规范」这种空话，要写「变量命名用 camelCase、类名用大驼峰、状态文件统一放 src/state 目录」——AI 只认明确的指令；约定要前置到每次对话的上下文里，我把所有工程约定整理成一份 200 字的提示词，每次开新对话先贴一遍，确保 AI 生成前就知道规范；错误要及时纠正、约定要动态更新，每次 AI 生成不符合约定的代码，别只改代码，要把这条规则补进约定文档，避免下次再犯。

写在最后：产出质量取决于你给的上下文和规则

很多人以为用 AI 编码就是「提需求等生成」，但 AI 的产出质量完全取决于你给的上下文和规则。下次动手前先花 10 分钟把核心工程约定理清楚，比边写边返工划算得多——AI 再强，也没有你项目的长期积累，你给的边界越清晰，它交出来的东西越稳。