1. 为什么 Claude Code 老是不按 CLAUDE.md 执行你大概率遇到过这个场景CLAUDE.md 里明明写了「用 JUnit 4不要用 JUnit 5」结果 Claude Code 还是给你生成了ExtendWith的测试类你写了「提交信息用type(scope): subject格式」它照样给你来一句update code。于是你开始怀疑是不是模型不行或者是不是 CLAUDE.md 根本没被读到。先别急着继续往 CLAUDE.md 里堆内容。我见过一个 482 行的 CLAUDE.md从项目介绍、目录结构、编码规范、Git 提交格式一路写到部署流程恨不得把公司 wiki 全搬进去。结果呢真正需要它记住的构建命令、违反默认习惯的编码规范、.claude/rules里的 globs 规则全被淹没在信息噪声里。Claude Code 每次启动都要把这 482 行注入 contexttoken 预算被大量低价值内容吃掉关键指令反而被稀释。更隐蔽的问题是加载层级。Claude Code 会沿目录树向上递归收集所有 CLAUDE.md根目录一份、子目录一份如果两边写了矛盾的指令根目录说用 ESLint子目录说用 Biome它会优先听离当前工作目录更近的那层。很多人根本没意识到自己项目里存在多份 CLAUDE.md自然也就查不出为什么「我写的规则没生效」。所以这篇的排查思路分两步走先把模型通道配通确认 Claude Code 真的在按你配置的通道请求再按四层加载顺序把当前加载的 CLAUDE.md 列出来逐条核对.claude/rules的 globs 有没有命中测试文件。通道不通后面所有排查都是空中楼阁。2. 先把模型通道配通TaoToken 的 Key 与 Base URL在排查 CLAUDE.md 之前得先保证 Claude Code 的请求确实发出去了、确实回来了。这一步用 TaoToken 来做通道配置。需要说清楚的是TaoToken 只提供 Key 和 Base URL它不参与读写你的 CLAUDE.md也不碰你的项目文件。你的共识协议文件还是老老实实躺在项目目录里TaoToken 负责的是模型请求这一段链路。注册入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册完进控制台创建 API Key地址是https://taotoken.net/console创建 Key 的页面https://taotoken.net/api-keys拿到 Key 之后Base URL 填这个注意三个「不要」https://taotoken.net/api不要填官网地址不要在后面加/v1不要带任何 UTM 参数。Base URL 就是纯粹的https://taotoken.net/api多一个字符都可能让请求 404。这一点我在配置时踩过加了/v1之后一直报路径错误去掉就通了。如果你用的是 Claude Code 原生命令行配置方式是在环境变量或配置文件里指定ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。如果你用 CC Switch 这类切换工具就在对应通道里填 Base URL 和 Key。两种方式选一种即可核心就是让 Claude Code 的请求打到https://taotoken.net/api。3. 可复制配置Claude Code 与 CC Switch 两种接法3.1 命令行环境变量方式最直接的方式是设置环境变量。在~/.zshrc或~/.bashrc里加export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key保存后source ~/.zshrc让它生效。然后验证一下变量有没有读进去echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY | head -c 8第二条命令只打印 Key 的前 8 位避免完整 Key 出现在终端历史里。确认输出是https://taotoken.net/api和你的 Key 前缀就说明环境变量没问题。3.2 CC Switch 配置方式如果你用 CC Switch 管理多个通道新建一个通道字段这样填字段填写内容名称TaoToken随便起Base URLhttps://taotoken.net/apiAPI Key控制台创建的 Key模型按需选择默认即可保存后切换到该通道。CC Switch 的好处是可以在多个通道之间快速切换排查问题时能立刻确认「是不是通道本身的问题」。3.3 项目级配置可选如果你不想污染全局环境变量可以在项目根目录建.claude/settings.json把通道配置写进去。但要注意这个文件如果提交到仓库Key 就泄露了所以务必加进.gitignore。更稳妥的做法还是用环境变量或 CC Switch。配置完成后Claude Code 的请求链路就通了。接下来才是真正的排查CLAUDE.md 到底加载了哪几层。4. 验证请求与加载层级让 Claude Code 自报家门4.1 先确认通道通了在项目目录下启动 Claude Code随便问一句你好请回复「通道正常」四个字。如果它能正常回复说明 Base URL 和 Key 都配对了。如果报 401检查 Key 有没有复制完整如果报 404检查 Base URL 是不是多加了/v1或 UTM 参数如果超时检查网络和 Base URL 拼写。4.2 让 Claude Code 列出当前加载的 CLAUDE.md通道通了之后直接在对话里问请列出你当前加载的所有 CLAUDE.md 文件路径以及每个文件的内容摘要。Claude Code 会把沿目录树向上收集到的所有 CLAUDE.md 列出来。按四层加载顺序你应该能看到类似这样的结构企业策略层/etc/claude/CLAUDE.md个人开发者通常没有 项目级/your-project/CLAUDE.md 用户级~/.claude/CLAUDE.md 本地覆盖/your-project/.claude/CLAUDE.md如果某一层你明明写了文件却没出现在列表里先检查路径对不对。项目级必须在项目根目录本地覆盖必须在.claude/子目录下用户级必须在~/.claude/下。路径错一层文件就不会被加载。4.3 检查 .claude/rules 的 globs 是否命中.claude/rules/下的规则文件靠 frontmatter 里的globs字段决定生效范围。比如你写了testing.md--- description: 测试文件编码规范 globs: [**/test/**/*.java, **/*Test.java] --- - 测试方法命名should_预期行为_when_前置条件 - 每个测试方法只测一件事 - 断言用 assertThat()不要用 assertEquals()验证方法是让 Claude Code 去编辑一个匹配 glob 的测试文件然后问它你刚才编辑测试文件时加载了哪些 .claude/rules 下的规则如果它说没加载到testing.md大概率是 globs 写错了。常见错误是把**/test/**/*.java写成test/**/*.java少了开头的**/导致只在根目录的 test 下生效子模块的 test 目录匹配不到。另一个坑是 globs 为空或没写这种情况下规则会始终生效等价于写在 CLAUDE.md 里反而失去了精准投放的意义。4.4 用「第二次纠正」验证共识协议这是判断 CLAUDE.md 是否真正生效的终极方法。故意让 Claude Code 犯一个 CLAUDE.md 里已经写明的错误比如你写了「用 JUnit 4」就让它生成一个测试类。如果它用了 JUnit 5你纠正一次如果下次新对话它又用 JUnit 5说明 CLAUDE.md 里的这条规则没生效。按原文的铁律第二次纠正同一个问题时立刻写进 CLAUDE.md 或.claude/rules/。如果写进去了还是犯那就是加载层级或 globs 的问题回到 4.2 和 4.3 继续查。5. 本篇常见错排查5.1 Base URL 填错导致请求失败最常见的三个错误填了官网地址而不是https://taotoken.net/api在末尾加了/v1复制时带上了 UTM 参数。这三个都会让请求打到错误的路径。排查方法是在终端里直接 curl 一下curl -s -o /dev/null -w %{http_code} https://taotoken.net/api返回 401 或 403 是正常的因为没带 Key返回 404 说明路径不对。如果返回 404逐字符核对 Base URL。5.2 CLAUDE.md 路径不对导致没加载项目级 CLAUDE.md 必须在项目根目录和.git同级。如果你放在src/CLAUDE.md它只会在 Claude Code 工作目录进入src/时才被加载。本地覆盖必须在.claude/CLAUDE.md注意是.claude目录下的CLAUDE.md不是.claude/CLAUDE.md/这种错误嵌套。5.3 globs 写错导致规则不命中globs是数组每个元素是一个 glob 模式。常见错误用了单引号包裹导致 YAML 解析异常模式里用了 Windows 反斜杠忘了**/前缀导致只匹配根目录。建议统一用双引号路径分隔符统一用/需要匹配任意层级时以**/开头。5.4 多份 CLAUDE.md 指令矛盾根目录和子目录的 CLAUDE.md 如果写了矛盾指令Claude Code 优先听离当前工作目录更近的那层。排查方法是问它「当前工作目录下哪份 CLAUDE.md 的优先级最高」然后检查那份文件里有没有和根目录冲突的规则。如果只是「不同」而不是「矛盾」两者会合并生效这种情况反而容易造成规则叠加后的意外行为。5.5 通道通了但 CLAUDE.md 还是没生效如果 4.1 确认通道正常4.2 确认文件被加载4.3 确认 globs 命中但规则还是不执行那问题可能出在指令本身有歧义。比如「代码要写得简洁」这种指令Claude 无法判断什么叫简洁。改成「方法体不超过 30 行超过就提取子方法」这种可执行、可验证的指令效果会立刻不一样。6. 配通通道后再谈共识协议排查 CLAUDE.md 不生效顺序不能反。先确认模型通道通了——用 TaoToken 拿到 KeyBase URL 填https://taotoken.net/api在 Claude Code 或 CC Switch 里配好问一句「通道正常」确认请求能回来。然后按四层加载顺序让 Claude Code 列出当前加载的 CLAUDE.md检查.claude/rules的 globs 有没有命中测试文件最后用「第二次纠正同一问题就写进 CLAUDE.md」来验证共识协议是否真正生效。通道配置相关的入口整理在这里按需取用注册与 Keyhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 控制台https://taotoken.net/console API Keyshttps://taotoken.net/api-keys 接入文档https://taotoken.net/doc 模型对话https://taotoken.net/models Coding Planhttps://taotoken.net/coding-plan如果你长期用 Claude Code 做编码和 Agent 任务Coding Plan 那条通道更适合高频调用如果只是临时验证模型行为模型对话页面就够用。通道配通只是第一步真正让 Agent 按你的共识协议执行还得回到 CLAUDE.md 本身——只写它猜不到的东西其余的全删。
1. 为什么 Claude Code 老是不按 CLAUDE.md 执行你大概率遇到过这个场景CLAUDE.md 里明明写了「用 JUnit 4不要用 JUnit 5」结果 Claude Code 还是给你生成了ExtendWith的测试类你写了「提交信息用type(scope): subject格式」它照样给你来一句update code。于是你开始怀疑是不是模型不行或者是不是 CLAUDE.md 根本没被读到。先别急着继续往 CLAUDE.md 里堆内容。我见过一个 482 行的 CLAUDE.md从项目介绍、目录结构、编码规范、Git 提交格式一路写到部署流程恨不得把公司 wiki 全搬进去。结果呢真正需要它记住的构建命令、违反默认习惯的编码规范、.claude/rules里的 globs 规则全被淹没在信息噪声里。Claude Code 每次启动都要把这 482 行注入 contexttoken 预算被大量低价值内容吃掉关键指令反而被稀释。更隐蔽的问题是加载层级。Claude Code 会沿目录树向上递归收集所有 CLAUDE.md根目录一份、子目录一份如果两边写了矛盾的指令根目录说用 ESLint子目录说用 Biome它会优先听离当前工作目录更近的那层。很多人根本没意识到自己项目里存在多份 CLAUDE.md自然也就查不出为什么「我写的规则没生效」。所以这篇的排查思路分两步走先把模型通道配通确认 Claude Code 真的在按你配置的通道请求再按四层加载顺序把当前加载的 CLAUDE.md 列出来逐条核对.claude/rules的 globs 有没有命中测试文件。通道不通后面所有排查都是空中楼阁。2. 先把模型通道配通TaoToken 的 Key 与 Base URL在排查 CLAUDE.md 之前得先保证 Claude Code 的请求确实发出去了、确实回来了。这一步用 TaoToken 来做通道配置。需要说清楚的是TaoToken 只提供 Key 和 Base URL它不参与读写你的 CLAUDE.md也不碰你的项目文件。你的共识协议文件还是老老实实躺在项目目录里TaoToken 负责的是模型请求这一段链路。注册入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册完进控制台创建 API Key地址是https://taotoken.net/console创建 Key 的页面https://taotoken.net/api-keys拿到 Key 之后Base URL 填这个注意三个「不要」https://taotoken.net/api不要填官网地址不要在后面加/v1不要带任何 UTM 参数。Base URL 就是纯粹的https://taotoken.net/api多一个字符都可能让请求 404。这一点我在配置时踩过加了/v1之后一直报路径错误去掉就通了。如果你用的是 Claude Code 原生命令行配置方式是在环境变量或配置文件里指定ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。如果你用 CC Switch 这类切换工具就在对应通道里填 Base URL 和 Key。两种方式选一种即可核心就是让 Claude Code 的请求打到https://taotoken.net/api。3. 可复制配置Claude Code 与 CC Switch 两种接法3.1 命令行环境变量方式最直接的方式是设置环境变量。在~/.zshrc或~/.bashrc里加export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key保存后source ~/.zshrc让它生效。然后验证一下变量有没有读进去echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY | head -c 8第二条命令只打印 Key 的前 8 位避免完整 Key 出现在终端历史里。确认输出是https://taotoken.net/api和你的 Key 前缀就说明环境变量没问题。3.2 CC Switch 配置方式如果你用 CC Switch 管理多个通道新建一个通道字段这样填字段填写内容名称TaoToken随便起Base URLhttps://taotoken.net/apiAPI Key控制台创建的 Key模型按需选择默认即可保存后切换到该通道。CC Switch 的好处是可以在多个通道之间快速切换排查问题时能立刻确认「是不是通道本身的问题」。3.3 项目级配置可选如果你不想污染全局环境变量可以在项目根目录建.claude/settings.json把通道配置写进去。但要注意这个文件如果提交到仓库Key 就泄露了所以务必加进.gitignore。更稳妥的做法还是用环境变量或 CC Switch。配置完成后Claude Code 的请求链路就通了。接下来才是真正的排查CLAUDE.md 到底加载了哪几层。4. 验证请求与加载层级让 Claude Code 自报家门4.1 先确认通道通了在项目目录下启动 Claude Code随便问一句你好请回复「通道正常」四个字。如果它能正常回复说明 Base URL 和 Key 都配对了。如果报 401检查 Key 有没有复制完整如果报 404检查 Base URL 是不是多加了/v1或 UTM 参数如果超时检查网络和 Base URL 拼写。4.2 让 Claude Code 列出当前加载的 CLAUDE.md通道通了之后直接在对话里问请列出你当前加载的所有 CLAUDE.md 文件路径以及每个文件的内容摘要。Claude Code 会把沿目录树向上收集到的所有 CLAUDE.md 列出来。按四层加载顺序你应该能看到类似这样的结构企业策略层/etc/claude/CLAUDE.md个人开发者通常没有 项目级/your-project/CLAUDE.md 用户级~/.claude/CLAUDE.md 本地覆盖/your-project/.claude/CLAUDE.md如果某一层你明明写了文件却没出现在列表里先检查路径对不对。项目级必须在项目根目录本地覆盖必须在.claude/子目录下用户级必须在~/.claude/下。路径错一层文件就不会被加载。4.3 检查 .claude/rules 的 globs 是否命中.claude/rules/下的规则文件靠 frontmatter 里的globs字段决定生效范围。比如你写了testing.md--- description: 测试文件编码规范 globs: [**/test/**/*.java, **/*Test.java] --- - 测试方法命名should_预期行为_when_前置条件 - 每个测试方法只测一件事 - 断言用 assertThat()不要用 assertEquals()验证方法是让 Claude Code 去编辑一个匹配 glob 的测试文件然后问它你刚才编辑测试文件时加载了哪些 .claude/rules 下的规则如果它说没加载到testing.md大概率是 globs 写错了。常见错误是把**/test/**/*.java写成test/**/*.java少了开头的**/导致只在根目录的 test 下生效子模块的 test 目录匹配不到。另一个坑是 globs 为空或没写这种情况下规则会始终生效等价于写在 CLAUDE.md 里反而失去了精准投放的意义。4.4 用「第二次纠正」验证共识协议这是判断 CLAUDE.md 是否真正生效的终极方法。故意让 Claude Code 犯一个 CLAUDE.md 里已经写明的错误比如你写了「用 JUnit 4」就让它生成一个测试类。如果它用了 JUnit 5你纠正一次如果下次新对话它又用 JUnit 5说明 CLAUDE.md 里的这条规则没生效。按原文的铁律第二次纠正同一个问题时立刻写进 CLAUDE.md 或.claude/rules/。如果写进去了还是犯那就是加载层级或 globs 的问题回到 4.2 和 4.3 继续查。5. 本篇常见错排查5.1 Base URL 填错导致请求失败最常见的三个错误填了官网地址而不是https://taotoken.net/api在末尾加了/v1复制时带上了 UTM 参数。这三个都会让请求打到错误的路径。排查方法是在终端里直接 curl 一下curl -s -o /dev/null -w %{http_code} https://taotoken.net/api返回 401 或 403 是正常的因为没带 Key返回 404 说明路径不对。如果返回 404逐字符核对 Base URL。5.2 CLAUDE.md 路径不对导致没加载项目级 CLAUDE.md 必须在项目根目录和.git同级。如果你放在src/CLAUDE.md它只会在 Claude Code 工作目录进入src/时才被加载。本地覆盖必须在.claude/CLAUDE.md注意是.claude目录下的CLAUDE.md不是.claude/CLAUDE.md/这种错误嵌套。5.3 globs 写错导致规则不命中globs是数组每个元素是一个 glob 模式。常见错误用了单引号包裹导致 YAML 解析异常模式里用了 Windows 反斜杠忘了**/前缀导致只匹配根目录。建议统一用双引号路径分隔符统一用/需要匹配任意层级时以**/开头。5.4 多份 CLAUDE.md 指令矛盾根目录和子目录的 CLAUDE.md 如果写了矛盾指令Claude Code 优先听离当前工作目录更近的那层。排查方法是问它「当前工作目录下哪份 CLAUDE.md 的优先级最高」然后检查那份文件里有没有和根目录冲突的规则。如果只是「不同」而不是「矛盾」两者会合并生效这种情况反而容易造成规则叠加后的意外行为。5.5 通道通了但 CLAUDE.md 还是没生效如果 4.1 确认通道正常4.2 确认文件被加载4.3 确认 globs 命中但规则还是不执行那问题可能出在指令本身有歧义。比如「代码要写得简洁」这种指令Claude 无法判断什么叫简洁。改成「方法体不超过 30 行超过就提取子方法」这种可执行、可验证的指令效果会立刻不一样。6. 配通通道后再谈共识协议排查 CLAUDE.md 不生效顺序不能反。先确认模型通道通了——用 TaoToken 拿到 KeyBase URL 填https://taotoken.net/api在 Claude Code 或 CC Switch 里配好问一句「通道正常」确认请求能回来。然后按四层加载顺序让 Claude Code 列出当前加载的 CLAUDE.md检查.claude/rules的 globs 有没有命中测试文件最后用「第二次纠正同一问题就写进 CLAUDE.md」来验证共识协议是否真正生效。通道配置相关的入口整理在这里按需取用注册与 Keyhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 控制台https://taotoken.net/console API Keyshttps://taotoken.net/api-keys 接入文档https://taotoken.net/doc 模型对话https://taotoken.net/models Coding Planhttps://taotoken.net/coding-plan如果你长期用 Claude Code 做编码和 Agent 任务Coding Plan 那条通道更适合高频调用如果只是临时验证模型行为模型对话页面就够用。通道配通只是第一步真正让 Agent 按你的共识协议执行还得回到 CLAUDE.md 本身——只写它猜不到的东西其余的全删。
