企业官网建设流程全解析

1. 从两份说明书说起：AGENTS.md 到底解决了什么痛点

如果你同时用 Claude Code 和 Codex 写代码，大概率经历过这种别扭事：项目根目录下躺着一个CLAUDE.md，写着项目结构、编码规范、测试命令；转头打开 Codex，它不认这个文件，你得再维护一份AGENTS.md，内容大差不差，但格式要求、字段命名又略有出入。改一次架构，两个文件都得动，漏掉一个就开始出现"Agent 按旧规范写代码"的诡异现象。

Claude Code 正式支持AGENTS.md这件事，本质上就是把这份重复劳动砍掉了一半。现在你可以只维护一份AGENTS.md，Claude Code 会把它当作项目级上下文来读取，和 Codex 共用同一套说明。对多 Agent 协作的团队来说，这不是"多支持一个文件名"这么简单，而是把项目说明书从"每个工具一份"变成了"项目一份、工具共享"。

先把概念理清楚，避免后面绕晕。AGENTS.md是一份放在项目仓库里的 Markdown 文件，用自然语言描述这个项目的关键信息：目录结构、技术栈、构建与测试命令、代码风格、禁止事项、常见坑。它的定位是"给 AI 编码助手看的 README"——README 是给人看的，讲的是怎么用这个项目；AGENTS.md是给 Agent 看的，讲的是怎么改这个项目。

CLAUDE.md是 Claude Code 早期专属的项目记忆文件，格式和AGENTS.md高度相似，但只被 Claude Code 识别。Codex 走的是AGENTS.md路线，OpenAI 那边把它作为跨工具的项目约定来推。两边各认各的，就出现了开头说的双份维护问题。

这次支持之后，Claude Code 的读取优先级大致是这样的：如果项目里同时存在CLAUDE.md和AGENTS.md，它会按自己的规则合并或择一（具体行为随版本演进，建议以你本地版本的实测为准）；如果只有AGENTS.md，它就直接用。这意味着新项目可以直接上AGENTS.md，老项目可以逐步把CLAUDE.md的内容迁移过去，最终只留一份。

谁最该关注这件事？三类人。第一类是同时用多个 Agent 的独立开发者，省下的是实打实的维护时间。第二类是团队里负责"AI 工程化"的人，统一说明书意味着新人接入任何 Agent 都看同一份规范。第三类是刚开始接触 Agent 编码工具的新手，从第一天就用对文件，比后面迁移省事得多。

提示：AGENTS.md不是配置文件，没有严格的 schema，它是自然语言文档。写得越具体、越贴近真实操作，Agent 的表现越稳；写得越空泛，越容易被忽略。

2. AGENTS.md 与 CLAUDE.md 的差异拆解与选型思路

2.1 两者到底差在哪：从字段到读取逻辑

很多人以为这俩只是文件名不同，其实在细节上有几处值得注意的差异。下面这张表是我在实际项目里对比出来的，供你选型时参考。

从表里能看出来，AGENTS.md的定位更"中立"。它不绑定某一个厂商的工具，谁认这个约定谁就能读。这也是为什么这次 Claude Code 跟进支持，被很多人看作"向通用约定靠拢"的信号。

选型思路其实很简单：新项目直接上AGENTS.md，别犹豫。老项目如果只有CLAUDE.md，先别急着删，确认你当前 Claude Code 版本对AGENTS.md的支持稳定后，再把内容迁过去，保留一段时间双文件并行做过渡。团队协作场景下，统一到AGENTS.md的收益最大，因为 Codex 用户和 Claude Code 用户看的是同一份东西，评审时不会出现"你按你的规范、我按我的规范"。

2.2 为什么是 AGENTS.md 胜出，而不是各搞各的

这里有个容易被忽略的逻辑：Agent 编码工具的核心竞争力之一，是"对项目的理解程度"。理解从哪来？从上下文来。上下文里最稳定、最可控的部分，就是项目自己提供的说明书。如果每个工具都要求一份专属说明书，那项目维护者就被绑死在工具选择上——换工具等于重写文档，迁移成本高得离谱。

AGENTS.md作为跨工具约定，把这个成本降下来了。它的价值不在于格式多先进，而在于"大家都认"。这跟.editorconfig统一编辑器风格、package.json统一 Node 项目元信息是一个道理：约定本身不神奇，神奇的是生态都接受它。

Claude Code 支持它，等于承认了"项目说明书应该是项目资产，而不是工具资产"。这个转变对长期维护的项目意义很大。你想想，一个跑了两年的项目，CLAUDE.md里积累了无数踩坑记录和架构决策，如果哪天团队决定换工具，这些内容能不能带走？能，只要它在AGENTS.md里。

