企业官网建设流程全解析

1. 为什么需要 CLAUDE.md 与 AGENTS.md 双文件协同

如果你同时用 Claude Code、Cursor、Cline、Codex 这几类工具写代码，大概率遇到过这种糟心事：在 Claude Code 里调教好的规则，换个工具就全失效了。你明明在CLAUDE.md里写了「所有回答用简体中文」「方法必须带注释」，结果切到别的工具，它照样给你飙英文、生成一堆没注释的代码。

问题的根源在于：不同 AI 编码工具读取的规则文件名不一样。Claude Code 认CLAUDE.md，而越来越多的工具（包括 Cursor、部分 Agent 框架、以及 TaoToken 这类聚合网关背后的模型调用链）开始统一认AGENTS.md。你只维护一份，就必然有一半工具读不到。

我试过最笨的办法——两份文件各写一遍，结果改了一处忘了另一处，规则越漂越远。后来改成「单一事实来源 + 同步脚本」：把规则正文集中放在一个地方，用脚本生成CLAUDE.md和AGENTS.md，项目根目录放一份、全局目录放一份。这样无论你切到哪个工具、在哪个项目里，AI 拿到的上下文都是同一套。

这篇就按这个思路走：先讲清楚两个文件各自管什么、放哪里，再给你可复制的目录结构、文件模板和同步脚本，最后演示改完规则怎么验证它真的生效了。适合手上同时开着两三个 AI 编码工具、被规则不一致折磨过的开发者。核心检索词就三个：CLAUDE.md 全局文件配置、AGENTS.md 规则同步、多工具统一上下文。

先说清楚两个文件的定位差异，这决定了你该往哪写：

CLAUDE.md是 Claude Code 的原生记忆文件。它会在会话启动时被读取，注入到系统提示里。Claude Code 支持多层级：项目根目录的./CLAUDE.md、用户全局的~/.claude/CLAUDE.md，还有子目录里的。层级越靠近当前工作目录，优先级越高。

AGENTS.md是一个更通用的约定，社区里把它当作「跨工具的规则入口」。它的位置通常在项目根目录./AGENTS.md，全局位置各家实现不同，常见的是~/.config/agents/AGENTS.md或直接放家目录~/AGENTS.md。

关键点：规则内容应该只有一份。我的做法是把真正的规则写进AGENTS.md，然后让CLAUDE.md通过引用或同步脚本跟它保持一致。这样新增工具时，只要它认AGENTS.md，就自动继承全部规则。

还有一个容易忽略的坑：全局文件和项目文件的合并顺序。全局放通用偏好（语言、注释风格、禁止行为），项目放项目专属约束（输出目录、技术栈、目录结构）。如果两边冲突，项目级应该覆盖全局级。Claude Code 是按「从全局到项目」逐层加载、后者覆盖前者的逻辑，所以你把「禁止操作 git」放全局、「本项目允许提交到 feature 分支」放项目，是能生效的。

理解了这层，下面就可以动手搭目录了。

2. TaoToken 前置准备：拿到 Base URL、Key 和 Model ID

在配规则文件之前，得先把工具能跑起来。不管你用 Claude Code 还是别的客户端，接入 TaoToken 都需要三样东西：Base URL、API Key、Model ID。这三件套缺一不可，很多人卡在 401 就是因为只填了 Key 没填对 Base URL。

TaoToken 的 API 入口是https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 Base URL 用。官网在https://taotoken.net/，注册和看文档都从这里进。

拿 Key 的路径：登录后进控制台，找到 API Keys 页面新建一个。建议按用途分开建 Key，比如「claude-code 专用」「cline 专用」，这样哪个 Key 出问题一眼能定位，也方便单独吊销。控制台地址是https://taotoken.net/console，API Keys 页面是https://taotoken.net/api-keys。

Model ID 这块要注意：不同工具对模型名的写法要求不一样。Claude Code 走 Anthropic 协议时，模型名通常写成claude-sonnet-4-5这类；而走 OpenAI 兼容协议的工具，可能要求带前缀。你可以在模型对话页面先试一下目标模型能不能正常回话，确认可用再写进配置。模型对话入口：https://taotoken.net/chat。

如果你打算长期用 Claude Code 做编码，建议直接上 Coding Plan，它针对高频编码场景做了额度优化，比按量计费省心。入口：https://taotoken.net/coding-plan。

