需求明明写得很长，Codex 还是跑偏：问题往往不是信息不够，而是没分层

上一篇结尾我留了一个问题为什么有些需求已经写得很长Codex 还是会跑偏刚开始和 AI 搭档写代码时人很容易得出一个直觉——既然它理解得不够那我就再多解释一点。于是原本三行的需求被补成三十行前面讲业务背景中间贴旧代码后面加注意事项担心它漏掉又补几句“请仔细检查”“务必完整实现”。信息确实多了结果却不一定更稳定。后来我慢慢意识到问题经常不是“说得太少”而是不同性质的信息挤在了一起。目标、背景、约束、建议、实现步骤和验收标准全用同一种语气写在一大段里。人看完都要回头找重点更别说让 AI 在动代码时始终保持正确优先级。需求写得长和需求写得清楚是两回事。一个很长但不够清楚的前端需求先看一个常见的演示场景。它不是我的真实项目只是为了说明问题帮我完善订单列表页面。现在页面只有基础查询需要增加状态筛选、时间范围、重置和导出。 项目是 Vue3 和 Element Plus代码尽量写得优雅一点最好把旧代码也顺便优化一下。 查询时要有 Loading按钮不能重复点击接口错误要有提示导出可能比较慢。 另外移动端显示也要正常表格列太多时可以自己处理。不要影响原来的分页和权限。 如果发现公共请求封装不合理也可以一起改最后帮我检查代码有没有问题。这段话并不短甚至看起来考虑得挺全面。但真正准备修改时会发现里面至少混了五类任务新增筛选条件。调整查询和重置行为。增加导出流程。处理响应式布局。顺便重构旧代码和公共请求封装。它们的风险、影响范围和验收方法完全不同却被装在了同一个任务里。当最终结果不符合预期时我们甚至很难回答到底是 AI 漏掉了需求还是需求本身没有给出明确的先后顺序第一种混乱主目标和顺手优化混在一起上面那个需求的主目标是什么是让订单列表支持更多查询条件还是完成导出还是重构旧代码如果这些都算主目标实际上就等于没有主目标。我现在更愿意要求一个任务只有一个主要结果。例如本次只完善订单列表的筛选与重置行为确保查询条件和分页状态一致。至于导出、移动端适配和旧代码重构可以记录下来但不要让它们和本次交付争夺优先级。“顺便优化一下”是我现在很警惕的一句话。因为它没有范围也没有验收标准。AI 可能只改几个变量名也可能把半个页面重新组织一遍。两种做法都能被解释为“优化”但风险完全不是一回事。第二种混乱事实、要求和建议没有区分下面三句话看起来很像性质其实不同项目当前使用 Vue3 和 Element Plus。本次必须复用现有分页组件。如果结构合适可以考虑抽一个组合式函数。第一句是事实第二句是硬约束第三句只是建议。如果把它们连成一段AI 很可能无法稳定判断哪个不能违反、哪个可以放弃。特别是当“建议”与现有代码冲突时它可能为了完成建议反过来破坏更重要的项目一致性。所以我会直接给信息加标签【已知事实】项目使用 Vue3、TypeScript 和 Element Plus。 【必须遵守】复用现有分页组件不修改其公共 API。 【可选建议】只有在能减少当前页面重复逻辑时才考虑抽取组合式函数。这不是为了把提示词写得像合同而是让优先级一眼可见。第三种混乱长期规则和本次任务混在一起“项目统一使用哪种请求封装”“公共组件怎样命名”“修改后要运行哪些检查”这类规则通常会在很多任务中重复出现。而“这次新增两个筛选条件”“删除后保留当前页”只属于当前任务。如果每次都把两类信息全部粘进需求一方面会让任务越来越长另一方面也容易出现版本不一致今天复制的是旧规则明天又补了一条新规则最后连自己都不知道哪份算准。我的处理方式很简单长期稳定的项目规则放在项目级规则文件或可复用工作流中。当前任务的目标、范围和特殊边界只写在当前任务里。如果两者冲突先指出冲突不允许静默选择。这样做的重点不是少写几行字而是让每条信息有固定位置。第四种混乱实现要求和验收标准写成了一回事“增加 Loading”是实现要求“请求期间不能重复提交成功或失败后 Loading 都能恢复”才是验收标准。“支持移动端”是一个方向“在 375px 宽度下搜索区不遮挡按钮表格可以查看完整操作入口”才接近可检查的结果。很多长需求把前者写了一大堆后者却只剩一句“最后检查有没有问题”。这会带来一个很现实的麻烦AI 可以完成代码修改却不知道应该用什么证据证明完成了。最后的汇报往往变成“已实现筛选、导出和响应式适配”而不是哪些操作已经验证、哪些风险仍未验证。我现在会把验收单独放在最后并尽量写成动作1. 输入状态和时间范围后查询请求参数与页面条件一致。 2. 点击重置后清空筛选条件页码回到第一页并重新请求数据。 3. 查询失败后保留用户已填写的条件Loading 能正常结束。 4. 不改变现有权限判断和分页组件 API。能操作、能观察、能判断通过与否这才叫验收。第五种混乱同一段里藏着互相冲突的要求长需求最难发现的不是遗漏而是冲突。比如“尽量只做最小修改”后面又写“把旧代码顺便重构干净”。“完全复用现有写法”后面又要求“使用最新的组件组织方式”。“不要改公共组件”同时又希望“统一解决所有页面的同类问题”。这些要求单独看都合理放在一起却未必能同时满足。如果不提前解决冲突AI 只能选择一个方向。真正危险的不是它做了选择而是我们可能直到审查代码差异时才发现它选择的不是我们心里默认的那个。所以我会增加一句很朴素的规则如果要求之间存在冲突先列出冲突和可选处理方式暂时不要修改代码。这句话不能消除冲突但能阻止冲突直接变成代码。我现在如何给长需求分层当任务信息比较多时我会按下面六层整理1. 本次唯一主目标用一句话写出这次必须交付的结果。超过一个主要结果就考虑拆任务。2. 已知上下文只保留与当前任务直接相关的技术栈、文件、现有行为和参考实现。3. 硬约束写明不能改变的接口、公共组件、权限逻辑、依赖和业务行为。4. 功能与边界按用户操作顺序描述正常路径、异常路径和关键状态变化。5. 执行顺序先理解现状再列计划确认影响范围后做最小修改最后检查差异和运行结果。6. 验收标准把“完成”翻译成可以操作、观察和判断的检查项。最后再单独放一个“本次不做”列表把导出、重构、视觉优化之类暂缓事项写清楚。它们没有被遗忘只是没有混进当前交付。一个简单的自检删掉一半文字主任务还清楚吗我会用一个有点粗暴的方法检查需求先不看示例、背景和补充说明只看每个分层的第一句话。如果这样仍然能回答下面四个问题结构通常不会太差这次只解决什么问题哪些行为和文件不能改变应该按什么顺序推进用什么证据判断完成如果删掉背景之后连主任务都找不到那再补更多文字也没用。说到底我们不是要让 AI 记住一篇小作文而是要让它在每个执行节点都知道当前最重要的事情是什么。下一篇我会继续解决 Day 2 的第二个问题一个看起来完整的前端需求究竟应该怎样拆成几个可独立验收的小任务。重点不是按文件拆而是按“可观察的行为变化”来拆。本系列持续更新。后面所有方法都会逐步放进 Vue3、Element Plus 和真实页面验收场景中。参考资料Codex 官方用例先理解代码库和调用关系再开始修改Codex 官方用例用可评估结果迭代复杂任务