1. 代码写得快方向错得更快半年AI编程的真实体验先说结论这半年我用 AI 编程写出的代码量比过去三年手动敲的还多。项目从内部工具到中台服务都有涉及Cline、Cursor、Windsurf、VS Code Copilot、Trae 基本都深度用过中间还接过 DeepSeek 的 API 自己搭过工作流。但最后卡住我的不是模型上下文不够长也不是代码生成质量不稳定而是我自己根本写不出一份像样的需求描述。最初我也有所有程序员的通病拿到一个模糊想法打开 Cursor直接输入帮我写一个XX系统。AI 确实立刻开始生成代码文件结构、数据库表、接口定义一应俱全。第一周我甚至有点飘觉得程序员这个职业完蛋了只是时间问题。但等代码量到一定程度问题开始暴露AI 写出来的东西完全符合我的字面描述却根本不符合我的真实意图。我反复改提示词它反复重构改到最后整个代码库变得七零八落一堆死代码和没有人能说清的怪逻辑。这个经历让我意识到一个反直觉的事实AI编程真正考验的不是代码能力而是需求表达能力。以前和产品经理对接需求不清至少还有一个人能和你来回掰扯双方用沉默和默契补全信息现在对面变成了一个极度听话、绝对不和你确认、直接把所有假设当事实执行的机器你脑子里的模糊地带全部原样具象化成了代码里的错误。它能精确执行但它不会读心。这篇文章不是来吹某个工具多好用的。我想认真聊聊一个看起来特别软、实际上决定AI编程成败的问题怎么把脑子里模糊的想法变成 AI 能一次听懂、不必反复返工的输入。文章里会有我踩坑的实录、排查思路的复盘以及一套我整理出来、现在团队里所有人都在用的需求描述模板。如果你刚开始尝试 AI 编程或者已经用了 AI 编程但总觉得生成的东西不是我要的这篇文章大概率能帮你找到问题真正所在。它不在代码层而在你张口说话之前的那层思维。2. 需求不清的三种典型翻车现场AI 把大概意思执行到了极致2.1 翻车现场一用了三个月才发现 AI 建错了核心表结构这是我印象最深的失败案例。当时要做一个内部订单审核系统我的原始需求描述是帮我写一个订单管理系统支持订单录入和审核。这听起来没问题对吧AI 也确实执行了建了订单表、用户表写了录入页面、审核页面。我往里填测试数据功能都能跑。但三个月后业务方要求加订单改价功能时我发现 AI 用的是审核通过后直接改写原记录的逻辑而不是新建一条变更记录。这意味着一旦订单改过价原始价格就永久消失了财务对账直接对不上。根子在需求描述里。我当时说支持订单录入和审核从来没说清楚订单的价格字段在审核通过后是否锁定改价应该覆盖原值还是保留历史版本审核动作和修改动作之间是什么关系。AI 只能根据最常见业务逻辑来猜——而最常见的猜法就是把值改了拉倒。回头看这根本不是 AI 的错是我把业务里最核心的一条规则——价格不可追溯、改价需留痕——漏得干干净净。2.2 翻车现场二提示词越写越长代码越改越乱第二个教训是另一个极端。我后来开始认真写提示词把想到的所有细节全部堆进去一段需求写了八百多个字。我要一个任务管理模块任务有优先级、截止时间、负责人。任务状态有未开始、进行中、已完成、已取消。未开始的可以被取消进行中的不能被取消除非是管理员。已完成的任务要记录完成时间。负责人发送邮件通知。任务可以添加评论。列表要分页...AI 确实全都照做了但实现方式非常糟糕六个状态散落在一个大表的枚举字段里状态迁移逻辑全写在页面按钮的 onclick 回调中没有一处统一的状态机。后来产品说任务需要支持暂停状态时改动波及十几个文件改完这周又冒出新 bug。这次的教训是写得长不等于写得清楚。我给的是一堆零散的现象描述但完全没给约束条件和规则边界。当时我根本不知道有用户故事和验收标准这套软件工程方法论更不知道 AI 编程时需要的不是散文而是精确的行为约束。AI 没有能力从我八百字的小作文里提炼出状态机这种抽象设计它只会逐字逐句地满足我的字面要求。2.3 翻车现场三需求随手改测试全部白做第三种情况最隐蔽也最要命。项目中期产品经理没错我们小团队还是有人工的 PM虽然她只管提需求在群里随口说了句订单列表最好能导出 Excel。我在 Cursor 里随手加了一句需求AI 立刻给我加了个导出按钮还贴心地引入了两个第三方库。一切看起来很顺利直到我发现新引入的库和现有项目的 Excel 处理逻辑冲突单元测试挂了 19 个。更麻烦的是这个需求本身写得很含糊——导出 Excel客户要的是全部字段还是列表里可见字段要不要包含金额合计数据量大的时候要不要异步导出AI 全部按最简方案实现了。最惨的不是 AI 实现错了。最惨的是需求在最后两周改了四遍——导出字段、格式要求、是否加密——每次改动都要重新测。如果一开始吗就写好一份明确的需求说明和验收标准这些返工周期至少能压缩一半。2.4 三种翻车背后的共同点问题全部出在需求这一层把三种情况放一起看你会看到一个清晰的模式失败模式表面现象真实问题责任方表结构根本性错误三个月后要返工需求没写核心业务规则我需求方提示词过长越改越乱代码结构无层次需求是散文不是约束我需求方需求任意变更测试全挂返工不断没有验收标准变更无流程我需求方我花了很多时间研究 Cursor 的配置、Copilot 的提示词技巧、Windsurf 的规则文件怎么写最后发现这些工具层面的优化全部是在执行层打转。如果我输入的根本不是一个清晰规则任何工具、任何模型、再聪明的 agent都只是在忠实地放大我的混乱。AI 编程的本质是把需求规格说明变成可执行代码的快捷键。快捷键再快按错了命令也不会走到正确的地方。3. 为什么 AI 对需求的要求比人类更高输入决定输出的底层逻辑3.1 人类协作中的隐性信息补全机制AI 完全没有和人类合作时需求沟通其实有大量你不说我也知道的隐性信息补全。比如你让小张把订单状态改成已审核小张脑子里自动知道要记录审核人、审核时间、状态变更要过日志、别人只在只读状态时不允许审核。这些不是需求里写的是很多年软件工程规范沉淀出来的行业常识。AI 确实也是基于海量代码训练出来的它也有常识。但它的常识应该是全行业的平均分布未必匹配你的特定业务。更关键的是人类会主动确认AI 只会被动猜测。同一个模糊需求交给五个不同程序员五个人都会做出合理假设、问你两句、甚至帮你指出风险交给 AI它会安静地选择一个最常见假设然后写出一坨看起来非常合理的代码。这就像一个极其听话、但没有任何提问权限的实习生在干活。你让他倒杯水他会真的只倒水不加茶叶不调温度。他没有恶意他只是真的不知道。写代码也一样——所有你没说的边界、所有你没有定义的异常、所有你没给出的约束AI 不是帮你补全了而是帮你搁置了然后在代码里变成隐式的、随机的决定。更致命的是这个决定可能藏在某个深处你短期内根本发现不了。3.2 AI 编程的需求接口自然语言提示词 多文件上下文 规则文件需要明确的是AI 编程的需求输入方式和传统软件工程有不少差别但两者底层逻辑一致。传统的需求接口是需求规格说明书SRS有完整的信息架构功能需求、非功能需求、接口定义、业务规则、验收标准。而 AI 编程的需求接口拆成了三块自然语言提示词你要做什么、边界条件是什么、不能怎么做多文件上下文AI agent 读取你项目里的现有代码、配置文件、README作为隐式需求来源规则文件Cursor 的.cursor/rules文件、Windsurf 的rules文件、Copilot 的.github/copilot-instructions.md用来持久化团队的编码规范和业务约束。这三块组合在一起构成了 AI 眼中的需求规格。但大多数人只用了第一块而且用的方式是聊天式而非规格式。聊天式需求是帮我加一个导出 Excel 的功能这种一句带过AI 的自由度极大。规格式需求是在订单列表页添加导出按钮点击后生成包含订单号、金额、状态的 xlsx 文件金额大于 10000 的订单导成 result_big.xlsx这种精确行为描述。你会发现前者像谈需求后者像写需求规格书——虽然就是几行字但颗粒度完全不同。3.3 从软件工程需求文档里学到的三句话比提示词技巧更值钱我之前对需求规格说明书这种词很排斥觉得是传统软件工程那套重文档、轻代码的东西早过时了。但被 AI 坑了半年之后我重新翻开了大学教材发现三句话价值极高。第一句需求要描述做什么而不是怎么做。这意味着你的提示词应该聚焦在业务规则、行为约束、输入输出关系而不是告诉 AI用 React 写一个函数组件或者用 Python 的 pandas 处理——怎么做的决策应该留给 AI前提是你在做什么层面把规则定死。第二句每个需求都要能追溯到验收标准。这条规则解决了我翻车现场三的问题。需求文档就是一个需求条目对应一个可测试的标准。我的需求描述里如果有订单列表支持导出那后面必须跟一句验收标准点击导出按钮后下载一个包含所有列表列字段的 xlsx 文件且文件能在 Excel 中正常打开。如果写不出验收标准说明这个需求本身还不够清晰。第三句需求变更要有流程。传统软件工程里需求变更要过变更控制委员会CCB听起来官僚。但在 AI 编程场景下它变得非常实用任何需求需要改动先更新需求文档/提示词再让 AI 改代码而不是直接对着聊天框说顺便改一下这个。因为你随口改一句AI 就会立刻动手然后你还要花大量时间验证其他功能是否被破坏。没有变更记录这个回滚和排查过程根本无法进行。3.4 一个关键认知转折AI 编程需要的不是提示词是需求规格化能力现在很多人还在研究Magic Prompt能不能一步生成高质量应用研究 Cursor 和 Windsurf 谁更智能研究各种 AI 智能体工具和平台。但站在半年的真实使用时间点上我认为这些讨论方向都偏了。AI 编程工具的差异从绝对效果来说远没有想象中那么大。真正决定输出质量的上限不是模型不是工具是你给它的需求的规格化程度。同一段需求描述拿给 Cursor 和 Copilot 生成的结果差距可能不到 15%但一份规格化的需求和一份聊天式需求拿给同一个工具生成的结果差距可能是 10 倍。这个认知转变把我从工具党变成了方法论党。我开始抛弃再换一个工具看看的思路认认真真研究怎么把脑子里的想法变成 AI 能执行的规则集合。4. 一套能落地跑的 AI 需求拆解法从一句话想法到可验收的代码4.1 第一步先把一句话需求拆成五个维度我现在的习惯是拿到任何需求不管多小先拆成五个维度写下来。这五个维度是我的核心方法论直接对标软件工程需求文档里的核心章节又足够轻量适合 AI 编程场景维度要回答的问题例子业务背景为什么要做这个功能运营需要每周看订单数据手动导 Excel 太耗时角色与流程谁会用操作流程是什么运营人员点导出 → 选时间范围 → 下载文件功能边界做什么不做什么只做按时间范围导出不做定时自动化业务规则有哪些必须遵守的约束金额超过一万的要拆成单独文件权限不足不能导出验收标准怎么确定做完了导出文件能打开且字段完整关键点是功能边界那一栏。大多数人写需求只写前两栏完全不写不做什么导致 AI 自由发挥。而我被坑的几次几乎都踩在边界不清上——它自己发挥出了我根本不需要的智能。举个实际案例。我曾经需要给内部知识库加一个全文搜索功能。第一版需求描述是加个搜索支持关键词匹配能搜到文章标题和内容。AI 写了通用的 SQL LIKE 查询结果数据量一上来就慢。后来我发现这个知识库不到五千篇文章500MB 的 SQLite 足够根本不需要上 Elasticsearch。但 AI 不管这些它只会按通用最佳实践来写。如果我在功能边界里明确写上仅支持 SQLite FTS5 全文检索不引入独立搜索服务数据量在万级以内AI 的方案会完全不一样。这就是边界信息的价值它约束了 AI 的自由度让它在你的约束范围内搜索最优解而不是全行业最优解。4.2 第二步把业务规则翻译成 AI 能执行的逻辑约束业务规则是需求文档里最有技术含量的一部分。不能写订单要有充分的审核机制这种虚话要写订单状态字段只能为 pending → approved → shipped → delivered不可跳转也不可逆从 approved 到 shipped 必须由仓库角色执行这种精确逻辑。翻译成 AI 编程需求时要记住AI 对自然语言的理解是统计性的不是逻辑性的。它擅长理解如果-那么这种清晰的演绎结构不擅长理解尽量合理正常这些模糊副词。所以业务规则的表达要尽量接近伪代码的逻辑结构。我总结了一个简单的改写范式原文订单被审核后就不能再改了改写订单状态字段一旦变为 approved订单的所有可编辑字段金额、数量、收货地址均变为只读任何写操作返回错误提示只有状态为 pending 的订单允许编辑第一句话 AI 也大概能懂但不能改到底是不能改状态还是不能改字段审核后具体指什么时刻最后出现了什么错误提示这些全部跑到 AI 自由发挥区间去了。第二句话则把状态、条件、行为、异常四个要素全部定死AI 没有自由发挥的空间生成的代码自然精准。4.3 第三步给 AI 一个输入输出规格说明而非散文这一步对应软件工程里的接口定义章节。AI 编程场景下最常见的接口不是 API 接口而是三种函数级输入输出、页面级交互流、数据模型关系。函数级输入输出的写法很简单。我之前写提示词总是开发一个函数计算订单价格AI 生成了什么参数、返回什么结构、处理什么异常全靠猜。现在的写法是编写函数 calculateOrderTotal(order)输入订单对象含 items 数组每项含 quantity, unitPrice, discountRate、shippingFee 字段输出一个数字为商品总价 sum(quantity × unitPrice × (1 - discountRate)) shippingFee异常订单为空时返回 0任何商品缺少 discountRate 时按 0 处理shippingFee 为负数时抛类型错误这种写法的好处不是 AI 第一次就完全写对虽然确实大概率写对而是出错时你可以精准定位是哪条规格没有满足。没有规格说明AI 写错了你也说不清它错在哪只能模糊地说不对重写。页面级交互流同样要精确。不要写用户登录后进入首页看到订单列表要写未登录用户访问 /orders 时重定向到 /login登录成功后返回原先要访问的 /orders 页面订单列表默认按创建时间倒序每页 20 条分页后 URL 带上 ?page2页面顶部显示总数和筛选条件。这些看着繁琐但每条都在消除 AI 的猜测空间。写需求的人多用十分钟AI 执行时就能少重构十次。4.4 第四步在 Cursor / Copilot / Windsurf / Trae 里如何组织输入不同工具有不同的需求输入机制我也把四家主流产品都摸了一遍简单对比供参考工具需求输入方式我的使用心得最关键的规则Cursor聊天面板 .cursor/rules全局规则 文件引用规则文件写得好后续每次对话都受益把项目规范写进 rules比每次重复提示词高效十倍WindsurfCascade 面板 rules文件 自动读取项目上下文对多文件项目上下文理解更完整适合大改动用它做跨文件重构时需求要带上影响范围说明VS Code Copilot行内补全 聊天面板 .github/copilot-instructions.md适合小步快跑配合注释驱动开发在代码里写行级注释比大段聊天提示更直接Trae类似 Cursor 的对话式 AI IDE免费额度友好用于学习和轻量项目不错配合需求文本模板效果更好关键的输入组织方式是把需求描述模板固化成项目根目录下的一个REQUIREMENTS.md文件。这样每次对话前我可以让 AI 先读这个文件请按照 REQUIREMENTS.md 中的规范实现 X它就能利用这个持久化的上下文而不是每次重新解释一遍项目背景。4.5 第五步写完需求后自己先做一轮需求走查这一步对应软件工程里的需求评审。AI 编程场景下我们不太可能组一个正式评审会但最少要做三件事第一自己重读一遍需求描述找到所有的模糊词。几分钟内比较快合适的这种词统统杀掉替换成具体数字或者默认值 X可配置。第二模拟 AI 的执行路径。假设你是 AI读完这段需求你会怎么写表结构遇到金额计算的边界条件例如数量为 0会做什么有没有可能 AI 实现的方案和你设想完全不同如果有可能说明需求里还缺少约束。第三做一次极端场景反问。我问自己的问题通常是数据为空时怎么办并发操作时怎么办权限不足时报什么错时间超过 deadline 时怎么处理。这些问题不是为了每个都写进需求而是为了倒逼自己确认——到底哪些是 AI 可以自己决定的哪些必须定死。绝不能出现漏掉了一个关键规则代码上线两个月后才发现这种命运由 AI 决定的局面。5. 复杂项目场景下的需求管理当需求不再是一页纸能说清的事5.1 需求规格说明书简化版一页纸项目管理法很多人一听到需求规格说明书就头大觉得那是大厂流程里厚达几十页的文档。我做个人项目和小团队项目时用的是一页纸模板效果出奇地好。核心就五段章节内容在 AI 编程中的用途目标与背景这个功能/项目要解决什么问题帮 AI 理解上下文避免推荐不合适的方案用户故事作为XX角色我希望XX以便XX定位角色和核心价值AI 据此做取舍核心功能列表F1 导出订单、F2 审核订单...AI 生成模块结构和任务清单的依据约束与规则技术栈、性能要求、业务硬性规则限定 AI 的实现方案避免自由发挥验收标准每个功能对应的可测结果确认 AI 工作是否完成的判定依据对于超小型需求我会把这个模板压缩成三行。比如F1 导出订单运营点按钮获得 xlsx 文件字段含订单号/金额/状态打开文件内容正确——这已经足够 AI 执行了。真正要避免的是做一个导出功能这种只有一个名词的需求。5.2 需求追踪与变更管理AI 编程场景下的轻量方案我在翻车现场三中说的需求随手改测试全白做本质上就是缺少变更管理。传统软件工程的 CCB 流程太重落地到个人开发者我用的是一套三个文件的轻量方案第一个文件是REQUIREMENTS.md当前完整需求描述。每个功能条目带编号AI 实现完后在文件里标记[x] F1 已完成。第二个文件是CHANGELOG.md需求变更记录。任何需求的变化都记录改了哪条需求、为什么改、影响哪些功能、验收标准如何变化。哪怕只有一句话。AI 编程的特性是每一次代码改动都可以追溯到一句需求描述所以需求变更记录本质上就是代码变更的索引。第三个文件是当前激活需求列表用 ChatGPT 或 DeepSeek 的 API 可以做一次自动化梳理把现有功能和需求描述交给大语言模型让它找出代码里有但需求里没有写的功能AI 自由发挥的部分和需求里有但代码里尚未实现的功能。这个自动化检查每两周跑一次能发现大量隐患。5.3 测试用例与需求的绑定让验收从口头变成可执行软件工程里软件需求规格说明中的用例建模用 Use Case 把需求和测试连接起来。在 AI 编程里我用的方法是需求条目直接映射到测试文件一个编号对应一组测试。具体做法需求里的每条验收标准直接作为测试用例的输入。比如 F1 的验收标准是导出文件包含订单号和金额字段那测试里就是断言exportedFile.columns包含这两个字段。AI 生成代码时我会在提示词里写明同时生成满足以下验收标准的测试文件。这样最直接的好处是AI 每次改完需求我可以一键跑测试通过与否直接告诉我需求是否真正实现而不是我肉眼扫一遍页面觉得好像可以。AI 编程最大的风险是看起来实现了实际上有一堆边界条件没处理——测试文件是这个风险的最佳防火墙。5.4 多需求并存时的优先级管理给 AI 明确分层执行指令真实项目里不可能一次只做一个需求。我之前经常一次给 AI 列十几个需求它全部实现但每个都实现得半吊子——因为我没说优先级和依赖顺序。AI 会从左往右一条一条执行如果中间某个需求本身有歧义后面的所有需求都会被这个歧义污染。现在的做法把需求列表按 P0/P1/P2 分层并告诉 AI 必须按编号顺序执行一个需求验收通过后再开始下一个。同时在需求描述里加上依赖关系说明F2 依赖 F1 的数据结构在 F1 完成前不需要实现 F2 的存储逻辑只需要定义接口和页面原型。这本质上就是传统软件工程里的迭代计划只不过执行者是一个 AI agent。给 AI 分层既避免了并发任务导致的上下文污染也让每次验收变得干净可控。6. 从需求文档到AI Agent 协作把我现在的工作流完整拆给你看6.1 一个典型需求的完整流转链路从想法到代码落地最后分享一套我自己现在每天在用的工作流。以最近做的库存告警通知功能为例完整走一遍第一步把原始想法拆成需求五维度写进REQUIREMENTS.mdF3 库存告警通知功能业务背景仓库库存低于安全阈值时需要通知采购员当前依靠人工盯盘效率低角色流程库存变动时触发检测 → 低于阈值 → 发送企业微信通知 → 采购员确认后标记已处理功能边界只做库存低于阈值的检测和通知不做补货单生成、不做采购流程管理业务规则同一 SKU 在 24 小时内不重复通知通知接收人为该 SKU 对应的采购员标记已处理后 48 小时内不再触发该 SKU 的通知验收标准输入一个库存低于阈值的 SKU能收到通知收到通知后点击已处理再次触发时不重复通知24 小时内重复触发时跳过。第二步处理与 AI 协作的上下文输入。我打开 Cursor先让 AI 读取REQUIREMENTS.md然后把库存变动的相关代码文件用引用到对话中补充一句请基于现有项目的框架为 F3 编写完整实现包括数据库迁移、服务层逻辑、企业微信通知接口对接和对应的测试文件。第三步等待 AI 生成后跑一遍我提前写好的测试脚本。没有测试脚本的需求视为未完成。测试通过后我才会做人工 code review。这个流程跑通了三个月返工率下降非常明显。尤其是业务规则那一栏只要规则写清楚AI 生成的一次通过率非常高。凡是返工的十次里有八次是因为我在业务规则里漏了条件。6.2 AI Agent 在做需求操作时经常需要提升的四个地方前面提到热词里有一个需求操作需要提升我的理解是AI Agent 做需求实现时经常在以下几个环节表现不稳定需要使用者主动喂更多信息第一数据模型的建模选择。AI 经常在新增一张表和复用已有表加字段之间做出错误判断。我现在的对策在需求描述里明确数据模型请复用现有 users 表不要新建用户表。如果需求本身对数据模型没把握就先让 AI 生成方案而不是直接让它写代码。第二异常处理策略。AI 写异常处理的常见问题是吞掉异常catch 了不处理或过度处理每个函数都套 try-catch。如果需求里没有明确异常策略AI 的表现完全随机。我通常在需求里加一句失败时的行为记录错误日志并返回友好错误信息业务数据不落库。第三日志和可观测性。AI 默认不写日志或者只在关键入口写简单的console.log。如果项目依赖日志排查问题需要在需求里明确日志级别INFO 记录入参和出参ERROR 记录堆栈敏感字段脱敏。第四性能和容量的预判。AI 喜欢按通用最佳实践生成代码但这种最佳实践往往是为大规模系统准备的比如引入缓存、消息队列用到小项目上就是过度设计。我一般在项目根目录的REQUIREMENTS.md里写一段全局性能声明本项目为内部工具日活不超过 100 人数据量在 10 万行以内优先考虑实现简单性而非扩展性。这一句话能让 AI 少写大量无用代码。6.3 大语言模型 API 做需求梳理的斜杠用法除了直接用 AI 编程工具我发现把需求梳理本身交给大模型 API比如 DeepSeek 的 api也是一个很高效的做法。这不是让 AI 替我写需求而是让它帮你发现需求的漏洞。具体做法把你写好的需求五维度发给 DeepSeek或其他模型加上一句提示词请扮演资深产品经理审查这份需求描述找出所有可能产生歧义的地方。输出格式每个歧义点对应一个具体问题我需要针对这个问题修改需求。几秒钟后它会返回十几个问题F3 的同一 SKU 在 24 小时内不重复通知如果 SKU 从低于阈值恢复后又再次低于阈值也算同一 24 小时吗企业微信通知接口有频控限制吗超过频控时的降级策略是什么这些我根本没有想到的边界问题一次就被挖了出来。我把这些问题逐条补进需求文档再给 Cursor 执行。我经常把这称之为我打草稿、AI 做验收审查、我修订、AI 再实现的循环返工率确实降得非常明显。6.4 给 Cursor / Copilot 场景下的规则文件书写样板最后放一个我常用的.cursor/rules文件精简版适合中小型项目。你可以根据自己的情况改# 项目全局规则 ## 通用 - 本项目为内部工具优先考虑实现简单性不做过度设计 - 所有新增字段需要同时在数据库迁移文件和对应 TypeScript 类型中更新 - 所有外部 API 调用必须包含超时和错误日志 ## 数据模型 - 新表必须包含 id自增主键、created_at、updated_at 字段 - 不要轻易新增表优先在现有表上扩展字段 ## 接口实现 - 所有服务层函数必须包含输入校验 - 金额统一使用 decimal 类型禁止使用 float - 各类枚举值必须定义为常量禁止散落在代码里 ## 测试 - 每个需求功能必须附带对应测试文件 - 测试使用项目现有的测试框架不要引入新框架把这份规则文件丢给项目之后AI 生成的代码整体质量稳定了一大截。但请注意规则文件是全局兜底的需求约束具体每个功能的具体规则还是要靠你在每次提示词中写清楚。规则文件解决那些你不想每次重复说的常规约束功能提示词解决那些这个功能特有的行为规则两者缺一不可。7. 写在最后把我踩过的坑总结成几句不太中听的大实话回头看这半年我的最大收获不是学会了 Cursor 的某个快捷键也不是掌握了多复杂的提示词技巧而是老老实实把大学软件工程课里的需求分析重新捡了回来。这件事听起来一点都不酷但它真的解决了我 80% 的返工痛苦。如果你也在用 AI 编程我建议你别急着研究下一个新工具也别在哪个 AI 编程智能体工具更强这种问题上多花时间。先试着把你下一个需求写到能够回答下面五个问题这个功能给谁用解决他的什么问题业务背景操作流程的每一步是什么角色流程哪些事是这个功能绝对不做的功能边界数据的变换规则有哪些硬性条件业务规则我凭什么认为它做完了验收标准五个问题回答完你花十分钟写的文字比之前花一小时写的长篇提示词更值钱。我实测下来这类需求描述 AI 的一次生成通过率至少翻了一倍。另一个大的体会是逐步养成需求先于代码的肌肉记忆。这半年我最大的改变是打开 Cursor 的第一件事不再是在对话框里描述功能而是打开REQUIREMENTS.md把需求改清楚。代码只有在上面的需求理清楚之后才算开始。这个习惯刚开始会觉得很麻烦觉得多此一举但坚持一个月之后你会和我一样发现写需求的时间只是换一种方式花在了代码上。它不会增加你的总工作量它只是把隐性的返工成本显性化了变成了写文档的时间——而显性化的成本总是更容易被控制。最后分享一个我非常私人的判断标准如果你的需求描述写完之后你自己读一遍觉得这个活好像也不是很难嘛那大概率说明需求写得够好了。真正清晰的需求会让你觉得实现它很简单——因为复杂度已经被你消化在描述里了。这恰恰说明AI编程时代最先卡住你的永远不会是代码而是你把复杂世界翻译成精确规则的能力。 
长河君 · 2026/11/4 8:23:12 · 阅读 1.2k AI编程需求拆解法：把模糊想法变成可验收代码的经验谈
1. 代码写得快方向错得更快半年AI编程的真实体验先说结论这半年我用 AI 编程写出的代码量比过去三年手动敲的还多。项目从内部工具到中台服务都有涉及Cline、Cursor、Windsurf、VS Code Copilot、Trae 基本都深度用过中间还接过 DeepSeek 的 API 自己搭过工作流。但最后卡住我的不是模型上下文不够长也不是代码生成质量不稳定而是我自己根本写不出一份像样的需求描述。最初我也有所有程序员的通病拿到一个模糊想法打开 Cursor直接输入帮我写一个XX系统。AI 确实立刻开始生成代码文件结构、数据库表、接口定义一应俱全。第一周我甚至有点飘觉得程序员这个职业完蛋了只是时间问题。但等代码量到一定程度问题开始暴露AI 写出来的东西完全符合我的字面描述却根本不符合我的真实意图。我反复改提示词它反复重构改到最后整个代码库变得七零八落一堆死代码和没有人能说清的怪逻辑。这个经历让我意识到一个反直觉的事实AI编程真正考验的不是代码能力而是需求表达能力。以前和产品经理对接需求不清至少还有一个人能和你来回掰扯双方用沉默和默契补全信息现在对面变成了一个极度听话、绝对不和你确认、直接把所有假设当事实执行的机器你脑子里的模糊地带全部原样具象化成了代码里的错误。它能精确执行但它不会读心。这篇文章不是来吹某个工具多好用的。我想认真聊聊一个看起来特别软、实际上决定AI编程成败的问题怎么把脑子里模糊的想法变成 AI 能一次听懂、不必反复返工的输入。文章里会有我踩坑的实录、排查思路的复盘以及一套我整理出来、现在团队里所有人都在用的需求描述模板。如果你刚开始尝试 AI 编程或者已经用了 AI 编程但总觉得生成的东西不是我要的这篇文章大概率能帮你找到问题真正所在。它不在代码层而在你张口说话之前的那层思维。2. 需求不清的三种典型翻车现场AI 把大概意思执行到了极致2.1 翻车现场一用了三个月才发现 AI 建错了核心表结构这是我印象最深的失败案例。当时要做一个内部订单审核系统我的原始需求描述是帮我写一个订单管理系统支持订单录入和审核。这听起来没问题对吧AI 也确实执行了建了订单表、用户表写了录入页面、审核页面。我往里填测试数据功能都能跑。但三个月后业务方要求加订单改价功能时我发现 AI 用的是审核通过后直接改写原记录的逻辑而不是新建一条变更记录。这意味着一旦订单改过价原始价格就永久消失了财务对账直接对不上。根子在需求描述里。我当时说支持订单录入和审核从来没说清楚订单的价格字段在审核通过后是否锁定改价应该覆盖原值还是保留历史版本审核动作和修改动作之间是什么关系。AI 只能根据最常见业务逻辑来猜——而最常见的猜法就是把值改了拉倒。回头看这根本不是 AI 的错是我把业务里最核心的一条规则——价格不可追溯、改价需留痕——漏得干干净净。2.2 翻车现场二提示词越写越长代码越改越乱第二个教训是另一个极端。我后来开始认真写提示词把想到的所有细节全部堆进去一段需求写了八百多个字。我要一个任务管理模块任务有优先级、截止时间、负责人。任务状态有未开始、进行中、已完成、已取消。未开始的可以被取消进行中的不能被取消除非是管理员。已完成的任务要记录完成时间。负责人发送邮件通知。任务可以添加评论。列表要分页...AI 确实全都照做了但实现方式非常糟糕六个状态散落在一个大表的枚举字段里状态迁移逻辑全写在页面按钮的 onclick 回调中没有一处统一的状态机。后来产品说任务需要支持暂停状态时改动波及十几个文件改完这周又冒出新 bug。这次的教训是写得长不等于写得清楚。我给的是一堆零散的现象描述但完全没给约束条件和规则边界。当时我根本不知道有用户故事和验收标准这套软件工程方法论更不知道 AI 编程时需要的不是散文而是精确的行为约束。AI 没有能力从我八百字的小作文里提炼出状态机这种抽象设计它只会逐字逐句地满足我的字面要求。2.3 翻车现场三需求随手改测试全部白做第三种情况最隐蔽也最要命。项目中期产品经理没错我们小团队还是有人工的 PM虽然她只管提需求在群里随口说了句订单列表最好能导出 Excel。我在 Cursor 里随手加了一句需求AI 立刻给我加了个导出按钮还贴心地引入了两个第三方库。一切看起来很顺利直到我发现新引入的库和现有项目的 Excel 处理逻辑冲突单元测试挂了 19 个。更麻烦的是这个需求本身写得很含糊——导出 Excel客户要的是全部字段还是列表里可见字段要不要包含金额合计数据量大的时候要不要异步导出AI 全部按最简方案实现了。最惨的不是 AI 实现错了。最惨的是需求在最后两周改了四遍——导出字段、格式要求、是否加密——每次改动都要重新测。如果一开始吗就写好一份明确的需求说明和验收标准这些返工周期至少能压缩一半。2.4 三种翻车背后的共同点问题全部出在需求这一层把三种情况放一起看你会看到一个清晰的模式失败模式表面现象真实问题责任方表结构根本性错误三个月后要返工需求没写核心业务规则我需求方提示词过长越改越乱代码结构无层次需求是散文不是约束我需求方需求任意变更测试全挂返工不断没有验收标准变更无流程我需求方我花了很多时间研究 Cursor 的配置、Copilot 的提示词技巧、Windsurf 的规则文件怎么写最后发现这些工具层面的优化全部是在执行层打转。如果我输入的根本不是一个清晰规则任何工具、任何模型、再聪明的 agent都只是在忠实地放大我的混乱。AI 编程的本质是把需求规格说明变成可执行代码的快捷键。快捷键再快按错了命令也不会走到正确的地方。3. 为什么 AI 对需求的要求比人类更高输入决定输出的底层逻辑3.1 人类协作中的隐性信息补全机制AI 完全没有和人类合作时需求沟通其实有大量你不说我也知道的隐性信息补全。比如你让小张把订单状态改成已审核小张脑子里自动知道要记录审核人、审核时间、状态变更要过日志、别人只在只读状态时不允许审核。这些不是需求里写的是很多年软件工程规范沉淀出来的行业常识。AI 确实也是基于海量代码训练出来的它也有常识。但它的常识应该是全行业的平均分布未必匹配你的特定业务。更关键的是人类会主动确认AI 只会被动猜测。同一个模糊需求交给五个不同程序员五个人都会做出合理假设、问你两句、甚至帮你指出风险交给 AI它会安静地选择一个最常见假设然后写出一坨看起来非常合理的代码。这就像一个极其听话、但没有任何提问权限的实习生在干活。你让他倒杯水他会真的只倒水不加茶叶不调温度。他没有恶意他只是真的不知道。写代码也一样——所有你没说的边界、所有你没有定义的异常、所有你没给出的约束AI 不是帮你补全了而是帮你搁置了然后在代码里变成隐式的、随机的决定。更致命的是这个决定可能藏在某个深处你短期内根本发现不了。3.2 AI 编程的需求接口自然语言提示词 多文件上下文 规则文件需要明确的是AI 编程的需求输入方式和传统软件工程有不少差别但两者底层逻辑一致。传统的需求接口是需求规格说明书SRS有完整的信息架构功能需求、非功能需求、接口定义、业务规则、验收标准。而 AI 编程的需求接口拆成了三块自然语言提示词你要做什么、边界条件是什么、不能怎么做多文件上下文AI agent 读取你项目里的现有代码、配置文件、README作为隐式需求来源规则文件Cursor 的.cursor/rules文件、Windsurf 的rules文件、Copilot 的.github/copilot-instructions.md用来持久化团队的编码规范和业务约束。这三块组合在一起构成了 AI 眼中的需求规格。但大多数人只用了第一块而且用的方式是聊天式而非规格式。聊天式需求是帮我加一个导出 Excel 的功能这种一句带过AI 的自由度极大。规格式需求是在订单列表页添加导出按钮点击后生成包含订单号、金额、状态的 xlsx 文件金额大于 10000 的订单导成 result_big.xlsx这种精确行为描述。你会发现前者像谈需求后者像写需求规格书——虽然就是几行字但颗粒度完全不同。3.3 从软件工程需求文档里学到的三句话比提示词技巧更值钱我之前对需求规格说明书这种词很排斥觉得是传统软件工程那套重文档、轻代码的东西早过时了。但被 AI 坑了半年之后我重新翻开了大学教材发现三句话价值极高。第一句需求要描述做什么而不是怎么做。这意味着你的提示词应该聚焦在业务规则、行为约束、输入输出关系而不是告诉 AI用 React 写一个函数组件或者用 Python 的 pandas 处理——怎么做的决策应该留给 AI前提是你在做什么层面把规则定死。第二句每个需求都要能追溯到验收标准。这条规则解决了我翻车现场三的问题。需求文档就是一个需求条目对应一个可测试的标准。我的需求描述里如果有订单列表支持导出那后面必须跟一句验收标准点击导出按钮后下载一个包含所有列表列字段的 xlsx 文件且文件能在 Excel 中正常打开。如果写不出验收标准说明这个需求本身还不够清晰。第三句需求变更要有流程。传统软件工程里需求变更要过变更控制委员会CCB听起来官僚。但在 AI 编程场景下它变得非常实用任何需求需要改动先更新需求文档/提示词再让 AI 改代码而不是直接对着聊天框说顺便改一下这个。因为你随口改一句AI 就会立刻动手然后你还要花大量时间验证其他功能是否被破坏。没有变更记录这个回滚和排查过程根本无法进行。3.4 一个关键认知转折AI 编程需要的不是提示词是需求规格化能力现在很多人还在研究Magic Prompt能不能一步生成高质量应用研究 Cursor 和 Windsurf 谁更智能研究各种 AI 智能体工具和平台。但站在半年的真实使用时间点上我认为这些讨论方向都偏了。AI 编程工具的差异从绝对效果来说远没有想象中那么大。真正决定输出质量的上限不是模型不是工具是你给它的需求的规格化程度。同一段需求描述拿给 Cursor 和 Copilot 生成的结果差距可能不到 15%但一份规格化的需求和一份聊天式需求拿给同一个工具生成的结果差距可能是 10 倍。这个认知转变把我从工具党变成了方法论党。我开始抛弃再换一个工具看看的思路认认真真研究怎么把脑子里的想法变成 AI 能执行的规则集合。4. 一套能落地跑的 AI 需求拆解法从一句话想法到可验收的代码4.1 第一步先把一句话需求拆成五个维度我现在的习惯是拿到任何需求不管多小先拆成五个维度写下来。这五个维度是我的核心方法论直接对标软件工程需求文档里的核心章节又足够轻量适合 AI 编程场景维度要回答的问题例子业务背景为什么要做这个功能运营需要每周看订单数据手动导 Excel 太耗时角色与流程谁会用操作流程是什么运营人员点导出 → 选时间范围 → 下载文件功能边界做什么不做什么只做按时间范围导出不做定时自动化业务规则有哪些必须遵守的约束金额超过一万的要拆成单独文件权限不足不能导出验收标准怎么确定做完了导出文件能打开且字段完整关键点是功能边界那一栏。大多数人写需求只写前两栏完全不写不做什么导致 AI 自由发挥。而我被坑的几次几乎都踩在边界不清上——它自己发挥出了我根本不需要的智能。举个实际案例。我曾经需要给内部知识库加一个全文搜索功能。第一版需求描述是加个搜索支持关键词匹配能搜到文章标题和内容。AI 写了通用的 SQL LIKE 查询结果数据量一上来就慢。后来我发现这个知识库不到五千篇文章500MB 的 SQLite 足够根本不需要上 Elasticsearch。但 AI 不管这些它只会按通用最佳实践来写。如果我在功能边界里明确写上仅支持 SQLite FTS5 全文检索不引入独立搜索服务数据量在万级以内AI 的方案会完全不一样。这就是边界信息的价值它约束了 AI 的自由度让它在你的约束范围内搜索最优解而不是全行业最优解。4.2 第二步把业务规则翻译成 AI 能执行的逻辑约束业务规则是需求文档里最有技术含量的一部分。不能写订单要有充分的审核机制这种虚话要写订单状态字段只能为 pending → approved → shipped → delivered不可跳转也不可逆从 approved 到 shipped 必须由仓库角色执行这种精确逻辑。翻译成 AI 编程需求时要记住AI 对自然语言的理解是统计性的不是逻辑性的。它擅长理解如果-那么这种清晰的演绎结构不擅长理解尽量合理正常这些模糊副词。所以业务规则的表达要尽量接近伪代码的逻辑结构。我总结了一个简单的改写范式原文订单被审核后就不能再改了改写订单状态字段一旦变为 approved订单的所有可编辑字段金额、数量、收货地址均变为只读任何写操作返回错误提示只有状态为 pending 的订单允许编辑第一句话 AI 也大概能懂但不能改到底是不能改状态还是不能改字段审核后具体指什么时刻最后出现了什么错误提示这些全部跑到 AI 自由发挥区间去了。第二句话则把状态、条件、行为、异常四个要素全部定死AI 没有自由发挥的空间生成的代码自然精准。4.3 第三步给 AI 一个输入输出规格说明而非散文这一步对应软件工程里的接口定义章节。AI 编程场景下最常见的接口不是 API 接口而是三种函数级输入输出、页面级交互流、数据模型关系。函数级输入输出的写法很简单。我之前写提示词总是开发一个函数计算订单价格AI 生成了什么参数、返回什么结构、处理什么异常全靠猜。现在的写法是编写函数 calculateOrderTotal(order)输入订单对象含 items 数组每项含 quantity, unitPrice, discountRate、shippingFee 字段输出一个数字为商品总价 sum(quantity × unitPrice × (1 - discountRate)) shippingFee异常订单为空时返回 0任何商品缺少 discountRate 时按 0 处理shippingFee 为负数时抛类型错误这种写法的好处不是 AI 第一次就完全写对虽然确实大概率写对而是出错时你可以精准定位是哪条规格没有满足。没有规格说明AI 写错了你也说不清它错在哪只能模糊地说不对重写。页面级交互流同样要精确。不要写用户登录后进入首页看到订单列表要写未登录用户访问 /orders 时重定向到 /login登录成功后返回原先要访问的 /orders 页面订单列表默认按创建时间倒序每页 20 条分页后 URL 带上 ?page2页面顶部显示总数和筛选条件。这些看着繁琐但每条都在消除 AI 的猜测空间。写需求的人多用十分钟AI 执行时就能少重构十次。4.4 第四步在 Cursor / Copilot / Windsurf / Trae 里如何组织输入不同工具有不同的需求输入机制我也把四家主流产品都摸了一遍简单对比供参考工具需求输入方式我的使用心得最关键的规则Cursor聊天面板 .cursor/rules全局规则 文件引用规则文件写得好后续每次对话都受益把项目规范写进 rules比每次重复提示词高效十倍WindsurfCascade 面板 rules文件 自动读取项目上下文对多文件项目上下文理解更完整适合大改动用它做跨文件重构时需求要带上影响范围说明VS Code Copilot行内补全 聊天面板 .github/copilot-instructions.md适合小步快跑配合注释驱动开发在代码里写行级注释比大段聊天提示更直接Trae类似 Cursor 的对话式 AI IDE免费额度友好用于学习和轻量项目不错配合需求文本模板效果更好关键的输入组织方式是把需求描述模板固化成项目根目录下的一个REQUIREMENTS.md文件。这样每次对话前我可以让 AI 先读这个文件请按照 REQUIREMENTS.md 中的规范实现 X它就能利用这个持久化的上下文而不是每次重新解释一遍项目背景。4.5 第五步写完需求后自己先做一轮需求走查这一步对应软件工程里的需求评审。AI 编程场景下我们不太可能组一个正式评审会但最少要做三件事第一自己重读一遍需求描述找到所有的模糊词。几分钟内比较快合适的这种词统统杀掉替换成具体数字或者默认值 X可配置。第二模拟 AI 的执行路径。假设你是 AI读完这段需求你会怎么写表结构遇到金额计算的边界条件例如数量为 0会做什么有没有可能 AI 实现的方案和你设想完全不同如果有可能说明需求里还缺少约束。第三做一次极端场景反问。我问自己的问题通常是数据为空时怎么办并发操作时怎么办权限不足时报什么错时间超过 deadline 时怎么处理。这些问题不是为了每个都写进需求而是为了倒逼自己确认——到底哪些是 AI 可以自己决定的哪些必须定死。绝不能出现漏掉了一个关键规则代码上线两个月后才发现这种命运由 AI 决定的局面。5. 复杂项目场景下的需求管理当需求不再是一页纸能说清的事5.1 需求规格说明书简化版一页纸项目管理法很多人一听到需求规格说明书就头大觉得那是大厂流程里厚达几十页的文档。我做个人项目和小团队项目时用的是一页纸模板效果出奇地好。核心就五段章节内容在 AI 编程中的用途目标与背景这个功能/项目要解决什么问题帮 AI 理解上下文避免推荐不合适的方案用户故事作为XX角色我希望XX以便XX定位角色和核心价值AI 据此做取舍核心功能列表F1 导出订单、F2 审核订单...AI 生成模块结构和任务清单的依据约束与规则技术栈、性能要求、业务硬性规则限定 AI 的实现方案避免自由发挥验收标准每个功能对应的可测结果确认 AI 工作是否完成的判定依据对于超小型需求我会把这个模板压缩成三行。比如F1 导出订单运营点按钮获得 xlsx 文件字段含订单号/金额/状态打开文件内容正确——这已经足够 AI 执行了。真正要避免的是做一个导出功能这种只有一个名词的需求。5.2 需求追踪与变更管理AI 编程场景下的轻量方案我在翻车现场三中说的需求随手改测试全白做本质上就是缺少变更管理。传统软件工程的 CCB 流程太重落地到个人开发者我用的是一套三个文件的轻量方案第一个文件是REQUIREMENTS.md当前完整需求描述。每个功能条目带编号AI 实现完后在文件里标记[x] F1 已完成。第二个文件是CHANGELOG.md需求变更记录。任何需求的变化都记录改了哪条需求、为什么改、影响哪些功能、验收标准如何变化。哪怕只有一句话。AI 编程的特性是每一次代码改动都可以追溯到一句需求描述所以需求变更记录本质上就是代码变更的索引。第三个文件是当前激活需求列表用 ChatGPT 或 DeepSeek 的 API 可以做一次自动化梳理把现有功能和需求描述交给大语言模型让它找出代码里有但需求里没有写的功能AI 自由发挥的部分和需求里有但代码里尚未实现的功能。这个自动化检查每两周跑一次能发现大量隐患。5.3 测试用例与需求的绑定让验收从口头变成可执行软件工程里软件需求规格说明中的用例建模用 Use Case 把需求和测试连接起来。在 AI 编程里我用的方法是需求条目直接映射到测试文件一个编号对应一组测试。具体做法需求里的每条验收标准直接作为测试用例的输入。比如 F1 的验收标准是导出文件包含订单号和金额字段那测试里就是断言exportedFile.columns包含这两个字段。AI 生成代码时我会在提示词里写明同时生成满足以下验收标准的测试文件。这样最直接的好处是AI 每次改完需求我可以一键跑测试通过与否直接告诉我需求是否真正实现而不是我肉眼扫一遍页面觉得好像可以。AI 编程最大的风险是看起来实现了实际上有一堆边界条件没处理——测试文件是这个风险的最佳防火墙。5.4 多需求并存时的优先级管理给 AI 明确分层执行指令真实项目里不可能一次只做一个需求。我之前经常一次给 AI 列十几个需求它全部实现但每个都实现得半吊子——因为我没说优先级和依赖顺序。AI 会从左往右一条一条执行如果中间某个需求本身有歧义后面的所有需求都会被这个歧义污染。现在的做法把需求列表按 P0/P1/P2 分层并告诉 AI 必须按编号顺序执行一个需求验收通过后再开始下一个。同时在需求描述里加上依赖关系说明F2 依赖 F1 的数据结构在 F1 完成前不需要实现 F2 的存储逻辑只需要定义接口和页面原型。这本质上就是传统软件工程里的迭代计划只不过执行者是一个 AI agent。给 AI 分层既避免了并发任务导致的上下文污染也让每次验收变得干净可控。6. 从需求文档到AI Agent 协作把我现在的工作流完整拆给你看6.1 一个典型需求的完整流转链路从想法到代码落地最后分享一套我自己现在每天在用的工作流。以最近做的库存告警通知功能为例完整走一遍第一步把原始想法拆成需求五维度写进REQUIREMENTS.mdF3 库存告警通知功能业务背景仓库库存低于安全阈值时需要通知采购员当前依靠人工盯盘效率低角色流程库存变动时触发检测 → 低于阈值 → 发送企业微信通知 → 采购员确认后标记已处理功能边界只做库存低于阈值的检测和通知不做补货单生成、不做采购流程管理业务规则同一 SKU 在 24 小时内不重复通知通知接收人为该 SKU 对应的采购员标记已处理后 48 小时内不再触发该 SKU 的通知验收标准输入一个库存低于阈值的 SKU能收到通知收到通知后点击已处理再次触发时不重复通知24 小时内重复触发时跳过。第二步处理与 AI 协作的上下文输入。我打开 Cursor先让 AI 读取REQUIREMENTS.md然后把库存变动的相关代码文件用引用到对话中补充一句请基于现有项目的框架为 F3 编写完整实现包括数据库迁移、服务层逻辑、企业微信通知接口对接和对应的测试文件。第三步等待 AI 生成后跑一遍我提前写好的测试脚本。没有测试脚本的需求视为未完成。测试通过后我才会做人工 code review。这个流程跑通了三个月返工率下降非常明显。尤其是业务规则那一栏只要规则写清楚AI 生成的一次通过率非常高。凡是返工的十次里有八次是因为我在业务规则里漏了条件。6.2 AI Agent 在做需求操作时经常需要提升的四个地方前面提到热词里有一个需求操作需要提升我的理解是AI Agent 做需求实现时经常在以下几个环节表现不稳定需要使用者主动喂更多信息第一数据模型的建模选择。AI 经常在新增一张表和复用已有表加字段之间做出错误判断。我现在的对策在需求描述里明确数据模型请复用现有 users 表不要新建用户表。如果需求本身对数据模型没把握就先让 AI 生成方案而不是直接让它写代码。第二异常处理策略。AI 写异常处理的常见问题是吞掉异常catch 了不处理或过度处理每个函数都套 try-catch。如果需求里没有明确异常策略AI 的表现完全随机。我通常在需求里加一句失败时的行为记录错误日志并返回友好错误信息业务数据不落库。第三日志和可观测性。AI 默认不写日志或者只在关键入口写简单的console.log。如果项目依赖日志排查问题需要在需求里明确日志级别INFO 记录入参和出参ERROR 记录堆栈敏感字段脱敏。第四性能和容量的预判。AI 喜欢按通用最佳实践生成代码但这种最佳实践往往是为大规模系统准备的比如引入缓存、消息队列用到小项目上就是过度设计。我一般在项目根目录的REQUIREMENTS.md里写一段全局性能声明本项目为内部工具日活不超过 100 人数据量在 10 万行以内优先考虑实现简单性而非扩展性。这一句话能让 AI 少写大量无用代码。6.3 大语言模型 API 做需求梳理的斜杠用法除了直接用 AI 编程工具我发现把需求梳理本身交给大模型 API比如 DeepSeek 的 api也是一个很高效的做法。这不是让 AI 替我写需求而是让它帮你发现需求的漏洞。具体做法把你写好的需求五维度发给 DeepSeek或其他模型加上一句提示词请扮演资深产品经理审查这份需求描述找出所有可能产生歧义的地方。输出格式每个歧义点对应一个具体问题我需要针对这个问题修改需求。几秒钟后它会返回十几个问题F3 的同一 SKU 在 24 小时内不重复通知如果 SKU 从低于阈值恢复后又再次低于阈值也算同一 24 小时吗企业微信通知接口有频控限制吗超过频控时的降级策略是什么这些我根本没有想到的边界问题一次就被挖了出来。我把这些问题逐条补进需求文档再给 Cursor 执行。我经常把这称之为我打草稿、AI 做验收审查、我修订、AI 再实现的循环返工率确实降得非常明显。6.4 给 Cursor / Copilot 场景下的规则文件书写样板最后放一个我常用的.cursor/rules文件精简版适合中小型项目。你可以根据自己的情况改# 项目全局规则 ## 通用 - 本项目为内部工具优先考虑实现简单性不做过度设计 - 所有新增字段需要同时在数据库迁移文件和对应 TypeScript 类型中更新 - 所有外部 API 调用必须包含超时和错误日志 ## 数据模型 - 新表必须包含 id自增主键、created_at、updated_at 字段 - 不要轻易新增表优先在现有表上扩展字段 ## 接口实现 - 所有服务层函数必须包含输入校验 - 金额统一使用 decimal 类型禁止使用 float - 各类枚举值必须定义为常量禁止散落在代码里 ## 测试 - 每个需求功能必须附带对应测试文件 - 测试使用项目现有的测试框架不要引入新框架把这份规则文件丢给项目之后AI 生成的代码整体质量稳定了一大截。但请注意规则文件是全局兜底的需求约束具体每个功能的具体规则还是要靠你在每次提示词中写清楚。规则文件解决那些你不想每次重复说的常规约束功能提示词解决那些这个功能特有的行为规则两者缺一不可。7. 写在最后把我踩过的坑总结成几句不太中听的大实话回头看这半年我的最大收获不是学会了 Cursor 的某个快捷键也不是掌握了多复杂的提示词技巧而是老老实实把大学软件工程课里的需求分析重新捡了回来。这件事听起来一点都不酷但它真的解决了我 80% 的返工痛苦。如果你也在用 AI 编程我建议你别急着研究下一个新工具也别在哪个 AI 编程智能体工具更强这种问题上多花时间。先试着把你下一个需求写到能够回答下面五个问题这个功能给谁用解决他的什么问题业务背景操作流程的每一步是什么角色流程哪些事是这个功能绝对不做的功能边界数据的变换规则有哪些硬性条件业务规则我凭什么认为它做完了验收标准五个问题回答完你花十分钟写的文字比之前花一小时写的长篇提示词更值钱。我实测下来这类需求描述 AI 的一次生成通过率至少翻了一倍。另一个大的体会是逐步养成需求先于代码的肌肉记忆。这半年我最大的改变是打开 Cursor 的第一件事不再是在对话框里描述功能而是打开REQUIREMENTS.md把需求改清楚。代码只有在上面的需求理清楚之后才算开始。这个习惯刚开始会觉得很麻烦觉得多此一举但坚持一个月之后你会和我一样发现写需求的时间只是换一种方式花在了代码上。它不会增加你的总工作量它只是把隐性的返工成本显性化了变成了写文档的时间——而显性化的成本总是更容易被控制。最后分享一个我非常私人的判断标准如果你的需求描述写完之后你自己读一遍觉得这个活好像也不是很难嘛那大概率说明需求写得够好了。真正清晰的需求会让你觉得实现它很简单——因为复杂度已经被你消化在描述里了。这恰恰说明AI编程时代最先卡住你的永远不会是代码而是你把复杂世界翻译成精确规则的能力。