上一篇我解释了为什么让 Codex 改前端代码之前，我会先安排一个阅读阶段。

但“先读代码”也可能变成一句没有结果的口令。

如果任务只写：

请先熟悉一下项目，理解现有代码后再修改。

Codex 很可能会给出一段听起来正确的总结：项目使用 Vue3、TypeScript 和 Element Plus，目录分为 views、components、api、stores，页面采用 Composition API。

这些信息不能说错，却不足以支撑一次真实修改。

我真正想知道的不是它认不认识目录，而是：

• 当前功能从哪里进入。

• 用户操作经过哪些模块。

• 状态和业务规则分别由谁负责。

• 项目中哪个现有实现值得复用。

• 本次修改会影响哪些调用方。

• 改完以后去哪里验证。

所以我现在不会只要求“先读”，而会要求 Codex 先交一张与当前任务有关的“项目地图”。

这不是架构图，也不是仓库说明书。它是一份修改前的决策材料：让我能够检查 Codex 是否找对了入口、读清了关系、识别了风险。

项目地图不是目录树

目录树回答的是“文件放在哪里”，项目地图回答的是“一个行为怎样发生”。

例如下面这份输出，只能算目录介绍：

src/views：页面
src/components：公共组件
src/api：接口
src/stores：状态管理
src/utils：工具函数

它没有告诉我用户列表查询时，页面、分页组件、接口模块和全局状态之间到底怎样配合。

一张有用的地图应该更接近：

入口：
用户管理路由 → UserList 页面
​
查询流：
搜索表单 → handleQuery → 重置 pageNum → getList
→ getUserList → 响应转换 → tableData
​
分页流：
Pagination 组件 → current-change / size-change
→ 更新 queryParams → getList
​
公共依赖：
权限指令控制操作入口
统一请求层处理通用网络错误
页面负责保留筛选条件和结束 Loading
​
参考实现：
RoleList 的查询与重置流程可参考
其权限字段和表格列不可照搬

这份内容开始具备工程价值，因为它把文件、职责和行为连了起来。

OpenAI 当前的 Codex 代码库理解用例也明确指出：有效的理解结果应该形成一张具体地图，说明请求或行为流、模块职责、校验和状态变化，并指出风险位置和接下来应该阅读的文件，而不是只给一份文件名列表。

我要求项目地图至少包含六层

不同项目的结构差异很大，但面向前端修改时，我通常会固定检查下面六层。

第一层：规则地图

先回答“这个目录里的代码应该遵守什么”。

内容包括：

• 生效的 AGENTS.md 或目录规则。

• 当前任务触发的本地 Skill。

• 项目要求执行的检查。

• 明确禁止的修改。

• 遇到冲突时怎样暂停和报告。

示例：

项目	已确认内容	依据
项目规范	局部需求不得顺手修改公共请求封装	根目录 AGENTS.md
列表规范	查询、重置、分页需使用项目统一流程	当前适用 Skill
验证要求	修改后运行类型检查，并做页面路径验证	项目规则
暂停条件	必须改变公共组件 API 时先报告	项目规则

规则地图不应该复制整份规则文件。它只提取与当前任务直接相关的部分，并保留来源。

没有来源的“项目通常这样写”，不能自动算规则。

第二层：入口地图

回答“当前功能究竟从哪里开始”。

前端项目可能同时存在：

• 多个应用。

• 多套路由。

• PC 和移动端页面。

• 新旧版本目录。

• 同名但用途不同的组件。

• 演示页、测试页和真实业务页。

所以入口地图至少要说明：

• 应用入口。

• 路由或菜单入口。

• 页面入口组件。

• 主要子组件。

• 首次加载时执行的初始化行为。

例如：

应用入口：管理后台
路由入口：/system/user
页面入口：src/views/system/user/index.vue
主要子组件：SearchForm、UserTable、Pagination、UserDialog
初始化：页面挂载后调用 getList

这一步的验收重点不是路径写得多，而是能否证明这是当前真实使用的入口。

如果只根据文件名猜测，就应该标记为待确认；如果通过路由注册、菜单配置或父组件引用确认，才进入“已确认”。

第三层：职责地图

