企业官网建设流程全解析

1. 先搞清楚 Codex 里的 AGENTS.md 到底管什么

如果你刚开始接触 Claude Code 或 Codex，并且已经成功运行了claude init指令，那你大概率已经生成了一个CLAUDE.md文件。很多新手教程会直接告诉你“去改这个文件”，但真正决定 Codex 如何理解你的项目、调用哪些工具、执行什么流程的，其实是另一个更核心的规则文件——AGENTS.md。

简单来说，CLAUDE.md是你的项目说明书，告诉 AI 助手“这个项目是干什么的、用什么技术栈、有什么特殊约定”。而AGENTS.md是 AI 助手自己的工作手册和工具箱清单，它定义了助手能扮演什么角色、可以使用哪些技能（Skills）、以及处理任务时的具体规则和流程。理解AGENTS.md，你才能真正“配置”而不仅仅是“使用” Codex。

为什么这比单纯安装更重要？因为安装只是让工具跑起来，而看懂AGENTS.md意味着你能：

1. 定制专属助手：让 Codex 按照你预设的专家角色（如“前端代码审查员”、“数据库优化顾问”）来工作。
2. 控制工具边界：明确告诉助手哪些文件能读、哪些命令能跑、哪些外部 API 能调，避免越权操作。
3. 标准化输出：确保每次代码生成、问题解答的风格和格式都符合你的团队规范。

如果你发现 Codex 有时答非所问、或者不敢执行某些合理的操作，问题很可能就出在AGENTS.md的规则定义上。下面我们就从零开始，拆解这个文件。

2. 环境与文件准备：你的第一个 AGENTS.md

在深入规则细节前，我们先确保你有一个可以编辑和测试的环境。Codex/Claude Code 通常以命令行工具或 IDE 插件形式存在，其核心配置文件就放在你的项目根目录或用户配置目录下。

2.1 确认你的工作环境

首先，你需要知道 Codex 的配置文件在哪里。根据常见的安装方式：

• 通过claude init初始化：这通常会在你的项目根目录生成CLAUDE.md和AGENTS.md（如果不存在的话）。这是项目级配置，仅对当前项目生效。
• 全局安装或用户配置：有些安装方式会在你的用户主目录（如~/.config/claude/）下生成全局的AGENTS.md。这个文件会影响所有没有项目级配置的项目。
• VS Code 插件配置：如果你使用的是 VS Code 的 Claude Code 插件，配置可能以settings.json的形式存在，但其规则逻辑与AGENTS.md是相通的。

我建议的操作顺序是：

1. 在你的项目根目录下，执行ls -la（Linux/macOS）或dir（Windows）查看是否有AGENTS.md。
2. 如果没有，尝试运行claude init或查看插件设置，看是否会生成。
3. 如果还没有，就自己创建一个空的AGENTS.md文件。Codex 会识别并使用它。

注意：项目级的AGENTS.md优先级通常高于全局配置。这意味着你可以为每个项目定制不同的助手行为。

2.2 AGENTS.md 的基本结构

一个基础的AGENTS.md文件通常包含几个核心部分。我们从一个最简单的例子开始，你可以在你的AGENTS.md里先写下这些内容：

# 项目 AI 助手代理配置 ## 代理角色定义 你是一个专注于本项目的全栈开发助手。你精通本项目使用的技术栈（例如：Python/FastAPI, React, PostgreSQL），并且严格遵守项目的代码规范和架构约定。 ## 核心能力与约束 ### 你可以： 1. 读取和分析项目根目录下 `src/`, `tests/` 目录中的所有文件。 2. 执行项目内定义的、无害的构建和测试命令（如 `npm run test`, `pytest`）。 3. 根据 `CLAUDE.md` 中的项目上下文，生成、修改或重构代码。 4. 回答关于项目技术栈和架构的问题。 ### 你禁止： 1. 修改项目根目录下的 `package.json`, `requirements.txt`, `docker-compose.yml` 等核心依赖和配置定义文件，除非用户明确指令。 2. 执行任何具有破坏性的系统级命令（如 `rm -rf /`, `format C:`）。 3. 访问或读取项目目录之外的任意文件。 4. 在未明确询问用户的情况下，调用需要网络权限或敏感信息的操作。 ## 工作流程 1. **理解需求**：首先复述用户请求，确保理解无误。 2. **分析上下文**：结合 `CLAUDE.md` 和现有代码，分析最佳实现路径。 3. **安全执行**：在提供代码或执行命令前，告知用户你将做什么以及为什么。 4. **输出格式**：提供的代码块必须指定语言，修改文件时需提供完整的 diff 格式或前后对比。 ## 技能（Skills）引用 （此部分用于链接或定义具体的技能模块，初期可留空或注释） <!-- #include: ./skills/web_scraper.md --> <!-- #include: ./skills/sql_optimizer.md -->