2.3 迁移前必须想清楚的三件事

第一件，内容归属。CLAUDE.md里有些内容是 Claude Code 特有的技巧（比如某些提示词写法），这些迁到AGENTS.md后可能对 Codex 无意义，甚至产生误导。迁移时要把"通用项目信息"和"工具专属技巧"分开，前者进AGENTS.md，后者可以留在本地或单独文档。

第二件，层级结构。两个文件都支持子目录嵌套，但覆盖规则可能不同。迁移前先确认你项目里有没有子目录级的CLAUDE.md，如果有，要一并规划子目录的AGENTS.md，否则会出现"根目录规范生效、子目录规范丢失"的情况。

第三件，版本兼容。不同版本的 Claude Code 对AGENTS.md的支持程度不一样，有的版本可能只读根目录，有的支持嵌套。迁移前用一个小项目实测一遍，确认读取行为符合预期，再动主项目。

注意：迁移不是"删旧建新"就完事。建议保留CLAUDE.md至少一个迭代周期，观察 Agent 行为有没有退化，确认无误后再清理。

3. 一份高质量 AGENTS.md 的结构设计与实操写法

3.1 推荐结构：从"项目是什么"到"别碰什么"

写AGENTS.md最忌讳的是写成散文。Agent 读文档是为了执行任务，它需要的是可检索、可定位的信息。我实践下来，下面这个结构最稳，按重要性排序：

1. 项目概述：一句话说清项目做什么、技术栈是什么。
2. 目录结构：关键目录及用途，标注哪些是生成物、哪些是手写代码。
3. 构建与测试命令：精确到可直接复制执行的命令。
4. 代码规范：命名、格式、导入顺序、注释要求。
5. 禁止事项：明确列出不能做的事，比如不能改生成文件、不能引入某类依赖。
6. 常见坑与背景知识：那些"不看就会踩"的隐性规则。

这个顺序的逻辑是：先让 Agent 建立全局认知，再给它操作手段，最后用禁止事项兜底。很多人的AGENTS.md只写了前两条，结果 Agent 能看懂项目但一动手就出错，问题往往出在缺少禁止事项和背景知识。

3.2 每个部分怎么写才有效

项目概述部分，控制在三到五行。写清楚技术栈版本很关键，比如"Node 20 + TypeScript 5.4 + pnpm"，而不是笼统的"用 Node 和 TS"。版本信息直接影响 Agent 生成的代码语法，写清楚能省掉大量返工。

目录结构部分，用列表而不是树形图。树形图好看但难检索，列表更实用。每个目录后面跟一句用途说明，比如：

• src/core/：核心业务逻辑，纯函数为主，不依赖框架。
• src/adapters/：外部接口适配层，所有网络请求集中在这里。
• generated/：自动生成代码，禁止手动修改。

构建与测试命令部分，给完整命令，不要给"运行测试"这种模糊描述。要写成pnpm test --filter=core这种可直接执行的。如果测试有前置步骤（比如先起本地服务），也要写进去。

代码规范部分，只写那些"Agent 容易搞错"的点。通用的格式规范交给 linter 就行，不用在AGENTS.md里重复。重点写项目特有的约定，比如"所有异步函数必须显式处理错误，禁止裸 await"。

禁止事项部分是价值最高的。把你踩过的坑都写进去：不能改哪些文件、不能引入哪些依赖、不能用的 API。这一部分写得越具体，Agent 越不容易闯祸。

3.3 一个可直接抄的模板

下面这份模板是我在多个项目里迭代出来的，你可以直接拿去改。

# AGENTS.md ## 项目概述 - 技术栈：Node 20 + TypeScript 5.4 + pnpm - 用途：订单处理服务，对外提供 REST API - 入口：src/index.ts ## 目录结构 - src/core/：核心业务逻辑，纯函数，无框架依赖 - src/adapters/：外部接口适配，网络请求集中于此 - src/api/：HTTP 路由与参数校验 - generated/：自动生成，禁止手动修改 - tests/：测试用例，与 src 目录结构对应 ## 构建与测试 - 安装依赖：pnpm install - 本地开发：pnpm dev - 运行测试：pnpm test - 单文件测试：pnpm test <file> - 类型检查：pnpm typecheck ## 代码规范 - 异步函数必须显式 try/catch，禁止裸 await - 导入顺序：node 内置 → 第三方 → 本地，组间空行 - 所有导出函数必须有 JSDoc 注释 - 禁止使用 any，必要时用 unknown + 类型守卫 ## 禁止事项 - 禁止修改 generated/ 下任何文件 - 禁止在 core/ 中引入网络请求库 - 禁止新增依赖，如需新增先说明理由 - 禁止提交 console.log 调试代码 ## 常见坑 - 测试依赖本地 Redis，跑测试前先执行 pnpm redis:start - 时区统一用 UTC，禁止用本地时间 - 金额字段统一用整数分，禁止用浮点

