Tips & Tricks · Parhum Khoshbakht

我们的 CLAUDE.md 只有 162 行。下面是里面留下了什么 — 以及我们砍掉了什么。

我们把项目根 CLAUDE.md 从 820 行精简到 162 行，没有损失任何护栏。诀窍是用一张技能触发表替代内联协议，把领域规则移到嵌套文件和路径作用域规则中。

您仓库里最贵但您不知道的那个文件

如果您使用 Claude Code，您项目根的 CLAUDE.md 就是您仓库中单一最贵的文件。不是因为磁盘空间 — 而是因为它的每一个字节都会在每次会话开始时加载进上下文，没有任何懒加载。技能是渐进式加载的。MCP 工具可以延迟加载。CLAUDE.md 就那样常驻在那里，永远加载、永远在征收您的窗口。

我们的曾经有 820 行。我们把它精简到 162 行，没有损失任何一条护栏。本文就是哪些被砍掉了、哪些留下了，以及完成此事的三种模式。

要点数字：820 → 162 行、约 8,000 → 约 1,200 token，以及在 200K 上下文窗口中占比从约 12% 降到约 0.75%。

CLAUDE.md 为什么值得自己一篇文章

在我们更宏观的 token 优化文章中，MCP Tool Search 是单一最大的杠杆。CLAUDE.md 是第二大的。关于大型 Claude Code 框架的研究报告称，优化后的根配置在基线开销上达到 54–62% 的减少，并记录了一个反例 — 一个 2,800 行的 CLAUDE.md — 浪费了大约每会话 62% 的 token。

机制就是原因。CLAUDE.md 在层级各级的内容都是无条件加载的：

  • 企业策略文件
  • 项目根 CLAUDE.md
  • 用户级 ~/.claude/CLAUDE.md
  • 项目本地覆盖文件
  • 通过 @path/to/file 语法导入的任何文件（递归最深 5 层）

Claude Code 在上下文方面所做的其他一切 — 渐进式技能加载、MCP Tool Search、subagent 隔离 — 都是为了规避「始终加载」税。CLAUDE.md 是您每一轮都无条件付费的那一项。

我们的「之前」：820 行，约占上下文 12%

我们最初的 CLAUDE.md 读起来像一本公司手册。它记录了我们使用的每一个技能、每一个发布门禁步骤、我们 WordPress Coding Standards 配置的每一个细微之处、React 组件的每一个命名约定、每一条管理员资源作用域规则。这确实是有用的参考材料。但它也会在每个会话被加载，包括那些与其中大部分内容毫不相关的会话。

下面是其中内容的粗略核算：

章节行数大约 token加载频率合理吗？
工作区地图与项目结构90900是 — 任何会话都需要的上下文
架构与技术栈60600是
隐私规则（不可妥协）40400是 — 关键不变量
每个技能的描述（30+ 项）1801,800否 — 各个技能按需加载
每个工作流的协议（详尽）2002,000否 — 仅在该工作流中需要
测试标准的细节1201,200否 — 仅与写测试的会话相关
发布门禁详走80800否 — 它属于发布技能里的内容
故障排查笔记50500否 — 很少需要

每个标了「否」的部分都在为「在一小部分会话中可用」而对所有会话征税。这大约是 6,300 token 的浪费 — 整整占据上下文窗口约 3% 的永久开销。

我们的「之后」：162 行，约 0.75%

新的 CLAUDE.md 用三种模式覆盖了同样的范围：触发表、嵌套 CLAUDE.md 文件，以及路径作用域规则。

模式 1：技能触发表

我们没有用一段段文字记录每个技能，而是用一个查找表替换了大约 30 个逐一描述：

## Skill triggers
| Trigger keywords | Skill | Domain |
|------------------|-------|--------|
| sprint, backlog, iteration | pm-sprint-plan | PM |
| story, acceptance criteria | pm-story-write | PM |
| deploy, release, ship | statnive-release | Dev |
| security, audit, CVE | sec-audit-remediate | Security |
| wireframe, mockup | ux-design | UX |
| benchmark, performance | wp-performance | WP |

关于大型框架的研究报告称这种模式约耗 800 token，而每技能冗长描述要 3,000+。Claude 的路由仍然能正常工作，因为触发关键词正是它所匹配的内容 — 我们以前写的那种长篇大论的「何时使用此技能、何时不使用」从未帮助过路由，只是填满了上下文。

所有那些详尽的「何时使用 / 何时不使用」内容都活在各自的 SKILL.md 文件里，仅在 Claude 路由到它们时才加载。触发表是索引；技能是章节。

模式 2：把领域规则放进嵌套 CLAUDE.md 文件

下面是大多数开发者错过的关键属性：子目录中的嵌套 CLAUDE.md 文件是惰性加载的。它们仅在 Claude 读取这些子树中的文件时进入上下文。

我们的仓库布局现在是这样：

statnive-workflow/
├── CLAUDE.md                    # 162 lines — global only
├── statnive/
│   ├── CLAUDE.md                # PHP / WordPress plugin conventions
│   ├── src/
│   └── tests/
├── statnive-website/
│   └── CLAUDE.md                # Astro / MDX / frontend conventions
└── jaan-to/
    └── CLAUDE.md                # AI framework conventions

当我们为插件写 PHP 时，statnive/CLAUDE.md 会自动加载，并带入我们的 WordPress Coding Standards 笔记、$wpdb->prepare() 强制规则以及管理员资源作用域规则。当我们写 MDX 博客内容时，statnive-website/CLAUDE.md 会带着 Astro 约定和文风笔记加载。两者互不干扰。