保存这个文件。现在，当你在该项目中向 Codex 提问时，它就会尝试遵循这个“工作手册”来行事。这个框架已经能解决很多“助手太奔放”或“助手太保守”的问题。

3. 逐层解析：从角色定义到技能调用的核心规则

上面是一个框架，现在我们来拆解每个部分的实际作用和可配置的细节。AGENTS.md的威力在于它的可读性和可编程性。

3.1 角色定义：给 AI 一个明确的“人设”

## 代理角色定义部分不是客套话。一个清晰的角色定义能显著提升回答的相关性和专业性。

• 模糊的定义：“你是一个编程助手。”
• 有效的定义：“你是本项目的资深后端工程师，特别擅长使用 FastAPI 构建高性能 REST API 和使用 SQLAlchemy 进行复杂的数据库查询优化。你注重代码的可测试性和可维护性。”

当你明确定义角色后，AI 在思考时会更倾向于调用与该角色相关的知识模式和解决方案。例如，对于“如何实现用户认证？”这个问题，一个“后端工程师”角色会优先考虑 JWT、OAuth2 流程、数据库会话管理；而一个“DevOps 工程师”角色可能会先考虑集成 Keycloak、配置 Nginx 反向代理或设置 Kubernetes Secret。

3.2 能力与约束：划定安全的操作沙箱

这是AGENTS.md的安全核心。### 你可以和### 你禁止列表直接决定了助手的能力边界。

你可以（Capabilities）：这里要具体，不要笼统地说“可以写代码”。

• 文件访问：读取和分析 ./lib/ 和 ./app/ 目录下的 .py, .js, .json 文件。比可以读文件更好。
• 命令执行：可以执行项目根目录下scripts/文件夹中所有以dev_开头的 .sh 脚本。或者可以运行make build和make test。
• 网络请求：可以调用向https://api.internal.example.com/v1/发起的 GET 和 POST 请求，但需在操作前说明请求体和预期响应。（注意：涉及内部或外部 API 时需格外谨慎）
• 工具使用：可以使用git diff来查看代码变更，使用pylint进行代码静态检查。

你禁止（Constraints）：这是防止“灾难性”操作的关键。必须明确列出高风险禁区。

• 文件保护：禁止修改或删除任何位于config/production/目录下的.yaml或.env配置文件。
• 命令黑名单：禁止执行任何包含rm,dd,mkfs,chmod 777等关键字的命令。
• 权限隔离：禁止尝试提升权限（如使用sudo）或访问/etc,/root,/home/其他用户等系统目录。
• 网络隔离：禁止向非白名单域名（如*.internal.example.com）之外的地址发起网络请求。

我一般会先在测试环境里，用一些边界案例（比如“帮我清理一下日志文件”、“看看系统状态”）来测试这些约束是否真的生效，然后再应用到正式项目。

3.3 工作流程：标准化交互过程

## 工作流程部分用于规范 AI 与你的交互模式。这能带来更一致、更可预测的体验。

一个良好的工作流程可以包括：

1. 确认（Clarify）：对于模糊需求，先提问确认细节（如“您希望这个 API 的响应格式是 JSON 还是 XML？”）。
2. 计划（Plan）：简要说明将要采取的步骤（如“我将：1. 在models.py中添加新字段；2. 创建数据库迁移脚本；3. 更新序列化器。”）。
3. 行动（Act）：执行操作，并高亮关键变化。
4. 验证（Verify）：建议或自动运行相关的测试命令，并汇报结果。