这份模板大概一百多行，覆盖了日常开发 90% 的场景。你可以根据项目特点增删，但建议保留"禁止事项"和"常见坑"这两块，它们是防止 Agent 犯错的关键。

3.4 子目录 AGENTS.md 的用法

大项目里，根目录的AGENTS.md不可能写全所有细节。这时候用子目录级的AGENTS.md做局部覆盖。比如src/adapters/AGENTS.md里写这个目录特有的约定：所有适配器必须实现统一的接口、错误必须转成项目自定义错误类型、超时时间统一配置。

子目录文件的读取逻辑是"就近优先"：Agent 处理src/adapters/下的文件时，会同时读根目录和该子目录的AGENTS.md，冲突时子目录优先。这个机制让你可以把通用规范放根目录、局部规范放子目录，避免根目录文件无限膨胀。

提示：子目录AGENTS.md不要写和根目录重复的内容，只写差异部分。重复内容不仅浪费上下文，还容易在更新时漏改一处导致矛盾。

4. 多 Agent 协作下的实操流程与配置细节

4.1 从零搭建：新项目的标准动作

新项目第一天就把AGENTS.md建起来，比后面补要省事得多。我的标准动作是：初始化项目后，先写AGENTS.md骨架，再写第一行业务代码。骨架不用很全，把项目概述、目录结构、构建命令三块填上就行，剩下的随着开发逐步补。

为什么先写文档再写代码？因为写文档的过程会逼你想清楚项目结构。很多人上来就写代码，写到一半发现目录乱了、命令不统一，回头再补文档，文档和现实已经对不上了。先写文档相当于先画图纸再施工，返工少。

具体步骤：

1. 创建项目，初始化package.json或对应语言的工程文件。
2. 在根目录创建AGENTS.md，填入项目概述和预期目录结构。
3. 确定构建、测试、类型检查命令，写进文档。
4. 提交一次，让文档成为项目的一部分。
5. 后续每次调整结构或命令，同步更新文档。

第 5 步是最容易被忽略的。文档一旦和现实脱节，Agent 就会按过时信息操作，反而添乱。建议把"更新 AGENTS.md"写进代码评审清单，改结构必须改文档。

4.2 老项目迁移：分三步走

老项目迁移别想着一步到位，分三步更稳。

第一步，盘点。把现有CLAUDE.md通读一遍，把内容分成三类：通用项目信息、Claude Code 专属技巧、过时内容。通用信息是要迁的，专属技巧留着或单独归档，过时内容直接删。

第二步，试迁。在项目里新建AGENTS.md，把通用信息填进去，先不删CLAUDE.md。用 Claude Code 跑几个典型任务，观察行为有没有变化。重点看它是否还遵守原来的规范、是否出现新的错误。

第三步，切换。确认无误后，把CLAUDE.md精简成一行指向AGENTS.md的说明，或者直接删除。保留一个迭代周期后彻底清理。

这个流程的核心是"可回退"。直接删旧文件风险太大，万一新文件有遗漏，Agent 行为退化你都不知道从哪查。保留旧文件做对照，出问题能快速定位。

4.3 和 Codex 共用的注意事项

既然目标是"一份文档两个工具用"，那就要考虑两个工具的读取差异。实测下来有几个点要注意。

命令写法上，Claude Code 和 Codex 对命令的解析能力不同。有些复杂命令（带管道、带环境变量）在一边能跑，另一边可能被截断。建议AGENTS.md里的命令尽量简单，复杂操作拆成多步写。

文件引用上，两个工具对路径的解析基准可能不同。写路径时统一用相对项目根目录的路径，避免歧义。

上下文长度上，两个工具对AGENTS.md的读取长度限制不同。文档太长可能被截断，导致后面的内容读不到。建议把最重要的信息放前面，禁止事项和常见坑这类关键内容不要放太后面。

注意：如果你的AGENTS.md超过几百行，考虑拆分到子目录文件，而不是全堆在根目录。上下文是有限资源，别浪费在重复和冗余上。

4.4 团队协作下的文档治理

一个人用AGENTS.md和团队用是两回事。团队场景下，文档会变成多人编辑的公共资产，需要治理规则。

谁负责更新？建议指定一个"文档 owner"，或者按模块分工：改src/adapters/的人负责更新对应的子目录文档。避免出现"谁都不管、文档烂掉"的情况。

怎么评审？把AGENTS.md的改动纳入代码评审。改文档和改代码一样需要 review，防止有人塞进错误信息误导 Agent。

