先说个现象。过去几个星期我在系统整理CS146S这门课的学习笔记同时带着一个内部小项目做重构结果发现最花时间的不是写代码而是把需求描述到“人和AI都能听懂”。以前软件工程的核心是“从需求到代码”现在正慢慢变成“从模糊想法到精确描述”。如果你正在用AI辅助编程或者刚开始带团队尝试这类工具这篇文章应该能帮你省掉不少弯路。这篇笔记不是单纯介绍某个AI写代码工具而是围绕“AI进入软件工程日常之后工作方式和质量保障到底该怎么变”展开。我会从个人实践出发覆盖需求表达、工具协同、代码审查、测试策略、团队协作这几个层面。适合正在做实际项目的开发者、技术负责人也适合那些打算把AI能力纳入正规开发流程但还没想清楚边界的人。1. 为什么说“描述能力”是AI时代软件工程师的第一生产力1.1 一个任务从想法到可合并代码的完整样例我在内部工具里接到过这样一个需求给现有报表模块增加一个“导出CSV”的功能要求支持字段选择、编码为UTF-8、导出后自动下载。放在以前我先写接口、再写前端按钮、再处理文件名和边界条件前后大概需要一个下午。这次我换了一种做法先把需求描述给搭档的AI编程助手听。第一版描述写得很随意“加个导出CSV的功能能选字段点了下载。”结果生成的代码有几个问题字段选择器用的是固定列表没有从配置中读取导出的内容直接拼接字符串没有处理字段里包含逗号和换行符的情况文件名写死成“export.csv”连续导出会被浏览器重命名。这些问题单看代码都能跑但放到真实场景里全部不合格。我改成下面这种描述方式之后效果完全不一样为报表模块新增CSV导出功能需求如下 1. 字段列表从modules/report/config/columns.js读取允许用户在界面上勾选列默认全选。 2. 导出数据来自当前筛选条件下的接口返回值不额外发请求。 3. CSV格式需符合RFC 4180字段含逗号、双引号、换行符时必须正确转义。 4. 文件名格式report_{日期}_{timestamp}.csv日期使用本地时区。 5. 编码统一UTF-8并在文件头添加BOM以便Excel识别。 6. 数据量超过5万行时禁用导出按钮并提示用户缩小筛选范围。这次生成的代码基本可以直接用只有一个字段转义的边界情况需要微调。同样一个功能第一次用了两轮对话加一次手动修复第二次一次通过。差别不在于AI变聪明了而在于我把自己脑子里的约束条件全翻译出来了。1.2 描述的本质是“把隐含约束显式化”人写代码的时候很多约束是潜意识里的你知道这个接口返回什么结构你知道这个字段要不要转义你知道这个按钮点击后要不要防抖。但AI编程助手不“知道”它只能从上下文和常识里猜。所谓的提升描述能力其实就是把过去写代码时默认掌握的隐性知识变成显式、可验证、有时间顺序的要求。我总结了一个非常实用的描述模板团队里的小伙伴现在也一直在用背景和目标这个功能解决什么问题服务哪个场景。输入来源数据从哪里来格式是什么边界条件是什么。输出要求输出的格式、命名、编码、大小限制。不允许做的事明确写出哪些行为是禁止的比如不允许额外请求、不允许覆盖已有配置。验收方式怎么判断这次完成是跑通测试还是人工检查某个页面。这套模板看起来啰嗦但放在协作场景里非常划算。因为AI生成的代码质量上限基本等于描述的信息量。描述越模糊AI的“自由发挥空间”越大你要修的bug就越多。描述越精确AI的结果越接近可合并状态。提示如果你发现自己每秒能生成很多行代码但花在改bug上的时间翻倍首先应该反思的是描述质量而不是工具强弱。2. AI辅助开发的日常链路输入准备、工具协同与结果验收2.1 我目前使用的三件套配置和适用场景AI编程工具不是越贵越好也不是装得越多越好。关键是让每种能力出现在它最该出现的位置。我现在的工作流里搭配了三种不同形态的工具各管一段工具形态适用场景使用原则IDE内联补全样板代码、单元测试、胶水代码、DTO字段映射小步生成逐行检查不接受“跳一大段”对话式编程助手模块设计、算法选型、老代码解释、批量重构方案先给约束再给任务要求它列出假设自动化测试生成工具补充边界测试、生成随机输入、做属性测试只用于扩大覆盖率不做正确性判断IDE内联补全是最常用的。写一个常规的HTTP接口框架代码能被自动填得非常准确。我的经验是这类补全适合“长度不超过几十行、逻辑直白”的代码一旦它开始自动帮你写超过一百行的业务逻辑就必须喊停。因为那种跨多个函数、涉及状态变更的代码内联补全对上下文的把握往往不够生成出来的东西表面能跑实际上很可能绕过了某些重要分支。对话式编程助手主要负责“想清楚再动手”。我会让它分别提供两三个方案每个方案标注时间和空间代价并说明对现有架构的影响。它给出的答案不一定全对但作为思路的补充非常有用。比如处理一个缓存失效问题它提出给每个键增加版本号这个方案我过去在自己项目里就验证过但它能把相关思路完整列出来省去了我组织语言的时间。对比强烈的是过去我自己做技术方案要花一两个小时查文档、写草稿现在只需要半个小时而且因为AI会主动列出隐含假设我能更早发现自己方案里自相矛盾的地方。2.2 输入侧准备工作为什么我开始把需求文档写得越来越细这个观点可能和直觉相反有了AI之后很多人恨不得少写文档。但我的实测结论是文档不是写给人看的更是写给AI看的。因为文档就是AI编程助手的上下文来源文档越细它生成代码时的“猜测空间”就越小。我给自己定了个小目标凡是打算让AI参与开发的功能先在需求文档里写清楚“完成定义”。这个定义不是一句“功能可用”而是包含数据流、异常分支、性能要求的小段落。例如需求登录接口增加2FA验证。 完成定义 1. 用户输入密码后系统校验通过但尚未建立会话返回需要2FA的状态码。 2. 前端跳转到2FA输入页展示设备绑定状态。 3. 验证码有效期90秒最多允许连续错误5次超过后锁定账号10分钟。 4. 整个流程对已有会话无影响已登录用户在有效期内不触发2FA。 5. 失败日志格式统一为auth_2fa_{uid}_{result}便于后续统计。写清楚这五条AI生成的核心逻辑基本不会跑偏。最明显的收益是以前我评审同事代码时经常要猜他为什么这样写现在对照完成定义逐条过逻辑漏洞一眼就能看出来。这个习惯让我的评审效率提升了很多。2.3 结果验收不要只相信“能编译”要相信“有证明”很多开发者的习惯是代码能编译、页面能点通就算完成。但AI参与的开发流程里这个标准远远不够。因为AI生成代码的最大特点就是“局部正确、整体可疑”——它特别擅长让单个函数看起来合理却不擅长度量这个函数在真实数据流里的表现。我把验收拆成三道关口静态检查跑完代码规范校验和类型检查确认没有未使用的变量、没有隐式类型转换、没有可疑的空值处理。自动化测试不只看有没有测试还要看测试里是否覆盖了“反向用例”。AI生成的测试经常只覆盖正常路径比如传入合法参数、返回正确结果对于参数为null、超出边界、并发调用这些情况往往缺位。人工阅读关键逻辑凡是涉及状态变更、资金操作、权限判断的代码我都要求逐行读一遍。不是不信任AI而是这类代码一旦错了测试未必能完全兜住。值得一提的是我遇到过AI生成的代码在测试环境跑了好几天都没问题结果某次并发量上去之后出现两个线程同时修改同一份配置最后把状态写脏了。测试没法覆盖到的场景非常多所以“人要对每一行负责”这条底线不能放松。3. 不轻信生成的代码幻觉、合规与测试防线3.1 实践中的幻觉案例不存在的API和过度自信的注释AI生成代码有个非常迷惑人的特点它生成的内容在语法上完全正确但语义上可能根本不存在。我遇到过一次很典型的幻觉AI在代码里调用了一个叫做parseDynamicField的方法说是配置解析库提供的。我找了半天都没找到这个函数最后发现它把另一个开源库里一个语义相近的方法记错了名字然后自信地拼接出了一个不存在的API。比这个更隐蔽的是“过度自信的注释”。AI会给生成的函数附上大段注释告诉你这个函数是线程安全的、支持重入、失败自动回滚。实际上它只是“碰巧”写了这样的注释代码本身根本没有对应机制。新手看到这类注释容易直接信任结果生产环境一出问题发现注释描述的和实际行为完全是两回事。现在我的团队里立了一个规则AI生成代码的注释必须进行事实核查。不是说注释必须删除而是注释里描述的行为必须有代码实现支撑如果代码里没有锁、没有事务、没有重试逻辑注释就不能说“安全”“自动”“保证”这类词。3.2 像设安全边界一样给AI使用设边界这件事很多人容易忽略。AI生成代码的能力越强越要有边界意识。我主要设了下面几条边界边界类型禁止事项原因数据边界不允许把生产环境的真实数据粘贴到AI工具上下文防止敏感信息扩散依赖边界不允许AI直接推荐并引入来源不明的第三方库需要人工审查许可证和来源变更边界不允许AI同时改动超过10个文件超出这个范围评审不可控权限边界不允许用AI生成与权限验证相关的核心代码权限逻辑必须逐行人工确认许可证这块尤其要提一句。AI推荐第三方库时会告诉你这个库“功能很合适”但它不会告诉你这个库的开源协议跟你项目的依赖链是否兼容。我见过有人在商业项目里引入了一个宽松协议的工具库结果这个库又传递依赖了一个严格的协议库搞得法务和研发都很头疼。所以凡是AI推荐的新依赖必须人工确认两层直接依赖的许可证、间接依赖的许可证。对合规和代码来源问题我的经验是宁可麻烦一点也要在依赖引入前做检查。这和在生产环境里给配置项和API做权限校验一样是工程素养的一部分不是额外负担。3.3 测试策略从“有测试”升级到“可验证”AI辅助编程改变了我对测试的理解。以前写测试是为了证明代码符合预期现在写测试更像给AI生成的代码“擦屁股”——不是贬义而是事实AI写的快乐路径很容易边界路径全靠测试引导它修正。我的做法是给测试分成三层反向测试故意传非法值、极端值、空值看代码会不会崩。比如写一个解析函数AI生成的版本可能只处理了标准格式反向测试一个带前导空格或全角逗号的输入问题就暴露了。属性测试不写死某个输入和输出而是用随机生成的大量输入验证不变量是否成立。比如排序函数不管输入什么列表输出长度都要等于输入长度且元素多重的数量不变。回归测试每次接受AI的代码补丁把过去出现过的bug都再跑一遍防止回归。这部分以前靠人工现在可以交给自动化工具。我特别建议把“属性测试”引入常规流程。它不需要知道所有输入组合只需要定义几条“必须永远成立”的规则然后让机器用随机数据去轰炸。AI生成的代码表面看起来思路清晰但用随机数据一跑经常出现索引越界和类型假设错误。4. 从个人效率到团队协作评审规则、仓库设计与知识管理4.1 AI辅助写代码之后评审标准必须调整AI生成的代码风格通常很规整变量命名也算通顺这让评审变得更有挑战因为差的代码一眼能看出而“包装良好、逻辑欠佳”的代码非常容易蒙混过去。我们的评审标准做了这几个转变从“这段代码好不好读”转向“这段代码为什么这么写”。AI能写出可读的代码但未必能讲清楚设计原因。评审时要求补上上下文。从“有没有测试”转向“测试是否覆盖了真实风险”。比如有没有并发场景、有没有数据一致性断言、有没有权限校验。从“是否符合规范”转向“是否引入不必要的新依赖或新抽象”。AI喜欢创造通用模块经常把两三处重复代码抽象成一个复杂组件导致阅读成本大幅上升。我还调整了评审清单增加了固定条目“逐行检查所有AI生成的代码确认没有未使用的兜底逻辑”“检查注释是否描述真实行为”“检查是否在无关文件中产生了附带改动”。大部分问题都藏在“附带的无关改动”里AI生成代码时偶尔会顺手改掉其他文件如果不细看很容易把改动混进合并请求。4.2 把仓库当成AI的上下文来设计这是一个比较前期的想法如果AI生成代码的质量依赖上下文那仓库本身就应该被设计成“易被理解的结构”。我们做的第一个调整是让每段核心逻辑都有清晰的模块注释。注释不是解释每一行在做什么而是说明这个模块的边界、输入输出和依赖关系。AI读取代码时首先接触的是这些模块头对整体架构的判断会更准确生成的补充代码也更贴合现有风格。第二个调整是维护“设计决策记录”。每当团队做了一次重要技术选型比如为什么用某个缓存策略、为什么这个接口返回列表而不是分页对象都写一小段记录放进仓库。这些记录对AI来说是最好的“地图”能有效避免它生成出风格迥异的新方案。第三个调整是为常见任务准备“仓库级提示模板”。我们在仓库里放了一个名为ai/的目录里面有若干标准任务模板比如“新增一个内部API”“修复一个线上bug”“重构一个过大的函数”。每种模板都规定了描述格式和验收标准。实测下来新手用这些模板去和AI协作产出的代码质量基本能达到老手80%的水准。4.3 新成员上手与知识传承的变化AI工具对新成员的影响非常有意思。过去新人上手项目大概要花一两周读代码、问问题、写小任务。现在新人可以更快地跑通流程因为AI能直接解释代码库、生成可运行的小改动但有个新问题新人开始“只知其然不知其所以然”。我见到不止一个新人在AI的帮助下半天就能提交一个功能但被问“这个功能为什么这样设计”时完全答不上来。因为AI给的可运行代码跳过了思考过程而思考过程恰恰是训练工程判断力的核心。为了应对这个问题我把新人的入门任务做成了“三步走”先用AI完成一个小功能然后把实现思路讲给另一个同事听最后不看AI生成的结果自己独立重写一遍。独立重写这一步看起来效率不高但能在早期建立“代码所有权”意识知道自己到底懂了多少。知识传承方面我也改变了带人的方式。以前是“你遇到问题来问我”现在变成了“你带着AI给出的几种方案来找我我们一起判断哪种更合理”。这个转变节省了我大量重复答疑的时间也让新人养成了先自己检索、再求助的习惯。5. 沉淀下来的几条工作方法和最后的提醒5.1 五条可复用规则整理完这门课的笔记我把收益最高的几条规则提取出来写在了团队文档的最前面永远有人对生成的每一行负责。AI可以生成代码但它不能负责任务的责任方代码出问题背锅的还是人。所以提交前必须亲自读一遍关键逻辑。描述清楚比写代码更困难也更值钱。需求描述颗粒度直接等于代码质量上限把时间花在写清楚“完成定义”上比反复调试更高效。验收标准先于生成代码。先把“什么算完成”定下来再去和AI对话。没有验收标准的生成结果无论看起来多好都只是半成品。测试要打“不信任补丁”。我会在每次接受AI代码补丁时额外补至少一条反向测试和一条边界测试这是对AI生成代码的最低保障。仓库和文档都是AI的上下文。花在整理模块注释和设计决策上的时间会通过更高质量的生成结果加倍还回来。5.2 几个我踩过的坑第一个坑是让AI直接生成一个跨模块的大功能。它确实生成了完整代码但把配置文件的格式给改了导致另一个模块读取失败。从那以后凡是跨文件修改我一定逐文件确认改动范围。第二个坑是过度相信AI的“解释”。它能把一段混乱的老代码解释得头头是道甚至补充出原代码作者本人都没有的设计意图。后来我养成了一个习惯AI解释完老代码我必须回到调用点和数据流上重新验证一遍而不是直接拿着解释去改代码。第三个坑是没有及时更新团队约定。早期我们允许各自随意使用各种AI工具结果每个人生成的代码风格差异很大维护成本非常高。现在我们的做法是把能用AI做的任务集中到两三个标准场景中对涉及敏感数据和核心逻辑的部分统一关闭AI代码生成功能只允许人工编写。这样团队既能享受效率提升也不会陷入混乱。最后分享一个自己的体会AI时代软件工程的复杂度没有降低只是转移了。以前难在“把思路翻译成代码”现在难在“把需求翻译成可验证的描述”以及“对抗生成结果带来的盲目信任”。如果能接受这个转变并且把描述能力、审查意识和测试底线当成核心技能来练AI工具就是很扎实的生产力而不是一个随时会埋雷的加速器。希望这篇CS146S学习笔记能给你带来一些可以直接实践的启发。