企业官网建设流程全解析

在真实项目中使用 Codex，最常见的问题不是模型不会写代码，而是它不了解项目约束、修改范围和验收标准。本文通过 AGENTS.md、任务拆分、上下文控制、测试验证和差异审查，介绍一套更稳定的 AI 编程工作流。

很多人第一次使用 Codex，会直接输入类似的需求：

帮我优化这个项目，并修复现有问题。

这种提示看起来很直接，但对真实项目来说，信息远远不够。

Codex 不知道：

• 哪些目录允许修改；
• 项目使用什么技术栈；
• 代码应该遵循什么规范；
• 哪些功能不能改变；
• 修改完成后应该运行什么测试；
• 什么结果才算任务完成。

因此，提升 Codex 成功率的关键，不是把需求写得特别长，而是给它明确的边界、步骤和验证方式。

一、先用 AGENTS.md 描述项目规则

在项目根目录创建一个AGENTS.md文件，用来告诉 Codex 当前项目的基本情况。

例如：

# 项目说明 这是一个基于 Vue 3、TypeScript 和 Vite 的后台管理系统。 ## 目录结构 - src/api：接口请求 - src/components：公共组件 - src/views：页面模块 - src/router：路由配置 - src/stores：Pinia 状态管理 - tests：自动化测试 ## 开发规范 - 使用 TypeScript - 使用 Composition API - 不使用 Options API - 公共类型放在 src/types - 接口请求统一放在 src/api - 不在组件中直接拼接请求地址 ## 修改限制 - 不修改后端接口字段 - 不删除现有路由 - 不升级项目依赖 - 不修改无关模块 ## 验证命令 安装依赖： npm install 类型检查： npm run type-check 单元测试： npm run test 生产构建： npm run build

这个文件相当于项目的 AI 开发说明书。

它不能替代完整文档，但可以帮助 Codex快速了解项目边界，减少风格不一致和无关修改。

二、不要一次要求修改整个项目

一个常见错误是把多个目标放进同一个任务。

例如：

重构用户模块，修复登录问题，优化页面性能，补充测试并更新文档。

这个任务同时包含：

• Bug 修复；
• 代码重构；
• 性能优化；
• 测试开发；
• 文档更新。

一旦其中某一步理解错误，后面的修改也可能全部受到影响。

更稳定的方法是拆成多个阶段。

第一阶段：只分析，不修改

请先分析用户登录模块，不要修改代码。 需要输出： 1. 登录流程涉及的文件； 2. Token 的保存和读取位置； 3. 登录失败可能出现的原因； 4. 建议修改的文件； 5. 可能影响的其他模块。

第二阶段：输出修改计划

根据刚才的分析，制定修改计划。 要求： 1. 不改变后端接口； 2. 不修改无关页面； 3. 每一步写明修改文件； 4. 说明可能存在的风险； 5. 暂时不要执行修改。

第三阶段：执行最小修改

按照确认后的计划修改代码。 本次只处理登录失败问题，不进行代码格式化，不重构其他模块。

第四阶段：运行验证

修改完成后依次运行： npm run type-check npm run test npm run build 如果出现错误，先分析原因，再进行最小范围修复。

这种方式虽然多了几个步骤，但更容易定位错误，也方便在中间阶段调整方向。

三、给任务设置明确的修改范围

Codex 在读取整个项目后，可能顺手修改它认为不合理的代码。

但这些“顺手优化”往往会增加审查成本。

因此，任务中最好明确写出允许修改和禁止修改的范围。

例如：

任务：修复用户退出后页面仍显示旧数据的问题。 允许修改： - src/stores/user.ts - src/api/user.ts - src/views/profile/index.vue 禁止修改： - 路由配置 - 登录页面 - 后端接口类型 - package.json - 其他业务模块 验收标准： 1. 退出后清除用户信息； 2. 退出后清除本地 Token； 3. 页面跳转到登录页； 4. 重新登录后可以正常获取用户信息； 5. 项目构建通过。

这里最重要的是“验收标准”。

“修复退出问题”是一个模糊目标，而“清除 Token、清除用户信息、跳转登录页、重新登录正常”才是可以验证的结果。

四、使用最小修改原则

让 Codex 修改项目时，可以明确要求采用最小修改原则：

请使用最小修改原则完成任务： - 不重构无关代码； - 不修改公共接口； - 不改变现有页面结构； - 不新增不必要的依赖； - 不进行全局格式化； - 优先复用现有工具函数。

最小修改有三个好处：

1. 更容易检查代码差异；
2. 更容易发现问题来源；
3. 出现异常时更容易回滚。

在真实业务项目中，“修改得少但正确”通常比“顺便重构得很漂亮”更重要。

五、不要只让 Codex 写代码，还要让它验证代码

AI 生成代码不等于任务完成。