回答“每一层负责什么，以及不负责什么”。

以一个列表页为例：

模块	主要职责	不应承担
页面	组织查询条件、列表状态和用户操作	重写通用请求机制
搜索组件	收集筛选条件并触发查询或重置	私自请求列表数据
分页组件	提供页码和每页数量变化	决定业务筛选规则
接口模块	定义请求入口和参数类型	管理页面 Loading
请求层	处理通用网络行为	猜测页面失败后的业务状态

职责地图的价值，是防止 AI 把一个功能放到“能写的位置”，而不是“应该负责的位置”。

例如，搜索组件内部直接发请求也许能跑，但会让分页、导出和缓存很难共享同一份条件。页面里直接处理所有网络错误也许更直观，却可能重复请求层已经完成的逻辑。

当职责没有读清，AI 很容易通过增加代码解决局部问题，同时扩大模块耦合。

第四层：行为与状态地图

这一层是整张地图的核心。

我会要求 Codex 按用户操作追踪，而不是按文件顺序总结。

后台列表常见的行为至少包括：

• 首次进入。

• 点击查询。

• 点击重置。

• 切换页码。

• 修改每页数量。

• 打开新增或编辑弹窗。

• 提交成功和失败。

• 删除后重新查询。

每条行为都可以用同一种格式记录：

触发动作
→ 事件处理方法
→ 状态变化
→ 参数转换
→ 接口调用
→ 响应处理
→ 页面结果

例如：

点击查询
→ handleQuery
→ queryParams.pageNum = 1
→ getList
→ getUserList(queryParams)
→ 更新 tableData 和 total
→ finally 结束 loading

还要补异常路径：

请求失败
→ 通用请求层提示网络或权限错误
→ 页面结束 loading
→ 当前筛选条件保留
→ 表格旧数据是否保留：尚未确认

这里最后一行比强行补一个答案更有价值。它暴露了当前需要确认的业务问题。

状态地图必须回答三个问题：

1. 状态的唯一来源在哪里？

2. 哪些操作会改变它？

3. 哪些后续行为会读取它？

只看状态在哪里定义，不看谁读写，仍然不算理解状态流。

第五层：复用与差异地图

成熟项目里经常有相近页面，但不能把“相似”直接理解为“可以复制”。

我会要求 Codex 把参考实现拆成两栏：

可以复用的模式	当前任务的差异
查询前页码回到第一页	当前页面多一个时间范围转换
重置使用统一方法恢复默认值	当前页面有一个固定不可清空的组织条件
请求期间使用页面 Loading	当前页面还存在独立导出 Loading
分页组件事件统一接入查询	当前页面删除后可能需要处理空页

这张表迫使它回答：

• 为什么这个页面值得参考。

• 具体参考哪种行为。

• 哪些业务差异不能照搬。

• 是否存在更接近的第二个参考。

我不接受“项目中其他页面都是这样写的”这种结论，除非它列出检索范围和代表文件。

多个页面采用相同模式，才可能说明这是项目惯例；一个页面这样写，只能说明它是一个实例。

第六层：影响与验证地图

最后回答“改动会传播到哪里，以及怎样验收”。

影响地图包括：

• 目标组件的调用方。

• 目标方法的引用位置。

• 共享类型和接口。

• 可能被改变的默认行为。

• 相关测试或页面。

验证地图包括：

• 类型检查。

• Lint、单测或构建。

• 当前功能的页面路径。

• 正常、异常和连续操作。

• 未能验证的内容。

例如：

风险	需要检查
查询条件与分页不同步	查询后翻页，再重置并重新查询
公共组件默认值变化	检查主要调用页面和插槽覆盖
参数转换错误	对比页面状态、请求参数和接口类型
异常后 Loading 不恢复	验证失败和取消路径
无关文件被修改	审查完整代码差异

一张项目地图如果没有验证入口，只完成了一半。

它说明了代码怎样工作，却没有说明修改后怎样证明仍然工作。

建图过程应该逐层收敛，而不是一次扫完整个仓库

我会让 Codex 按下面的顺序建立地图。

第一步：先圈定功能区域

给出路由、菜单、页面名或目录线索，要求它确认真实入口。

