企业官网建设流程全解析

摘要

使用 Codex 修改真实项目时，不少开发者都会遇到类似问题：只想修复一个页面，结果它同时调整了公共组件；只想修复一个 Bug，却顺手重构了整个模块；明明项目使用 pnpm，它却生成了 npm 命令。

这些问题不一定是 Codex 不会写代码，更多时候是项目没有提供足够明确的工程规则。本文介绍如何使用AGENTS.md为 Codex 持久化项目结构、验证命令、修改边界和交付标准，减少无关修改，让 AI 编程任务更加稳定。

使用 Codex 处理简单代码片段时，我们通常不需要提供太多背景。

例如：

解释这个 TypeScript 类型错误，并给出修改建议。

但当 Codex 进入真实项目后，情况会变得完全不同。

真实项目一般包含：

• 固定的目录结构；

• 统一的接口封装；

• 特定的状态管理方式；

• 已经存在的公共组件；

• 团队约定的代码风格；

• 测试、构建和代码检查命令；

• 不允许随意修改的核心模块。

如果没有把这些规则告诉 Codex，它只能根据当前文件和通用经验自行判断。结果可能是代码本身没有明显语法错误，却不符合项目的实际约定。

解决这类问题的一种有效方式，就是在项目中建立AGENTS.md。

一、AGENTS.md 是什么？

可以把AGENTS.md理解为一份专门写给编程智能体看的项目说明。

OpenAI 官方将它描述为面向智能体的开放格式说明文件。Codex 会自动把其中的内容加载进上下文，适合记录项目布局、运行命令、工程规范、禁止事项以及任务完成后的验证要求。

普通的README.md更多是写给开发者看的，通常介绍：

• 项目是什么；

• 如何安装；

• 如何启动；

• 如何部署。

而AGENTS.md更适合告诉 Codex：

• 修改代码前应该先做什么；

• 哪些目录可以修改；

• 哪些文件禁止改动；

• 应该运行哪些检查；

• 什么结果才算任务完成。

例如：

# AGENTS.md ## 项目技术栈 - Vue 3 - TypeScript - Vite - Pinia ## 目录约定 - `src/api`：接口请求 - `src/types`：类型定义 - `src/views`：业务页面 - `src/components`：公共组件 - `tests`：测试文件 ## 修改规则 - 不新增第三方依赖 - 不修改无关业务模块 - 不改变后端接口字段 - 不全局格式化代码 - 不删除历史兼容逻辑 ## 验证命令 - `npm run type-check` - `npm run test` - `npm run build`

有了这份文件，开发者就不需要在每个任务中反复解释相同规则。

二、为什么 Codex 会修改无关文件？

1. 任务目标过于宽泛

例如：

帮我优化订单模块。

“优化”可能包括很多事情：

• 优化性能；

• 调整目录；

• 重构组件；

• 修改接口；

• 合并重复逻辑；

• 增加缓存；

• 补充测试。

如果没有进一步限制，Codex 很可能扩大任务范围。

更合适的写法是：

只修复订单列表切换筛选条件时重复请求的问题。 不要调整目录结构，不要修改订单详情页，也不要新增依赖。

2. 项目规范没有明确记录

如果项目规定所有请求必须放在src/api，但这一规则没有写进文档，Codex 可能直接在页面组件里调用请求。

如果项目统一使用 pnpm，但没有明确说明，它也可能生成 npm 或 yarn 命令。

3. “完成”的定义不清楚

开发者说“修复完成”，可能意味着：

• Bug 已经消失；

• 类型检查通过；

• 测试通过；

• 构建通过；

• 没有无关修改。

Codex 如果只理解为“代码已经改完”，就可能在没有运行验证的情况下结束任务。

因此，项目规则中要写清楚：

代码生成不是任务完成，验证通过并检查 Diff 后才算完成。

三、AGENTS.md 应该写哪些内容？

一份实用的AGENTS.md不需要非常长，重点是准确、明确、可执行。

OpenAI 官方最佳实践建议把它用于记录仓库布局、运行方式、构建测试命令、工程约定、PR 要求、禁止规则和验收标准，同时保持内容精简。

1. 项目技术栈

告诉 Codex 当前项目使用什么技术。

## 技术栈 - React 19 - TypeScript - Vite - Zustand - Vitest

这样可以减少它生成与当前框架不匹配的代码。

2. 目录职责

