CLAUDE.md 进阶：从 10 行到 607 行的配置艺术

607 行的 CLAUDE.md 是怎么回事

我的一个项目，CLAUDE.md 写到了 607 行。

这不是夸张的修辞。那是一个 Roam Research 图谱管理项目——通过 MCP 与 Roam 的 API 交互，自动化地创建页面、收集资源、整理笔记。听起来不复杂，但 Roam MCP 的 API 有大量隐性行为：roam_create_page 的 content 参数在特定情况下不可靠，格式解析器对缩进和标点有微妙的要求，X/Twitter 链接需要特殊的 Puppeteer + GraphQL API 拦截方案才能正确采集。

这些陷阱，如果不在 CLAUDE.md 里白纸黑字地记录，Claude 每次新会话都会踩一遍。我记录了 5 个已验证的 API 行为陷阱、一套精确到标点级别的格式规范、一个 4 步 URL 处理流程。607 行就是这么来的。

但另一方面，我也有只写了 10 行 CLAUDE.md 的项目——一个记账小工具，项目名加一句描述就够了。Claude 看一眼代码结构就能推断出它需要知道的一切。

这两个极端之间，藏着一个关于 CLAUDE.md 的核心问题：配置深度应该由什么决定？

CLAUDE.md 不只是"项目说明"

在讨论具体案例之前，需要先理解一个机制：CLAUDE.md 是每次会话全量加载的。

这意味着你写了多长，Claude 每次对话都会完整读取一遍。10 行的 CLAUDE.md 几乎不占上下文预算，607 行则会吃掉一大块。而且随着长度增加，Claude 对各条指令的遵循精度会下降——注意力被稀释了。

所以官方给了一个建议：目标控制在 200 行以内。这是一个均衡点——足够放下关键信息，又不至于让上下文预算失控。

但 200 行只是建议线，不是硬性限制。实际项目中的 CLAUDE.md 行数分布是这样的：

关键不在于"写多少行"，而在于"这些行是否都 earn their place"。接下来用三个真实案例来看这个梯度是怎么运作的。

案例 A：100 行的时间感知实验 App

这是一个 iOS 应用项目，使用 MVVM + Clean Architecture，CLAUDE.md 写了 104 行。

配置内容

核心 CLAUDE.md 包含三部分：

1. 架构说明：MVVM 模式 + Clean Architecture 的层级划分
2. 构建流程：开发命令、测试命令、部署注意事项
3. 跨 Session 约定：命名规范、文件组织规则

但真正有意思的是它的 Rules 配置。这个项目有 8 条 Rules，其中多条使用了 paths frontmatter 做条件加载：

Copy# .claude/rules/compose-ui.md
---
paths:
  - "app/src/main/java/**/ui/**"
  - "app/src/main/java/**/composable/**"
---
Compose UI 组件开发规范...

这意味着 Compose UI 规范只在 Claude 操作 UI 层文件时才加载，操作数据层时不会出现。这是一种精准的上下文管理——不是把所有规则都塞进 CLAUDE.md，而是让 Claude 在需要的时候才看到对应的规则。

适用场景

这种 100 行级别的配置适合有明确架构模式的正式项目——你需要 Claude 理解架构决策（"为什么用 MVVM 不用 MVI"），但项目本身没有太多反直觉的技术坑需要记录。配合 paths 条件加载的 Rules，总上下文负担远低于把所有规则写进 CLAUDE.md。

案例 B：239 行的 Knowledge System

这是一个知识管理系统，操作 Logseq 和 SQLite 数据库，CLAUDE.md 写了 239 行。

配置内容

比案例 A 多出来的部分主要是三块：

完整的 API Quick Reference——Claude 需要直接调用 HTTP API 与 Logseq 交互，调用方式、参数格式、返回结构都写在 CLAUDE.md 里。

安全规则体系——知识管理系统的操作有风险，误删页面可能丢失大量内容。所以有明确的操作红线：不允许批量删除、修改前必须验证页面存在、每次操作后验证结果。

三层知识架构定义——Meta-Methodology → Universal Patterns → Discipline Configuration。这种领域特定的概念体系，Claude 无法从代码推断，必须显式告知。

配套的扩展体系

这个项目还大量使用了 Skills 和 Commands：

• 2 个 Skills（knowledge-system-builder、logseq-api），各自引用 5-6 个 reference 文件
• 3 条 Rules（knowledge-logseq-safety、knowledge-quality-gate、knowledge-system-format）
• 5 个专用 Commands

Skills 的 reference 文件机制很关键——详细的 API 文档不是写在 CLAUDE.md 里的，而是作为 Skill 的 reference 资源按需加载。CLAUDE.md 里只放了最核心的快速参考。

适用场景

这种 200 行级别的配置适合领域知识驱动的项目——Claude 需要理解一套它训练数据中可能不包含的概念体系和操作规范。安全红线、API 精确规范、领域模型，这些都不是 Claude 能自行推断的。

案例 C：607 行的 Information Management

回到开头提到的那个 Roam Research 项目。607 行，是三个案例中最极端的。

为什么这么长

核心原因只有一个：API 行为不可预测。

Roam MCP 的 API 有大量文档没有覆盖的隐性行为。举一个已验证的陷阱：

roam_create_page 的 content 参数在页面已存在时会静默失败——不报错，不写入，返回的结果看起来像成功了。你必须先检查页面是否存在，如果存在则改用 roam_create_block 逐条写入。

这种陷阱不记录，Claude 每次新会话都会重新踩。我记录了 5 个类似的已验证陷阱，每个包含问题描述、复现条件、正确替代方案。