你可以这样写：

## 标准问题处理流程 1. **需求解析**：若指令不明确，主动询问截止日期、性能要求、兼容性等约束条件。 2. **方案设计**：提供1-2个简要的技术方案概述，并说明其优缺点，供用户选择。 3. **增量实施**：对于复杂任务，分步骤提交代码更改，每步完成后请求确认。 4. **交付检查**：任务完成后，提供一份简短的检查清单，例如： * [ ] 新代码是否通过了现有测试？ * [ ] 是否更新了相关的文档注释？ * [ ] 是否有明显的性能或安全顾虑需要提示？

3.4 技能（Skills）集成：扩展助手的工具箱

这是AGENTS.md更高级的用法。Skills 可以理解为预定义的、可复用的功能模块。它们通常被定义在单独的.md文件中，然后在AGENTS.md里通过#include指令或类似方式引入。

一个 Skill 文件（例如skills/data_viz.md）可能长这样：

# 数据可视化技能 ## 描述 此技能使助手能够根据提供的数据（CSV、JSON格式或Python字典）生成描述性分析并推荐合适的可视化方案（如使用 matplotlib, seaborn, plotly）。 ## 输入 - 结构化数据或数据文件路径。 - （可选）期望的图表类型或关键指标。 ## 处理逻辑 1. 尝试加载并理解数据结构。 2. 进行基础统计分析（如均值、中位数、分布）。 3. 基于数据特征（类别型、数值型、时间序列）推荐1-3种可视化类型。 4. 生成对应的 Python 代码草图，并附上简要解释。 ## 输出 - 文本分析摘要。 - 推荐的图表类型及理由。 - 可直接运行的绘图代码块。

在AGENTS.md中引用它：

## 可用技能 <!-- 引入数据可视化技能模块 --> #include ./skills/data_viz.md

这样，当用户提出“帮我分析一下这份销售数据”时，助手就知道它可以调用data_viz这个技能包来处理，而不是试图用通用编程逻辑去硬解。

技能管理的经验：

• 初期：可以不用技能，把所有规则写在AGENTS.md里。
• 中期：当规则变多，或者多个项目需要共享某些能力（如“SQL审查”、“API文档生成”）时，将通用能力抽离成技能文件。
• 协作：技能文件便于团队共享和版本控制，每个人都可以改进特定的技能模块。

4. 实战：编写与调试你的 AGENTS.md 规则

知道结构后，我们来实战编写和测试。规则文件写得好不好，关键看它能否在实际对话中稳定地引导 AI 行为。

4.1 编写策略：从简到繁，逐步细化

不要试图一次性写出完美的AGENTS.md。我建议采用迭代方式：

1. 第1版：基础安全框。只写最核心的“禁止”条款和最基本的角色定义。先保证助手不会做危险操作。
2. 第2版：添加项目上下文。参考CLAUDE.md，把项目特有的技术栈、目录结构、常用命令加进“可以”列表。
3. 第3版：优化工作流。根据前两版使用中遇到的沟通摩擦，优化工作流程。比如，如果助手经常生成大段代码却不解释，就在流程里加上“分步骤解释”的要求。
4. 第4版：引入技能。当某些任务模式反复出现（如“生成单元测试”、“优化SQL查询”），将其抽象成技能。

4.2 调试与验证：如何测试规则是否生效

规则写完了，怎么知道它起作用了？不能靠感觉，要有测试方法。

测试用例表：

实际调试时，我常用的命令和观察点：

• 观察完整对话历史：在 Claude Code 或 Codex 的界面中，查看 AI 的“思考过程”（如果支持）。有时你能看到它在决策时引用了AGENTS.md的某条规则。
• 使用“澄清”性指令：如果你不确定某条规则是否被理解，可以直接问：“根据 AGENTS.md，你现在可以执行这个操作吗？” 这能强制 AI 显式地引用规则。
• 从简单任务开始：先用一个非常明确、在规则范围内的任务测试（如“读取README.md并总结”），确保基础通路是通的，再测试复杂边界情况。

4.3 常见问题与排查顺序

当你发现规则“好像没生效”时，按这个顺序排查：