## 目录职责 - `src/pages`：页面组件 - `src/api`：接口封装 - `src/types`：公共类型 - `src/hooks`：可复用 Hooks - `src/stores`：全局状态 - `tests`：自动化测试

目录职责越清楚，Codex 越不容易把业务代码放错位置。

3. 修改边界

## 修改边界 - 优先修改与当前任务直接相关的文件 - 不修改未在任务中提及的业务模块 - 不主动调整路由配置 - 不修改 `package.json` - 不新增生产依赖 - 如需扩大范围，先说明原因

这里尤其建议加入：

如果必须扩大修改范围，先说明原因，不要直接修改。

它可以阻止任务在不知不觉中变大。

4. 代码规范

## 代码规范 - 新代码必须使用 TypeScript - 优先复用现有工具函数 - 不重复实现已有公共组件 - 保持现有命名和文件组织方式 - 不进行与任务无关的格式化 - 公共函数需要补充类型说明

5. 验证命令

## 验证要求 修改完成后依次运行： 1. `npm run type-check` 2. `npm run lint` 3. `npm run test` 4. `npm run build` 如果命令失败： - 先分析失败原因 - 判断是否由本次修改引起 - 不得通过跳过测试或关闭规则解决问题

6. 交付标准

## 完成标准 任务完成前必须： - 说明修改了哪些文件 - 说明每个文件的修改目的 - 报告测试和构建结果 - 检查 `git diff` - 确认没有无关修改 - 列出仍未解决的风险

四、如何创建 AGENTS.md？

如果使用 Codex CLI，可以通过/init命令生成一份初始AGENTS.md，再根据项目真实情况修改。官方文档也强调，自动生成的内容只是起点，最终规则应该反映团队真实的构建、测试、审查和交付方式。

也可以直接在仓库根目录手动创建：

touch AGENTS.md

一个可以直接参考的完整版本如下：

# AGENTS.md ## 项目说明 这是一个基于 Vue 3、TypeScript、Vite 和 Pinia 的后台管理项目。 ## 主要目录 - `src/api`：接口请求 - `src/types`：类型定义 - `src/views`：业务页面 - `src/components`：公共组件 - `src/stores`：状态管理 - `tests`：测试文件 ## 工作方式 1. 修改前先分析相关调用链 2. 先给出涉及文件和修改方案 3. 优先采用最小修改原则 4. 不要主动重构无关代码 5. 修改完成后运行验证命令 6. 最后检查 Git Diff 并输出总结 ## 禁止事项 - 不新增第三方依赖 - 不修改 `package.json` - 不改变接口字段 - 不调整路由结构 - 不删除权限判断 - 不全局格式化代码 - 不修改当前任务以外的模块 ## 验证命令 - `npm run type-check` - `npm run lint` - `npm run test` - `npm run build` ## 完成标准 - 所有验证命令通过 - 没有无关文件变化 - 没有新增依赖 - 没有改变公开接口 - 输出修改文件、验证结果和风险说明

五、大型项目可以分目录建立规则

大型仓库里，不同目录可能使用不同的开发规范。

例如：

project/ ├── AGENTS.md ├── apps/ │ ├── web/ │ │ └── AGENTS.md │ └── admin/ │ └── AGENTS.md └── services/ └── payment/ └── AGENTS.override.md

根目录的文件可以记录所有模块共同遵守的规则。

子目录中的文件则记录当前模块的特殊要求，例如：

# services/payment/AGENTS.override.md ## 支付模块规则 - 修改前必须先阅读支付状态机 - 不允许改变金额计算精度 - 不允许修改回调验签逻辑 - 必须运行支付模块集成测试 - 任何数据库结构变化都要先停止并说明

Codex 会从项目根目录向当前工作目录查找规则，并按层级合并；距离当前目录更近的规则会出现在后面，因此可以覆盖上层的通用指导。AGENTS.override.md可用于在某一层提供更明确的覆盖规则。

这种设计很适合：

• Monorepo；

• 前后端共用仓库；

• 多服务项目；

• 支付、权限等高风险模块；

• 不同团队共同维护的代码库。

六、有了 AGENTS.md，任务仍然要写清楚

AGENTS.md不能替代具体任务。

它负责记录长期规则，当前提示词负责说明本次要做什么。

推荐使用下面的任务模板：