此外还有两块占了大量篇幅：精确到标点的格式规范（Roam block 对缩进和嵌套有严格要求，一个多余空格就可能导致层级错乱）和 URL 处理 4 步流程（其中 X/Twitter 链接需要 Puppeteer 拦截 GraphQL API 才能采集）。

一个警示

607 行是有代价的。每次会话启动，Claude 都要读完这 607 行。这不仅占用上下文预算，还增加了指令冲突的概率。

理想做法是拆分——API 陷阱放 Rules（行为约束）、格式规范放 Skill reference（按需加载）、URL 流程封装为专用 Skill，核心 CLAUDE.md 可缩到 150 行以内。

当时之所以没拆，是因为每发现一个坑就往 CLAUDE.md 里加一条，加着加着就到了 607 行。定期审视和重构 CLAUDE.md 的结构，和重构代码一样重要。

什么时候必须写长

从三个案例可以看出一个模式：CLAUDE.md 变长的根本原因不是"项目大"，而是Claude 无法自行推断的信息多。

具体来说，有四种场景会不可避免地推高配置行数：

1. API 行为不一致

外部 API 的隐性行为（Roam MCP 的 5 个陷阱、Docker 绕过 UFW 的端口映射行为、pnpm 的符号链接在 Docker COPY 中断裂）——这些不记录就会反复踩坑。

2. 多层架构

全栈应用的认证、支付、部署每一层都有独特的 caveats。拿课程站的 CLAUDE.md 举例，它有 27 条 Important Caveats，其中涉及 Prisma 7 的 adapter 模式、Next.js 16 的 proxy.ts、Better Auth 的 additionalFields、StatusLine 的 stdin JSON 结构——每条都源于实际开发中的调试经历。

3. 设计系统

色彩哲学、动画原则这类信息，如果只给规范不解释"为什么"，Claude 会在边界情况下做出错误推断。比如"首页不使用彩色"这条规则，如果不解释"因为整站视觉语言是 97% 纯灰度的静奢美学"，Claude 可能在某个角落偷偷引入一个彩色 badge。

4. 复杂部署

Docker + pnpm + 跨平台 + 特定云服务商的组合限制，每个交叉点都可能产生非直觉的行为。这类信息不在训练数据中，必须显式告知。

Persistence 三层体系：CLAUDE.md 不是唯一选择

当 CLAUDE.md 开始膨胀时，你需要知道还有两个可以分流的存储层级。Claude Code 的持久化信息管理由三层组成：

三层之间的分工逻辑是按稳定性排序：

• CLAUDE.md 放最稳定的真理——项目概述、技术栈、架构决策、构建命令。这些在项目生命周期中很少变动。
• Rules 放具体的行为指令——编码规范、验证规则、特定文件路径的约束。支持 paths frontmatter 做条件加载，只在操作匹配路径时才载入，不浪费上下文。
• Memory 放演化中的学习——Claude 在会话中发现的调试模式、用户纠正的偏好、项目进展追踪。这些由 Claude 自己写入，不进 git，纯机器本地。

判断信息该放哪一层，用这张决策表：

一个容易犯的错误是把所有东西都往 CLAUDE.md 里塞。当你发现 CLAUDE.md 超过 200 行时，先问自己：这些信息里，有多少可以拆到 Rules？有多少是 Claude 自己应该学会记在 Memory 里的？

超过 200 行怎么办：五种降级策略

如果项目确实需要大量配置信息（像课程站或 Roam 项目那样），可以用这五种策略来控制 CLAUDE.md 本体的长度：

1. Rules 分流

把可模块化的行为规则拆到 .claude/rules/*.md 中。比如课程站有 12 条独立的 Rules，涵盖 SubAgent 职责分离、Git Worktree 规范、架构师优先流水线等——这些如果全写在 CLAUDE.md 里，光 Rules 就要加 200 行。

2. paths 条件加载

给 Rules 文件加 paths frontmatter，让它们只在操作匹配文件时加载：

Copy# .claude/rules/homepage-design.md
---
paths:
  - "components/home/**"
  - "styles/**"
---
首页设计规范...

这样首页设计规范不会在你操作后端 API 路由时出现，精准节省上下文。

3. Skills reference 文件

把详细的 API 文档、操作指引封装为 Skill 的 reference 资源。Skill 的三级渐进加载机制意味着只有 Level 1（frontmatter）会在启动时加载，详细内容按需载入。

4. 子目录 CLAUDE.md

Monorepo 中，不同模块的配置放在各自子目录的 CLAUDE.md 中。子目录级 CLAUDE.md 是懒加载的——只有 Claude 操作到那个子目录时才读取。

5. @ 引用

用 @path/to/file 语法在 CLAUDE.md 中引用外部文件（最大 5 层递归），让核心文件保持精简：

Copy## 详细架构文档
@docs/architecture.md
 
## API 参考
@docs/api-reference.md

一个实操模板

如果你正准备给一个新项目写 CLAUDE.md，这是我建议的内容清单（按优先级排序）：

第一步：必写（适合所有项目，~20 行）

• 项目概述：一句话说清楚这是什么
• 开发命令：dev / build / test
• 技术栈：主要框架和语言

第二步：推荐写（正式项目，~60 行）

• 架构说明：目录结构和设计模式
• 构建/部署注意事项
• 关键 caveats：你踩过的坑

第三步：按需扩展（复杂项目，~120+ 行）

• API 规范和安全规则
• 设计原则和哲学（含"为什么"）
• 搭配 Rules + Skills 做分流

核心原则只有一条：每一行都要有"如果不写会怎样"的回答。如果 Claude 自己看代码就能推断，那不需要写；如果不写会导致 10 分钟的调试，那值得写。课程站的 27 条 Caveats 全都通过了这个测试。