上一篇我写了一个结论：给 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 可能把无关逻辑一起复制。

我判断参考实现是否合格，会看四件事：

1. 它是否仍在当前项目中真实使用。

2. 它是否与当前任务处于同一技术和组件体系。

3. 它的这部分行为是否已经得到项目认可。

4. 它有哪些内容明确不适合当前任务。

如果没有可信参考，就直接说明“没有已确认的标准页面”，让 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 动手前，我只检查它能否回答：

1. 当前行为由哪些模块共同完成？

2. 哪个实现可以参考，参考到什么范围？

3. 哪些业务规则已经确认，哪些仍有歧义？

4. 修改会影响谁，最危险的副作用是什么？

5. 最后运行什么检查、走什么页面路径来验收？

如果这五个问题有答案，项目上下文通常已经能支撑第一步修改。

如果回答不了，继续粘贴更多无关代码没有意义。应该回到缺口本身：是入口不清、参考不可信、调用关系没查，还是业务规则尚未决定？

真正有效的上下文，会随着任务推进逐步变具体

上下文不是开工前一次性准备完的材料包。

第一次只需要帮助 Codex找到正确区域；读完入口后，再补调用方和状态流；发现公共组件后，再扩展影响范围；准备验收时，再确认实际命令和页面路径。

这个过程更像前端开发中的逐步定位：

给出入口 → 读取规则 → 建立调用与状态地图 → 暴露歧义 → 补充必要事实 → 再开始修改

它比“先把我知道的一切都告诉 AI”更稳，因为每一层新上下文都有代码或业务依据。

到这里，Day 3 的两篇文章形成了一个完整组合：上一篇解决提示词如何做减法，这一篇解决项目上下文如何按需补足。

下一篇进入 Day 4：为什么我让 Codex 改前端代码之前，总会先让它读代码。重点会放在“读什么、读到什么程度、怎样判断它是真的理解了”，而不是把“先分析一下”当作一句形式化口令。

本系列持续更新。后面会继续把这套方法放进 Vue3 列表、Element Plus 表单、调用链分析和页面验收中。

参考资料

• OpenAI Codex 用例：修改前理解代码库、请求流与风险位置

• OpenAI Codex 定制文档：AGENTS.md 与 Skills 的职责和按需加载