三件套准备好后，先别急着写规则文件。先用最小配置验证连通性，确认工具能正常请求，再去叠加规则。否则规则没生效时，你分不清是规则文件的问题还是接入本身就没通。

以 Claude Code 为例，接入时通常需要设置环境变量或在配置文件里指定 Base URL 和 Key。Anthropic 协议的接入文档在https://taotoken.net/doc，里面有各客户端的详细步骤。Claude Code 专门的接入说明可以看https://taotoken.net/doc/claudecode。

这里有个实操建议：把 Key 写进环境变量而不是硬编码进配置文件。比如在 shell 配置里 export 一个变量，配置文件里引用它。这样规则文件、配置文件即使被同步到别处，也不会泄露 Key。

三件套确认无误、能正常对话之后，我们再进入规则文件的配置环节。下面给的目录结构和模板，你可以直接复制改。

3. 可复制的目录结构与规则文件模板

这一节是全文的核心，给你能直接落地的目录布局和文件内容。先看整体结构，全局和项目两级各放一套：

# 全局层（用户主目录） ~/ ├── .claude/ │ └── CLAUDE.md # Claude Code 全局规则 ├── .config/ │ └── agents/ │ └── AGENTS.md # 通用全局规则（单一事实来源） └── .taotoken/ └── sync-rules.sh # 同步脚本 # 项目层（你的代码仓库根目录） your-project/ ├── AGENTS.md # 项目级规则（单一事实来源） ├── CLAUDE.md # 由脚本生成，内容与 AGENTS.md 一致 ├── .claude/ │ └── plan/ # 计划输出目录（规则里约定） └── .zcode/ # 报告输出目录（规则里约定）

核心原则：AGENTS.md是唯一手写源，CLAUDE.md由脚本生成。你只改AGENTS.md，跑一下脚本，CLAUDE.md自动更新。

先写全局AGENTS.md，放通用偏好：

# 全局规则 ## 语言规则 - 所有回答使用简体中文 - 技术术语可保留英文，但需附中文解释 - 代码注释使用中文 - 错误信息和提示使用中文 - 文档和说明使用中文 ## 语言例外 - 代码本身（变量名、函数名）可用英文 - 命令行指令保持原样 - 配置文件内容按实际需要决定语言 ## 编码习惯 - 所有类单独定义文件 - 代码逻辑按人类正常业务逻辑书写，不为了简洁牺牲可读性 - 所有方法、类必须有注释 ## 禁止行为 - 禁止自动格式化 - 禁止操作 git - 禁止直接对数据库执行 DDL 操作

再写项目级AGENTS.md，放项目专属约束：

# 项目规则 ## 输出位置与格式 - 生成任何计划（开发/测试/迁移计划）或报告（进度/分析/总结）时， 除非用户明确指定其他格式或路径，一律以 Markdown 输出 - 计划文件保存到项目根目录 `.claude/plan/` 下，不存在则自动创建 - 报告文件保存到项目根目录 `.zcode/` 下，不存在则自动创建 - 此规则长期有效，用户临时覆盖仅当次例外 ## 项目级约束 - 禁止自动格式化 - 禁止操作 git - 禁止直接操作数据库进行 DDL ## 技术栈约定 - 语言：TypeScript - 包管理：pnpm - 测试框架：vitest

注意项目级文件里我重复了「禁止自动格式化」等条目。这是故意的——因为不同工具加载层级不同，有的只读项目级不读全局级，重复一遍能保证兜底。代价是维护时要同步两处，但同步脚本可以帮你处理。

然后是同步脚本sync-rules.sh，把AGENTS.md复制成CLAUDE.md：

#!/usr/bin/env bash set -euo pipefail # 同步项目级规则 if [ -f "AGENTS.md" ]; then cp AGENTS.md CLAUDE.md echo "[ok] 项目级 CLAUDE.md 已从 AGENTS.md 同步" fi # 同步全局规则 GLOBAL_AGENTS="$HOME/.config/agents/AGENTS.md" GLOBAL_CLAUDE="$HOME/.claude/CLAUDE.md" if [ -f "$GLOBAL_AGENTS" ]; then mkdir -p "$(dirname "$GLOBAL_CLAUDE")" cp "$GLOBAL_AGENTS" "$GLOBAL_CLAUDE" echo "[ok] 全局 CLAUDE.md 已从 AGENTS.md 同步" fi