这一模式从根中砍掉了大约 2,200 token 的「仅有时相关」的内容。

模式 3：.claude/rules/ 中的路径作用域规则

第三种机制是 .claude/rules/ — 带 YAML 前置元数据的规则文件，可以声明它们应用于哪些路径：

---
paths: ["statnive-website/src/**/*.tsx", "statnive-website/src/**/*.astro"]
---
Use Tailwind utilities scoped under `#statnive-app`. Never import the default
Tailwind bundle — it restyles the WordPress admin chrome.

带 paths: 字段的规则有条件加载 — 仅当 Claude 在处理匹配文件时才加载。没有 paths: 字段的规则无条件加载，因此我们让这一类规则保持很少（隐私规则、安全规则、提交约定）。

我们将大约 1,800 token 的框架特定约定从根 CLAUDE.md 移到了 .claude/rules/ 下的路径作用域规则中。它们在相关时仍会可靠地生效，在不相关时则零成本。

我们移除的反模式：@-imports

我们最初的 CLAUDE.md 有三个 @-imports：

@jaan-to/docs/best-practices.md
@jaan-to/context/tech.md
@jaan-to/outputs/ROADMAP.md

它看起来很整洁。它是一个陷阱。@ 语法在每次会话都会递归加载每个目标文件的完整内容，最深 5 层。仅这三个 import 就大约增加了 6,000 token 的永久开销，而模型可能每 20 次会话才需要一次这些内容。

我们把每一个都换成了一个指针：

For architectural context see `jaan-to/context/tech.md`.
For the current roadmap see `jaan-to/outputs/ROADMAP.md`.

Claude 在它实际需要时会读这些路径 — 通过 Read 工具，按需加载。零基线成本，同样的实际效果。

还留在根文件里的内容

砍完之后，162 行的根 CLAUDE.md 包含恰好这些：

章节行数为什么留下
产品哲学（来自研究的 8 条原则）28影响每一个决策；必须影响所有会话
工作区地图18一目了然的方向感，对任何会话都加载
隐私规则（不可妥协）16关键不变量 — Cookie、原始 IP、盐值、SHA-256
管理员资源作用域规则22之前曾咬过我们，且适用面广
提交策略（禁止 co-authored-by 尾注）8全局 git 约定
/simplify 工作流规则18我们质量门禁的强制执行
技能触发表32替代约 30 节冗长的逐技能描述
关键路径（指针，而非 import）20对文档的一行引用

其他一切要么进入嵌套 CLAUDE.md、路径作用域规则，要么进入各自的技能正文。

我们没有优化的部分

诚实的注意事项，与本系列其他文章一致：

  • 用户级 ~/.claude/CLAUDE.md 不在我们掌控之内。 我们的工程师每个人都有自己的全局配置，它们叠加在项目文件之上。研究指出这是一个常见的隐藏开销来源 — 一个全局 CLAUDE.md 写着「记得在提交前跑测试」，叠加在项目层正在做同样事情的工作流之上，会消耗 token 而没有增加信号。我们请团队成员审计自己的。您的可能也值得看看。
  • 我们还没有给根 CLAUDE.md 大小做 CI 门禁。 研究建议如果根 CLAUDE.md 加任何 @-import 超过约 2,500 token 就让 PR 失败。我们目前用 /context 抽查来强制。CI 门禁在路线图上。
  • IMPORTANT 和 YOU MUST 标记很诱人。 Anthropic 内部会把 CLAUDE.md 文件过他们的 prompt improver，并对关键规则使用强调标记。我们克制使用 — 每一个都是永久开销，所以我们只把它们留给隐私规则（无 Cookie、无原始 IP）和提交策略（无 co-authored-by 尾注）。

不能跳过的测量步骤

如果您在审计自己的 CLAUDE.md，最重要的一个命令是 /context。在全新会话最开始就跑它，先于任何提示。它会按来源拆分您的上下文使用：系统提示、工具、记忆（即 CLAUDE.md）、技能元数据，以及 MCP 工具 schema。

我们对 200K 窗口会话设的目标值：

来源目标硬上限
根 CLAUDE.md + 无作用域规则≤ 1,500 token2,500
技能元数据≤ 2,500 token5,000
MCP 工具 schema（含 Tool Search）≤ 3,000 token8,000
钩子标准输出（SessionStart、UserPromptSubmit）0 token每钩子 300

如果您的 /context 中任何一项超出这些目标超过约 50%，您面临的是和我们当时一样的问题。修复办法就是上面三种模式加上 MCP Tool Search。

这件事对运行 Statnive 的人为什么重要

我们的 CLAUDE.md 在 Statnive 在 GitHub 上的仓库中是公开的 — 与我们测试流水线公开是同一个理由。一份精炼的根配置意味着更快的会话、更便宜的运行，以及一个真正读到要紧内容、而不是在「随时可用、很少需要」的参考材料中被淹没的模型。这种效率最终复合成我们用户真正在乎的：一个频繁交付、且保持在 5KB tracker 预算以下的插件。

试试 Statnive

由一支把 token 预算与性能预算同等重视的团队打造的隐私优先 WordPress 分析。从 WordPress.org 免费安装 Statnive — 您的数据留在您的服务器上，我们的工程实践都在 GitHub 上供任何人审计。

免费获取 Statnive