怎么处理冲突？多人同时改文档容易冲突。建议小步提交，每次只改一个主题，减少合并冲突。冲突时以"更具体、更贴近当前代码"的版本为准。

版本怎么管？AGENTS.md跟着代码走，用同一个版本控制。不要单独维护一份"文档版本"，那样迟早对不上。

5. 常见问题排查与踩坑实录

5.1 Agent 不读 AGENTS.md 怎么办

最常见的问题是"我写了文档但 Agent 好像没看"。排查顺序如下。

先确认文件名和位置。必须是根目录下的AGENTS.md，大小写敏感。写成agents.md或放在子目录里，可能读不到。

再确认版本支持。老版本 Claude Code 可能不支持AGENTS.md，只认CLAUDE.md。升级到支持版本再试。

然后确认内容格式。文档开头如果有大量无关内容，Agent 可能"读到了但没重视"。把关键信息放前面，用清晰的标题分隔。

最后用测试验证。在文档里写一条明显的规则（比如"所有函数名用 snake_case"），然后让 Agent 写个函数，看它是否遵守。遵守说明读取正常，不遵守说明有问题。

5.2 文档写了但 Agent 不遵守

读取正常但不遵守，通常是文档写得太模糊。比如写"代码要整洁"，Agent 不知道什么叫整洁。改成"函数不超过 50 行、嵌套不超过 3 层"，就可执行了。

另一个原因是规则太多、互相冲突。Agent 面对矛盾规则时会随机选一个。定期清理文档，删掉过时和矛盾的条目。

还有一种情况是规则和代码现实不符。文档说用 A 方案，代码里全是 B 方案，Agent 会倾向于跟随代码。这时候要么改代码，要么改文档，别让两者打架。

5.3 排查速查表

5.4 几个我踩过的坑

第一个坑：把AGENTS.md写成了项目 README 的复制品。README 讲"怎么用"，AGENTS.md讲"怎么改"，两者受众不同。复制 README 会导致 Agent 拿到一堆用户视角的信息，缺少开发者视角的规范。

第二个坑：文档里写了"参考 xxx 文件"。Agent 不一定去读那个文件，写了等于没写。要么把关键内容直接写进AGENTS.md，要么明确说"修改前必须先读 xxx 文件"。

第三个坑：迁移时把 Claude Code 专属的提示词技巧也搬过去了。这些技巧对 Codex 无意义，还占上下文。迁移时要做减法，不是全盘复制。

第四个坑：文档更新滞后。改了构建命令没改文档，Agent 按旧命令执行失败，排查半天才发现是文档问题。现在我把"改命令必须改文档"当成硬规则。

第五个坑：子目录文档写太多。每个子目录都写一大篇，结果 Agent 读的时候上下文被塞满，反而忽略了根目录的关键规则。子目录文档只写差异，越短越好。

6. 把 AGENTS.md 用出复利：长期维护的几个习惯

AGENTS.md的价值不是一次写成的，是长期维护出来的。我观察下来，用得好的项目都有几个共同习惯。

习惯一：把踩过的坑即时写进去。每次 Agent 犯了个错，排查完就在AGENTS.md里加一条规则，防止再犯。这样文档会越来越贴合项目实际，Agent 表现越来越稳。这比一次性写一篇完美文档有用得多，因为真实项目里的坑是逐步暴露的。

习惯二：定期精简。文档只增不减会越来越臃肿，上下文被浪费。每隔一段时间通读一遍，删掉过时内容、合并重复条目、把不再需要的规则移除。精简后的文档 Agent 读起来更聚焦。

习惯三：区分"必须遵守"和"建议"。必须遵守的用明确措辞（"禁止""必须"），建议的用"推荐""优先"。Agent 对措辞的敏感度比人高，措辞清晰能减少误判。

习惯四：和代码同步演进。项目重构、换依赖、改命令时，把AGENTS.md当成代码的一部分一起改。别让它变成"历史文档"。

习惯五：跨工具验证。既然目标是多工具共用，就定期用不同工具跑同一批任务，看行为是否一致。不一致的地方往往是文档写得不够明确，正好借机改进。

这套习惯坚持下来，AGENTS.md会从"一份说明"变成"项目的活文档"。新人和新 Agent 接入时，读这一份就能上手，不用再问东问西。这才是它真正的复利所在——省下的不只是维护两份文档的时间，还有每次沟通、每次排查、每次返工的成本。

最后分享一个我自己的小做法：在AGENTS.md末尾留一个"最近更新"区块，记录最近几次改了什么、为什么改。这样回溯时能快速知道某条规则的来龙去脉，避免误删。这个区块不用长，一两行一次就够，但长期积累下来，它本身就是一份项目决策日志。