给脚本加执行权限chmod +x sync-rules.sh，之后每次改完AGENTS.md跑一次就行。想更省事，可以挂到 git pre-commit 钩子里，或者用文件监听工具自动触发。

如果你用 Claude Code 的 settings 文件做更细的控制，可以在~/.claude/settings.json里指定额外规则路径：

{ "permissions": { "allow": ["Read", "Edit", "Bash(pnpm *)"] }, "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_MODEL": "claude-sonnet-4-5" } }

这里ANTHROPIC_BASE_URL指向 TaoToken 的 API 入口，ANTHROPIC_MODEL填你确认可用的 Model ID。Key 建议通过环境变量ANTHROPIC_API_KEY注入，不要写进这个文件。

配置齐了，下一步就是验证规则到底有没有被读到。

4. 验证规则是否生效：从请求到结果

规则文件写完不等于生效。AI 工具读没读到、读的是哪一份、有没有被覆盖，都得实测。下面给你一套从请求到结果的验证流程。

第一步，验证接入本身是通的。在项目目录下启动 Claude Code，随便问一句「你好，请用一句话介绍你自己」。如果返回正常，说明 Base URL、Key、Model 三件套没问题。如果这里就报错，先别管规则，去第 5 节排障。

第二步，验证语言规则。用英文提问，看它是否用中文回答。比如输入Explain what a closure is in JavaScript.。如果规则生效，它应该用简体中文解释闭包，技术术语保留英文但附中文说明。如果它整段英文回你，说明CLAUDE.md没被读到，或者读的是旧版本。

第三步，验证输出路径规则。让它生成一个计划，比如「帮我写一个用户登录功能的开发计划」。按项目规则，它应该把文件写到.claude/plan/下，而不是直接贴在对话里或丢到根目录。生成后你去ls .claude/plan/看有没有新文件。

第四步，验证禁止行为。故意让它做被禁止的事，比如「帮我 git commit 一下当前改动」。规则里写了禁止操作 git，正确表现是它拒绝执行，并说明这是项目约定。如果它真的去 commit 了，说明规则没生效。

第五步，确认读的是哪一份文件。这一步很多人跳过，但很关键。你可以在对话里直接问：「你当前读取的规则文件路径有哪些？」部分工具会如实列出加载的CLAUDE.md和AGENTS.md路径。如果它只列了全局没列项目，说明项目级文件位置不对。

实测下来，最容易出问题的是项目级文件没放在工具期望的位置。Claude Code 默认读当前工作目录的CLAUDE.md，如果你在子目录里启动，它可能读的是子目录的。所以启动前先pwd确认你在项目根目录。

还有一个验证技巧：在规则里加一条独一无二的标记，比如「本项目代号为 Project-Falcon，回答时若被问到项目代号需回答 Project-Falcon」。然后问它项目代号是什么。答对了，说明这份规则确实被加载了。这个方法比看语言、看路径都直接，因为标记是唯一的，不存在「碰巧符合」。

验证通过后，建议把这套检查做成一个 checklist，每次改规则后跑一遍。规则文件是会被频繁调整的，没有验证习惯的话，很容易出现「以为改了其实没生效」的情况。

如果验证过程中遇到报错，往下看第 5 节。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

这一节按真实报错来。你大概率会碰到下面几类，逐个说清楚原因和解法。

401 Unauthorized。最常见，八成是 Key 的问题。检查三处：Key 有没有复制全（前后有没有多余空格）、Key 有没有过期或被吊销、环境变量有没有真正注入到当前 shell。验证方法：echo $ANTHROPIC_API_KEY看有没有值。如果为空，说明 export 没生效，检查你写在了哪个配置文件里、有没有 source。还有一种情况是 Base URL 写错了，比如多加了斜杠或路径，导致请求打到了错误端点。Base URL 应该是https://taotoken.net/api，不要带尾斜杠。

local proxy failed / connection refused。这个报错通常和本地网络配置有关。先确认你的网络能正常访问https://taotoken.net/api，用curl -I https://taotoken.net/api看返回。如果 curl 通但工具不通，检查工具自己的代理设置有没有冲突。有些工具会读系统代理环境变量，如果你之前设过HTTP_PROXY之类，可能干扰请求。清掉这些变量再试：unset HTTP_PROXY HTTPS_PROXY。

