别把整个项目都塞给 Codex：开发任务真正需要的是这份上下文清单

上一篇我写了一个结论给 Codex 的任务提示不是越复杂越好。我现在只在当前任务里保留唯一目标、必要事实、硬边界和验收证据。但把提示词缩短以后很多人马上会遇到另一个问题不把所有信息都写进去Codex 怎么理解我的项目这个担心是合理的。前端代码很依赖上下文。同样是一个搜索列表有的项目把分页放在查询对象里有的单独维护有的直接调用接口有的必须经过模块服务层有的使用 Element Plus 原生弹窗有的已经封装了统一弹窗组件。如果这些差异没有被识别Codex 很容易写出一套“技术上没错放进项目却不合适”的代码。可解决办法也不是把整个仓库介绍一遍更不是把所有规范、所有依赖和几千行代码复制进提示词。我现在对“项目上下文”的理解是上下文不是项目资料的总和而是完成当前任务所需要的决策依据。它的作用是帮助 Codex 判断该看哪里、相信什么、不能改变什么以及最后怎样证明结果正确。先区分两件事给入口和替 Codex 读项目很多过度上下文都来自一个误区担心 Codex 看不懂项目于是我们先替它做一遍代码阅读再把自己的结论全部写进任务。例如这个页面使用 Vue3 和 Element Plus查询条件放在 queryParams getList 负责请求数据handleSearch 负责查询handleReset 负责重置 分页组件通过 page-change 事件更新页码……如果这些信息已经核对过而且正是本次任务的关键事实可以提供。但如果只是根据文件名或局部代码猜出来的就可能把错误理解直接交给 Codex。更麻烦的是它可能不再重新检查而是沿着我们给出的结论继续实现。我更愿意给它“阅读入口”和“需要回答的问题”先阅读用户列表页面、用户接口模块、公共分页组件以及角色列表的相近实现。 暂时不要修改代码。 ​ 请确认 1. 查询条件和分页状态分别由哪里维护。 2. 点击查询、重置和翻页时分别调用什么方法。 3. 请求参数在哪里转换。 4. Loading、异常提示和权限由哪一层处理。 5. 本次修改最容易影响哪些既有行为。前一种写法把我的理解当成事实后一种写法要求 Codex 从代码中建立证据。这两者的区别很重要项目上下文应该帮助它读对代码而不是替它跳过读代码。OpenAI 当前的 Codex 代码库理解用例也强调开始修改前应先圈定相关目录或功能区域再梳理请求流、模块职责、校验、副作用、状态变化、风险位置和需要执行的检查。最终得到的应该是一张具体的项目地图而不只是文件名清单。第一层每个前端任务都应该有的最小上下文无论是改一张列表、一个弹窗还是一个公共组件我至少会提供下面五类信息。1. 任务所在的功能区域不要只说“改一下列表页”要给出足够准确的入口功能区域系统管理 / 用户管理 主要入口src/views/system/user/index.vue 相关接口src/api/system/user.ts如果还不知道具体文件也可以给目录或路由名称让 Codex 先查找。入口的作用不是限制它只能读这两个文件而是避免它从仓库根目录开始漫无目的地搜索。一个大型前端项目可能同时存在旧版页面、新版页面、移动端页面和演示代码。没有功能边界读到“看起来相似”的代码不代表读到了正确实现。我还会明确入口的可信程度已确认这是线上功能当前使用的入口。待确认根据路由名称推测需要继续查调用关系。仅供线索可能是旧实现不能直接照搬。“我知道什么”和“我猜什么”应该分开。2. 与当前任务直接相关的项目规则项目规则通常已经写在AGENTS.md或本地 Skill 中。当前任务不需要把它们全文复制一遍但要告诉 Codex 先读取哪些规则。例如开始前读取 - 仓库根目录的 AGENTS.md - 当前后台列表任务适用的 web-skills ​ 只提取与本任务相关的规则 - 列表查询与分页 - Loading 和按钮状态 - 消息提示 - 弹窗调用方式这一步要控制范围。一个 Skill 里可能同时包含列表、表单、弹窗、状态管理和接口封装规范。当前任务只是调整表格空值展示就没有必要把所有表单提交规则都带进工作上下文。OpenAI 的 Codex 定制文档把AGENTS.md定位为持续生效的项目指引把 Skills 定位为可复用流程和领域能力。Skills 采用按需加载的方式本意之一就是让丰富工作流可被发现又不必在任务开始时把所有细节塞满上下文。所以我的原则是先声明规则来源再按任务需要读取而不是复制整套规范。3. 一个经过确认的参考实现“请按照项目现有风格实现”几乎没有可操作性因为一个项目里可能同时存在三四种风格。我会给出一个明确参考参考页面src/views/system/role/index.vue 参考范围搜索、重置和分页状态流 不要照搬角色权限判断和表格列配置这里最重要的不只是“参考哪个文件”还有“参考它的哪一部分”。同一个页面里可能既有值得复用的查询流程也有历史遗留的表单写法。把整个文件标记为模板Codex 可能把无关逻辑一起复制。我判断参考实现是否合格会看四件事它是否仍在当前项目中真实使用。它是否与当前任务处于同一技术和组件体系。它的这部分行为是否已经得到项目认可。它有哪些内容明确不适合当前任务。如果没有可信参考就直接说明“没有已确认的标准页面”让 Codex 先总结当前模块的既有模式不要假装项目里已经有答案。4. 不能从代码中单独推断的业务规则有些上下文代码里找不到唯一答案必须由人提供。例如点击查询后是否回到第一页。重置后是立即请求还是等待用户再次点击查询。保存成功后保留当前页还是回到第一页。请求失败时表格保留旧数据还是显示空状态。没有权限时隐藏按钮还是显示但禁用。接口返回null时显示--、空白还是业务文案。这些不是 Vue3 或 Element Plus 的技术问题也不是 Codex 多读几个文件就一定能确定的问题。代码只能告诉它“现在怎样做”不一定能告诉它“需求希望怎样做”。如果现有行为本身就是要修复的对象继续照着现状推断只会把问题保留下来。所以我会给业务规则标注来源已确认需求 - 点击查询回到第一页。 - 重置后立即使用默认条件请求。 - 请求失败时保留用户已填写的筛选条件。 ​ 需要从现有代码确认 - 表格旧数据在失败时是否保留。 ​ 尚未确定 - 状态无权限时隐藏还是禁用发现现有行为不一致时先报告。确定、待查和待决策不能混成一段。5. 项目真实可用的验证方式上下文不只有“怎样写”还包括“这个项目怎样证明写对了”。我会提供或要求 Codex确认类型检查命令。Lint、单元测试或构建命令。当前模块已有的测试位置。页面启动和访问方式。本次任务需要走的交互路径。哪些检查当前环境无法运行。例如验证要求 - 先从 package.json 确认项目实际提供的检查命令不要猜命令。 - 运行与本次修改相关的类型检查和现有测试。 - 页面验证路径查询 → 翻页 → 重置 → 再次查询。 - 无法启动页面时明确列为未验证不得用代码审查代替页面验证。命令也属于项目上下文。不同项目使用的包管理器、脚本名称和检查范围都可能不同。直接写一个习惯中的npm run lint并不能保证仓库真的提供了它。第二层根据任务风险按需补充的上下文前面五类是最小集合。任务类型不同还要补充不同信息。如果改的是 UI 和样式需要关注设计稿、截图或明确的视觉参考。项目现有的颜色、间距、字号和断点来源。公共组件允许覆盖到什么程度。必须检查的屏幕宽度。长文本、空数据和权限按钮等内容边界。只说“做得好看一点”不是有效上下文。如果没有设计稿可以把要求收缩成可验证的实现约束例如- 保持当前页面的视觉体系不新增颜色令牌。 - 重点解决 375px 宽度下操作按钮被遮挡的问题。 - 桌面端现有布局和交互不变。这样写没有假装存在一套完整设计方案但任务仍然可判断。如果改的是表单和状态需要关注状态的唯一来源。新增、编辑和查看是否共用同一组件。数据何时初始化、回填、重置和销毁。校验规则来自前端、接口还是业务约定。提交中、成功、失败和关闭后的状态变化。异步请求返回顺序是否可能覆盖新状态。AI 生成表单最容易的问题不是少写一个输入框而是生命周期中的状态残留。所以表单上下文不能只给字段表还要给状态流。如果改的是接口联调需要关注真实接口定义或当前项目的类型声明。页面模型与接口模型是否需要转换。空值、枚举、时间和数字的约定。错误在哪一层处理。取消请求、重复请求和并发返回如何处理。是否有模拟数据以及模拟数据与真实接口的差异。不能提供真实响应时就明确把文章或任务限制在静态结构和方法层面不能让 Codex 根据字段名自行补全接口事实。尤其不要把生产环境的密钥、令牌、用户隐私数据当作“上下文”粘进去。完成前端任务需要的是数据结构和行为约定不是敏感数据本身。如果改的是公共组件需要关注所有主要调用方而不只是当前页面。Props、Emits、Slots 和暴露方法的契约。默认值与兼容行为。哪些调用方依赖当前副作用。修改后要回归哪些代表场景。局部页面可以强调最小行为公共组件必须补影响范围。只给一个调用示例很容易让 Codex 为当前页面优化却破坏其他使用方式。此时最重要的上下文不是更多组件代码而是调用方地图和兼容边界。第三层最好不要直接塞进任务的上下文不是所有相关资料都应该进入当前任务。下面几类内容我会特别谨慎。1. 没有确认是否还在使用的旧页面旧页面可以作为线索不能自动成为规范。如果必须参考要明确标注这个页面可能是旧实现只用于查接口字段不参考它的组件结构和状态管理。否则 Codex 很可能把技术债复制得很完整。2. 与任务无关的整份技术文档一份几十页的项目说明可能很重要但当前只改一个列表空值展示时真正相关的也许只有“统一占位符”和“表格列格式化”两条。把整份文档塞进去增加的主要是检索成本不是决策质量。正确做法是给文档位置和需要读取的章节让 Codex按需取用。3. 从别的项目复制来的万能模板Vue3、Element Plus、Pinia 都一样不代表项目结构一样。另一个项目里成功的列表模板可能使用不同请求封装、权限体系和状态约定。它可以帮助讨论方案却不能伪装成当前仓库事实。如果引用外部示例应明确它只用于说明某个技术点项目内实现仍以当前代码和规则为准。4. 没有证据的个人推测例如“这个组件应该没有其他地方使用。”“这个接口应该不会返回空值。”“项目应该都使用同一种弹窗。”“这里大概不需要权限。”这些话最危险的地方是语气听起来像上下文实际上只是尚未验证的假设。我会把“应该”“大概”“可能”全部转成待确认问题请查找该组件的全部调用方确认是否仅用于当前页面。上下文不怕不完整怕的是把不确定写成确定。5. 任何不必要的敏感信息前端联调经常接触接口地址、账号、令牌、日志和真实业务数据。提供上下文时要做最小化用字段结构代替真实用户数据。用错误类型和必要日志片段代替整份生产日志。隐去令牌、Cookie、密钥和个人信息。只提供定位问题所需的请求与响应片段。“让 AI 看得更多”从来不是泄露敏感信息的理由。我会使用的一份前端上下文清单下面这份模板可以直接复用。它不是要求每次全部填满而是帮助我识别哪些已经确认哪些还要从项目中查。## 功能区域 ​ - 业务模块 - 页面或路由入口 - 已确认的相关文件 - 仅供查找的线索 ​ ## 规则来源 ​ - 需要读取的 AGENTS.md - 本任务适用的 Skill - 只需提取的规则范围 ​ ## 可信参考 ​ - 参考文件或页面 - 只参考哪些行为 - 明确不要照搬什么 - 参考是否仍在使用 ​ ## 已确认的业务规则 ​ - 正常路径 - 异常路径 - 状态保留或清理规则 - 权限与空值规则 ​ ## 需要从代码中确认 ​ - 状态由谁维护 - 请求和数据转换在哪里 - 校验、副作用和权限在哪里 - 主要调用方 - 容易遗漏的依赖 ​ ## 尚未确定 ​ - 发现后必须暂停的问题 - 允许 Codex自行选择的实现细节 ​ ## 修改边界 ​ - 允许修改 - 禁止修改 - 公共能力需要调整时的处理方式 ​ ## 验证上下文 ​ - package.json 中的实际检查命令 - 相关测试位置 - 页面启动和访问方式 - 手动验证路径 - 当前环境无法验证的部分这份清单里我最看重的是三个标签已确认、需要查、尚未决定。很多上下文问题不是信息太少而是这三种状态没有分开。Codex 不知道哪条是事实、哪条是调查任务、哪条必须等人决策就只能把它们都当作普通说明继续往下做。上下文够不够不看字数看能否支持五个判断我不会用文件数量或文字长度判断上下文是否完整。在 Codex 动手前我只检查它能否回答当前行为由哪些模块共同完成哪个实现可以参考参考到什么范围哪些业务规则已经确认哪些仍有歧义修改会影响谁最危险的副作用是什么最后运行什么检查、走什么页面路径来验收如果这五个问题有答案项目上下文通常已经能支撑第一步修改。如果回答不了继续粘贴更多无关代码没有意义。应该回到缺口本身是入口不清、参考不可信、调用关系没查还是业务规则尚未决定真正有效的上下文会随着任务推进逐步变具体上下文不是开工前一次性准备完的材料包。第一次只需要帮助 Codex找到正确区域读完入口后再补调用方和状态流发现公共组件后再扩展影响范围准备验收时再确认实际命令和页面路径。这个过程更像前端开发中的逐步定位给出入口 → 读取规则 → 建立调用与状态地图 → 暴露歧义 → 补充必要事实 → 再开始修改它比“先把我知道的一切都告诉 AI”更稳因为每一层新上下文都有代码或业务依据。到这里Day 3 的两篇文章形成了一个完整组合上一篇解决提示词如何做减法这一篇解决项目上下文如何按需补足。下一篇进入 Day 4为什么我让 Codex 改前端代码之前总会先让它读代码。重点会放在“读什么、读到什么程度、怎样判断它是真的理解了”而不是把“先分析一下”当作一句形式化口令。本系列持续更新。后面会继续把这套方法放进 Vue3 列表、Element Plus 表单、调用链分析和页面验收中。参考资料OpenAI Codex 用例修改前理解代码库、请求流与风险位置OpenAI Codex 定制文档AGENTS.md 与 Skills 的职责和按需加载