不要从“解释整个仓库”开始。任务范围越具体，得到的关系越具体。

第二步：读取规则和运行配置

确认当前目录生效的项目规则、关键依赖和项目脚本。

这一步解决“怎样工作”和“怎样验证”，不需要展开所有工具配置。

第三步：沿一个真实行为追踪

选择最核心的一条用户路径，例如列表查询或表单提交，从入口追到结果。

当这条主链建立后，再补重置、翻页、失败等分支。

如果一开始同时追十条行为，地图很容易再次退化成文件摘要。

第四步：查相近实现和公共依赖

用项目内检索找到：

• 相近页面。

• 公共组件。

• 工具方法。

• 类型。

• 状态管理。

• 调用方。

每找到一个依赖，都要说明它为什么与当前任务有关。

第五步：列出冲突、假设和未知

把阅读中发现的问题集中记录：

• 两个页面行为不一致。

• 规则与现有代码冲突。

• 找不到可信参考。

• 业务状态没有唯一答案。

• 关键检查无法运行。

这一步不是给地图挑毛病，而是避免下一步在未知上继续堆代码。

第六步：形成最小修改建议

项目地图完成后，才允许提出：

• 建议修改哪些文件。

• 每个文件为什么要改。

• 哪些文件只需读取、不应修改。

• 修改顺序。

• 每一步的验证证据。

注意，这仍然只是建议。只要影响范围发生变化，就应该先更新地图和计划，而不是偷偷扩大修改。

我怎样检查这张地图是不是 AI “猜”出来的

项目地图最怕看起来很完整，却没有代码依据。

我会做下面几项检查。

关键结论是否有来源

“查询由页面维护”后面应该能指出页面和方法；“错误统一处理”应该能指出请求层或项目规则；“这个组件有多个调用方”应该列出主要引用。

没有来源的结论，最多算推断。

是否区分现状与规范

代码现在这样写，不等于项目要求一直这样写。

一个旧页面的实现是现状；AGENTS.md 或稳定重复模式更接近规范；本次需求则可能要求改变现状。

地图里必须分别标出：

• 当前代码事实。

• 项目明确规则。

• 从多个实例归纳出的模式。

• 本次任务要求。

四者发生冲突时，不能悄悄选择。

是否覆盖异常和连续操作

只画“点击查询 → 请求成功 → 渲染列表”的地图太乐观。

至少还要问：

• 请求失败时状态如何恢复。

• 快速连续操作会不会重复请求。

• 重置、翻页、返回页面时状态是否一致。

• 组件关闭或卸载后是否还有异步结果返回。

前端问题常常出现在操作顺序中，而不是单个按钮上。

是否说明不知道什么

一张全是确定结论的项目地图，反而值得警惕。

历史项目里常有命名不一致、旧代码残留、业务规则缺失和验证环境不完整。合理的阅读结果应该包含未知和待确认项。

“不知道”不是失败。没有证据却给出确定答案，才是风险。

是否能直接生成验收路径

如果地图真的解释清楚了状态流和影响范围，应该能够自然推导出验收步骤。

例如：

查询会重置页码，翻页会复用当前筛选条件，重置会恢复默认条件。

对应的验收就应该包含：

设置筛选并查询 → 翻到第二页 → 点击重置 → 检查条件、页码和请求参数。

如果地图和验收之间没有关系，说明阅读结果仍然停留在目录层。

一份可以直接交给 Codex 的“项目地图”模板

下面这份模板针对已有前端项目中的局部修改。内容不要求一次填满，但每个“已确认”结论都要有依据。