1. 文件位置与优先级：确认当前目录下的AGENTS.md是否被正确加载。尝试在对话开始时让助手“复述你的主要工作职责”，看它描述的是否是你文件里定义的角色。
2. 语法与格式：检查 Markdown 语法是否正确。特别是使用#include时，路径是否正确，被引用的技能文件是否存在且格式无误。一个常见的错误是路径使用了绝对路径或错误的相对路径。
3. 规则冲突或歧义：规则是否自相矛盾？例如，既说“可以执行所有npm run脚本”，又说“禁止执行可能安装依赖的脚本”。AI 在遇到模糊指令时可能会选择最保守或最不可预测的行为。规则要尽量具体、无歧义。
4. AI 的“理解”偏差：有时 AI 可能“理解”了规则，但在复杂场景下判断失误。这时需要你细化规则。例如，将“禁止修改核心配置文件”细化为“禁止修改任何扩展名为.config,.env,docker-compose.yml的文件，除非指令中明确包含‘我授权修改配置文件’字样”。
5. 工具/版本差异：不同版本或发行版的 Claude Code/Codex 对AGENTS.md的支持程度可能不同。查阅你所用版本的官方文档（如果有），确认其配置文件的完整规范。

5. 进阶：将 AGENTS.md 融入团队工作流

对于个人项目，AGENTS.md能让你拥有一个高度定制化的助手。对于团队项目，它则是一个强大的协作与知识沉淀工具。

5.1 作为团队规范载体

你可以把团队的开发规范直接写入AGENTS.md：

• 代码风格：“所有生成的 Python 代码必须符合 Black 格式化标准，使用单引号。”
• 提交规范：“在建议 Git 提交信息时，需遵循 Conventional Commits 格式（如feat:,fix:）。”
• 安全红线：“任何时候不得建议将密码、密钥等硬编码在源码中。”
• 审查要点：“在生成代码后，应自动提示进行单元测试覆盖率和静态类型检查（如mypy）。”

这样，新成员通过 AI 助手获得的帮助，天然就符合团队规范，减少了培训成本。

5.2 与 CLAUDE.md 的分工与协作

很多人混淆CLAUDE.md和AGENTS.md。记住这个核心区别：

• CLAUDE.md是“项目档案”：描述项目本身——这是什么项目、用了什么、怎么跑起来、有什么特殊设定。它是给 AI 看的项目 README。
• AGENTS.md是“助手章程”：规定AI 助手——你是谁、你能做什么、不能做什么、应该怎么做事。它是 AI 的行为准则。

它们需要配合使用。一个典型的协作流程是：

1. AI 助手首先读取AGENTS.md，明确自己的身份和行为边界。
2. 当用户提出一个具体项目问题时，AI 再去查阅CLAUDE.md，获取项目背景知识。
3. AI 结合两者（行为准则 + 项目知识），生成符合规范和上下文的回答或代码。

因此，在团队中，CLAUDE.md由项目负责人或核心开发者维护，保证项目描述的准确性。AGENTS.md则可以由技术负责人或 DevOps 工程师维护，定义团队通用的 AI 协作规范，并可以作为一个模板被各个项目复用和微调。

5.3 版本控制与持续演进

将AGENTS.md和相关的技能文件（skills/目录）纳入 Git 版本控制。这带来了几个好处：

• 可追溯：可以清楚地看到规则是如何随着团队经验积累而演变的。
• 可回滚：如果某次规则修改导致了意外的助手行为，可以快速回退到上一个稳定版本。
• 可复用：可以建立一个“公司级”或“团队级”的最佳实践AGENTS.md模板，新项目初始化时直接复制过去，再根据项目特点微调。

最后，也是最重要的建议：不要追求一个一劳永逸、完美无缺的AGENTS.md文件。把它当作一个活的文档。每次当你对助手的回答感到“差点意思”或者“它不该这么做”的时候，就去审视和更新AGENTS.md。这个过程本身，就是你和你的人工智能结对编程伙伴不断磨合、形成默契的过程。真正的价值不在于文件本身，而在于你通过定义规则，更清晰地梳理和固化了你的开发流程与最佳实践。