一个完整的 Codex 任务至少应该包含：

分析 → 修改 → 测试 → 检查差异 → 总结

可以在提示中加入：

完成修改后，请执行以下操作： 1. 查看 git diff； 2. 检查是否修改了无关文件； 3. 运行类型检查； 4. 运行自动化测试； 5. 运行生产构建； 6. 总结修改内容和验证结果。

最终输出可以要求使用固定格式：

## 修改文件 - src/stores/user.ts - src/views/profile/index.vue ## 修改内容 - 退出时清除用户状态 - 删除本地 Token - 增加退出后的页面跳转 ## 验证结果 - 类型检查：通过 - 单元测试：通过 - 生产构建：通过 ## 未处理问题 - 当前项目缺少退出流程的自动化测试

这样可以快速判断 Codex 到底做了什么，而不是重新逐个文件查找。

六、让 Codex 先读测试，再修改业务代码

如果项目已经有测试，可以让 Codex 先分析测试用例。

例如：

请先阅读用户模块现有测试，不要修改业务代码。 分析： 1. 当前测试覆盖了哪些场景； 2. 哪些边界情况没有覆盖； 3. 本次问题应该补充哪些测试； 4. 测试失败时可能对应哪些业务问题。

之后再让它补充测试：

先增加一个可以复现问题的失败测试。 确认测试能够稳定失败后，再修改业务代码，直到测试通过。

这是一种接近测试驱动开发的工作方式。

相比先修改代码再补测试，它更容易证明当前修改确实解决了目标问题。

七、控制上下文，避免重复读取整个仓库

项目越大，越不应该每次都让 Codex重新分析所有文件。

可以按照任务范围指定目录：

本次任务只分析以下目录： - src/modules/order - src/api/order.ts - tests/order 其他目录仅在发现明确依赖时读取。

也可以提供阶段性总结：

# 当前任务状态 ## 已完成 - 已定位订单金额计算问题 - 已确认问题位于 calculateTotal 函数 - 已补充失败测试 ## 下一步 - 修复优惠券与运费的计算顺序 - 运行订单模块测试 - 检查是否影响退款金额计算 ## 禁止修改 - 支付接口 - 数据库字段 - 订单状态枚举

后续任务直接读取这份总结，不需要重新解释完整背景。

八、审查 Codex 修改时重点看什么？

不要只看代码能不能运行，还要重点检查以下内容。

是否修改了无关文件

有时只是修复一个函数，却出现大量格式化差异。

可以使用：

gitstatusgitdiff--statgitdiff

先查看修改文件数量，再检查具体内容。

是否新增了不必要的依赖

检查：

gitdiffpackage.jsongitdiffpackage-lock.json

一个简单功能通常不应该随意引入新的第三方库。

是否改变了公开接口

重点检查：

• 函数参数；
• 返回值；
• 接口字段；
• 类型定义；
• 组件属性；
• 路由地址。

内部实现可以调整，但公开接口变化可能影响整个项目。

是否只处理了正常场景

还应检查：

• 空数据；
• 接口超时；
• 权限不足；
• 重复提交；
• 网络异常；
• 参数缺失；
• 用户取消操作。

九、一个可直接使用的 Codex 任务模板

任务目标： 修复订单页面重复提交的问题。 项目规则： 请先阅读项目根目录中的 AGENTS.md。 允许修改： - src/views/order - src/api/order.ts - tests/order 禁止修改： - 后端接口字段 - 路由配置 - package.json - 其他业务模块 执行步骤： 1. 分析重复提交产生的原因； 2. 输出涉及的文件和调用流程； 3. 制定最小修改方案； 4. 增加能够复现问题的测试； 5. 修改代码； 6. 运行相关测试； 7. 运行类型检查和生产构建； 8. 查看 git diff，确认没有无关修改。 验收标准： 1. 请求发送期间按钮不可重复点击； 2. 请求成功后恢复按钮状态； 3. 请求失败后也能恢复按钮状态； 4. 不改变现有接口参数； 5. 测试、类型检查和构建全部通过。 最终输出： - 修改文件； - 问题原因； - 解决方案； - 测试结果； - 尚未解决的风险。

相比“帮我修复重复提交”，这个模板给出了任务范围、执行过程和最终验收方式，结果通常会更稳定。

总结

Codex 修改代码的成功率，取决于项目规则是否清楚，而不只是模型本身的能力。

一套稳定的使用流程应该包括：

1. 使用AGENTS.md描述项目；
2. 先分析，再制定计划；
3. 限定允许修改的文件；
4. 使用最小修改原则；
5. 为任务设置验收标准；
6. 运行测试、类型检查和构建；
7. 最后检查git diff。

不要只让 Codex“写完代码”，而要让它完成一个可以被验证的工程任务。