# 当前任务项目地图
​
## 1. 任务边界
​
- 本次要改变的用户行为：
- 本次不改变的行为：
- 允许修改：
- 禁止修改：
​
## 2. 规则地图
​
- 生效的 AGENTS.md：
- 适用的 Skill：
- 与当前任务直接相关的规则：
- 必须执行的检查：
- 必须暂停的冲突：
​
## 3. 入口地图
​
- 应用与路由入口：
- 页面入口：
- 主要子组件：
- 初始化行为：
- 入口确认依据：
​
## 4. 职责地图
​
| 模块或文件 | 负责什么 | 与本任务的关系 | 依据 |
| --- | --- | --- | --- |
|  |  |  |  |
​
## 5. 行为与状态地图
​
### 主路径
​
用户操作 → 事件 → 状态 → 参数 → 请求 → 响应 → 页面结果
​
### 异常路径
​
失败或取消 → 提示 → 状态恢复 → 页面保留内容
​
### 状态清单
​
| 状态 | 唯一来源 | 写入位置 | 读取位置 |
| --- | --- | --- | --- |
|  |  |  |  |
​
## 6. 复用与差异
​
- 可信参考：
- 可以复用的模式：
- 不能照搬的业务差异：
- 找不到参考的部分：
​
## 7. 影响范围
​
- 直接修改文件：
- 只需读取文件：
- 主要调用方：
- 公共类型或接口：
- 潜在副作用：
​
## 8. 验证入口
​
- 项目实际检查命令：
- 相关测试：
- 页面访问路径：
- 手动验证步骤：
- 当前无法验证：
​
## 9. 结论分级
​
### 已确认
​
- 结论 + 文件或代码依据
​
### 推断
​
- 推断 + 推断依据 + 验证方式
​
### 未知
​
- 待确认问题 + 不确认会产生的风险
​
## 10. 最小修改建议
​
- 建议修改文件及原因：
- 建议顺序：
- 每步完成证据：
- 需要人确认后才能继续的事项：

项目地图什么时候算完成

它不需要覆盖整个仓库，也不追求每个文件都解释。

只要能够支撑当前任务的关键决策，就可以进入修改阶段。

我会用下面七个问题收尾：

1. 入口是否经过引用或路由关系确认？

2. 主行为是否从用户操作追到了页面结果？

3. 核心状态是否找到了唯一来源和所有关键读写点？

4. 复用对象是否有证据，而不是只凭文件名相似？

5. 公共组件或方法是否检查了主要调用方？

6. 未知和冲突是否已经单独列出？

7. 是否能据此写出最小修改范围和验收路径？

七个问题不一定全部有完美答案，但没有答案的部分必须明确标成风险。

项目地图的完成标准不是“没有未知”，而是“未知没有被伪装成事实”。

地图也可能过度：不要把阅读变成无限分析

读代码不是目的，安全完成任务才是目的。

如果任务只是修改一个已经定位明确的局部文案，就没必要建立十层调用关系；如果目标是调整公共组件 API，就不能只画当前页面。

我会根据风险控制地图深度：

任务类型	地图重点
局部样式或文案	入口、作用范围、页面验证
页面功能	状态流、接口、异常、相近实现
表单和弹窗	初始化、回填、校验、提交、清理
公共组件	契约、调用方、默认行为、回归范围
多文件重构	模块职责、依赖方向、行为基线、分步验证

一旦地图已经足够回答当前修改的决策问题，就应该停止扩展，进入小步实现和验证。

否则，“先读代码”也可能变成没有终点的准备工作。

真正有价值的项目地图，是后续修改和验收共用的依据

我要求 Codex 先交地图，不是为了多一份文档。

这张地图会直接进入后续流程：

• 用职责地图决定代码放在哪里。

• 用状态地图决定修改顺序。

• 用复用地图避免新增重复实现。

• 用影响地图控制改动范围。

• 用验证地图生成验收步骤。

• 用未知清单决定哪些地方必须由人判断。

如果修改过程中发现新调用方、新规则或新冲突，地图也应该同步更新。

这样，AI 的理解不是一句“我已经熟悉项目”，而是一份可以被检查、纠正和继续使用的工程产物。

Day 4 的两篇到这里形成闭环：第一篇解释为什么必须先读相关代码，这一篇定义读完以后应该交付什么。

下一篇进入 Day 5：AI 最容易忽略的需求边界。我会继续讨论那些不会主动报错、却最容易在交付后返工的前端边界，并说明哪些必须由人提前决定。

本系列持续更新。后面会把任务边界继续落成可执行的验收标准和检查清单。

参考资料

• OpenAI Codex 用例：用请求流、模块职责和风险位置理解代码库

• OpenAI Codex 定制文档：项目指引、Skills 与工作规则