任务目标： 修复订单列表切换状态后重复请求的问题。 允许修改： - src/views/order/List.vue - src/api/order.ts - tests/order/List.test.ts 禁止修改： - 用户模块 - 支付模块 - 路由配置 - package.json 执行步骤： 1. 先阅读 AGENTS.md 2. 分析重复请求的触发链路 3. 输出可能原因和最小修改方案 4. 修改相关文件 5. 运行项目规定的验证命令 6. 检查 Git Diff 7. 输出交付总结 验收标准： - 首次加载只请求一次 - 切换筛选条件正常重新请求 - 不改变接口字段 - 不新增依赖 - 测试和构建通过 - 没有无关修改

可以简单理解为：

• AGENTS.md管长期规则；

• 当前提示词管本次任务；

• Git Diff 管最终结果。

三者配合，Codex 的任务稳定性会明显提高。

七、如何检查 Codex 是否遵守规则？

1. 任务开始前让它总结规则

开始任务前，请先读取 AGENTS.md，并总结本次需要遵守的规则。 暂时不要修改代码。

如果总结与项目规则不一致，可以在任务开始前纠正。

2. 修改完成后检查 Git Diff

git status git diff --stat git diff

重点检查：

• 是否修改了允许范围以外的文件；

• 是否改变了接口或公共类型；

• 是否新增了依赖；

• 是否出现大面积格式化；

• 是否删除了历史兼容逻辑；

• 是否真正运行了验证命令。

3. 让 Codex 做一次规则审查

请根据 AGENTS.md 审查本次 Git Diff。 输出： 1. 是否违反修改边界 2. 是否存在无关修改 3. 是否改变公开接口 4. 是否新增未经允许的依赖 5. 是否完成全部验证 6. 是否达到项目定义的完成标准 先输出审查结果，不要继续修改。

八、AGENTS.md 也需要持续维护

项目规则不是创建一次就永远不变。

当 Codex 多次出现同一种问题时，可以把解决经验写回AGENTS.md。

例如它经常修改package.json，可以补充：

- 未经明确允许，不得修改 `package.json` 或 Lock 文件。

如果它经常跳过完整测试，可以补充：

- 局部测试通过后，仍需运行完整类型检查和构建。

官方也建议把反复出现的审查反馈写进AGENTS.md，形成持续改进的反馈循环；同时把规则放在最接近适用代码的目录中。

不过不要把所有临时需求都塞进去。

适合写入的内容是：

• 长期有效的项目规范；

• 多次重复出现的问题；

• 所有任务都应该遵守的规则；

• 高风险模块的固定限制。

一次性需求仍然应该写在当前任务提示词中。

九、常见误区

误区一：AGENTS.md 写得越长越好

规则太多、太模糊，反而会降低重点。

应该优先保留：

• 必须遵守的限制；

• 真实可运行的命令；

• 清楚的目录职责；

• 明确的完成标准。

误区二：只写技术栈，不写验证方式

告诉 Codex 项目使用 Vue，并不能保证任务完成。

还要告诉它：

• 如何测试；

• 如何构建；

• 如何检查修改；

• 什么才算完成。

误区三：规则写了，但任务范围仍然模糊

AGENTS.md不能把“帮我优化项目”自动变成一个边界明确的任务。

每次仍然要写清楚目标、范围和验收标准。

误区四：完全相信 Codex 已经遵守规则

规则可以提高稳定性，但不能代替测试和人工审查。

最终仍然要检查 Git Diff。

总结

Codex 总是修改无关文件，很多时候不是代码能力问题，而是项目规则和任务边界没有表达清楚。

AGENTS.md可以帮助开发者把长期有效的工程要求写进仓库，包括：

• 项目结构；

• 目录职责；

• 修改边界；

• 禁止事项；

• 测试命令；

• 代码审查要求；

• 任务完成标准。

更稳定的使用方式是：

用 AGENTS.md 固定长期规则，用任务提示词限定当前范围，用测试和 Git Diff 验证最终结果。

AI 编程不是让 Codex 获得无限自由，而是让它在清晰的工程规范内完成可验证的任务。

当规则、任务和验证形成闭环后，Codex 才更适合进入真实项目，而不仅仅是生成几段代码。

CSDN 文章描述

Codex 总是修改无关文件怎么办？本文介绍如何使用 AGENTS.md 为 Codex 建立项目规则，包括目录规范、修改边界、验证命令、分层规则和 Git Diff 审查方法。

参考资料

1. OpenAI Developers：Custom instructions with AGENTS.md。

2. OpenAI Developers：Codex Best Practices。

3. OpenAI Developers：Codex Customization。

4. OpenAI Developers：Codex CLI。