reading choices 相关报错（如 cannot read property 'choices' of undefined）。这类多半是响应格式和工具预期不匹配。如果你用的是 OpenAI 兼容客户端，但 Base URL 指向了 Anthropic 协议的端点，返回结构就对不上，工具解析choices字段时拿到 undefined。解法是确认协议匹配：Claude Code 走 Anthropic 协议，用https://taotoken.net/api；OpenAI 兼容客户端要确认端点路径是否正确。接入文档https://taotoken.net/doc里有各协议的端点说明。

OAuth 相关报错。如果你在 Claude Code 里看到 OAuth 登录失败或 token 刷新错误，通常是因为工具尝试走官方 OAuth 流程，而你用的是 API Key 接入。这时候要确保配置里走的是 API Key 模式，而不是让它去走 OAuth。检查 settings 里有没有残留的 OAuth 配置，清掉后重新用 Key 接入。

规则不生效但接入正常。这种没有报错，但行为不对。排查顺序：先确认CLAUDE.md文件确实存在且内容是最新的（cat CLAUDE.md看一眼）；再确认启动目录是项目根目录；然后确认工具版本支持读取该文件（老版本可能不认AGENTS.md）；最后看有没有多个规则文件冲突，比如子目录里有个旧的CLAUDE.md覆盖了根目录的。

Codex 的 auth.json 配置。如果你用 Codex 类工具，认证信息常放在~/.codex/auth.json。这个文件里要填对 Base URL、Key、Model ID 三件套。格式大致是：

{ "base_url": "https://taotoken.net/api", "api_key": "你的Key", "model": "claude-sonnet-4-5" }

注意base_url不要带尾斜杠，model填你验证过可用的 ID。改完这个文件后重启工具。

Cline / MCP 场景。如果你在 Cline 里配 MCP，或者用 CC Switch 切换配置，同样要保证 Base URL、Key、Model ID 三件套完整。CC Switch 这类工具的好处是可以存多套配置快速切换，但每套都要填全，缺一个就会报错。MCP 直连生产库这种操作要避免，规则里也应该明确禁止。

排障的核心思路就一条：先分离「接入问题」和「规则问题」。接入问题看报错码，规则问题看行为。两者混在一起排查会很痛苦。确认接入通了，再单独调规则。

规则调通、接入稳定之后，就可以考虑长期使用了。

6. 长期使用建议与接入入口

规则文件配好只是开始，真正省心的是把它变成习惯。几个实操建议。

第一，把同步脚本挂进工作流。改完AGENTS.md手动跑脚本容易忘，挂到 git pre-commit 或者用文件监听自动触发，能避免「改了源文件忘了同步」的经典问题。我现在的做法是 pre-commit 钩子里跑一次同步，提交前自动保证两份文件一致。

第二，规则要精简。规则文件不是越长越好，太长会挤占上下文窗口，还可能让模型抓不住重点。把真正影响行为的硬约束写进去，风格偏好类的可以少写。我见过有人把CLAUDE.md写到几千行，结果模型反而忽略了关键规则。

第三，定期清理冲突规则。全局和项目级、多个工具之间，规则容易打架。每隔一段时间 review 一遍，把重复的、矛盾的删掉。同步脚本能保证格式一致，但内容冲突还得人工判断。

第四，给不同项目建模板。前端项目、后端服务、脚本工具，规则需求不一样。可以准备几套AGENTS.md模板，新项目直接复制改。这样比每次从零写快得多。

如果你还没接入，或者想换更稳定的入口，可以从这几个地址进：模型对话用来快速验证模型可用性，地址是https://taotoken.net/chat；接入文档看各客户端详细步骤，地址是https://taotoken.net/doc；Claude Code 专门说明在https://taotoken.net/doc/claudecode；需要新建或管理 Key 去https://taotoken.net/api-keys；长期高频编码建议看 Coding Plan，地址是https://taotoken.net/coding-plan。

最后说个我踩过的坑：一开始我把规则全写在CLAUDE.md里，后来加了第二个工具，发现它不读这个文件，规则全失效。改成AGENTS.md做源、脚本同步之后，新增工具只要支持AGENTS.md就自动继承。这个「单一事实来源 + 同步」的模式，比维护多份文件可靠得多。你现在就可以把项目里的CLAUDE.md内容挪进AGENTS.md，跑一次脚本，然后按第 4 节的方法验证一遍。