别把整个项目都塞给 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 的职责和按需加载
