【CLAUDE.md优化】从一锅炖到分层治理：我的 CLAUDE.md 重构实录

网上教你写 CLAUDE.md 的文章不少该放什么、格式怎么写、层级怎么分讲得都对。但看完你还是不知道一件事**我的 CLAUDE.md 到底什么时候该拆、怎么拆、拆到什么程度。**这个问题没有标准答案因为 CLAUDE.md 不是配置文件它本质上是你和 AI 的协作界面。什么时候失效取决于你的项目形态、工作流以及你什么时候开始感觉Claude 好像越来越“听不懂我”了。所以这篇不是教程。这是一个真实项目的踩坑复盘。​ 我用 Claude Code 从零写了一个数据集分析工具使用FastAPI Vue 3前后端分离40 多个 API 端点项目几乎全程 AI 协作完成。在这过程中 CLAUDE.md 从 0 行涨到 200 多行token 越烧越多Claude 的表现反而越来越差。直到我花了一个下午重构配置体系效果立刻改变。​ 下面是完整经过​ 这篇文章讲的就是这条线从零配置的对话模式到什么都往里塞的膨胀期再到一个下午的重构最终形成分层治理的配置体系。每个阶段都是真实踩过来的。一、新手阶段对话即配置​ 刚开始用 Claude Code 时我的工作方式非常原始想到什么说什么。“这个项目用 FastAPI端口9501。” “前端 Vue3 TS用 pnpm。” “analysis 层不要依赖 FastAPI。”​ 问题很快出现每开一个新会话都要重新解释项目背景。​ Claude 没有跨会话记忆上一次聊得再深入下一次依然从零开始。​ 后来我发现了 CLAUDE.md项目根目录放一个 Markdown 文件Claude Code 启动时自动读取。于是我开始往里面塞东西说一句塞一条踩一个坑加一条规则。​ 这个阶段的 CLAUDE.md本质上就是对话记录的沉淀。没有结构没有分类想到什么写什么。​ 新手阶段的模式很直觉对话里说过的规矩一条条搬到 CLAUDE.md 里。没有规划没有分类纯粹是怕下次又忘了的本能反应。这个阶段完全没问题项目小的时候一个文件装得下。二、膨胀阶段什么都往里塞​ 随着项目推进CLAUDE.md 开始失控被我用成了万能收纳箱。​ 数据分析应用的架构不算复杂但模块不少后端有analysis/、api/、loaders/、report/四个核心模块前端有组件、路由、状态管理、国际化中间还有 Session 机制、CORS 配置、特征工程的累积模式……每次 Claude 犯错我就往 CLAUDE.md 里加一条Claude 在 analysis 层 import 了 Pydantic加一条analysis/ 零框架依赖只用 pandas/numpy/标准库。Claude 把 NaN 序列化搞炸了加一条NaN/Inf 处理留给 api 层analysis 层不做 JSON 序列化。Claude 在特征工程里搞混了累积模式的逻辑加一大段savefalse 只预览savetrue 才写入 session注意先捕获 response 再清缓存……前端 Claude 用了硬编码的 Tailwind 颜色加一条用 main.css 定义的工具类不要硬编码。Claude 又忘了 API 端点的路径把 40 多个端点的完整列表贴进去。你能想象这个文件最后变成什么样技术栈、构建命令、架构图、编码规范、API 参考、版本记录、踩坑备忘、个人偏好……全塞在一个文件里。问题不只是看着乱有效上下文逐渐被污染。Claude Code 每次启动时会把 CLAUDE.md 全文注入上下文这意味着token 消耗飙升。每一轮对话都要为这个巨型文件买单还没开始干活几千 token 就没了。信噪比下降。当你告诉 Claude “这 40 个 API 端点的路径是这样的”它在处理一个前端 CSS 问题时也会把这些信息加载进来。无关信息越多Claude 越容易分心。维护成本高。改了一个端点要记得去 CLAUDE.md 里同步。忘了同步Claude 拿着过时的信息干活结果更糟糕。本质上我把 CLAUDE.md 当成了垃圾桶什么都往里扔从不整理。​ 左边是项目初期的 CLAUDE.md几行关键信息Claude 读得轻松、理解得准确。右边是半年迭代后的样子API 列表、编码规范、缓存机制、CSS 工具类全塞在一起Claude 每次启动都要消化这些信息大部分跟当前任务无关。token 在涨效果在降。三、转折点一个下午的重构​ 触发重构的直接原因很具体我发现让 Claude 改一个前端组件的样式它读完 CLAUDE.md 后花了大量 token 去理解后端 API 的端点列表和特征工程的缓存机制。这些信息跟当前任务毫无关系。​ 我决定动手拆。原则很简单谁的规矩放到谁家门口。3.1 第一刀子目录 CLAUDE.md​ Claude Code 有一个很多人不知道的特性子目录也可以放 CLAUDE.md且只在 Claude 操作该目录时才加载。​ 这正好解决了前端任务加载后端规范的问题。我把模块级别的规范从主文件中拆出来分成三份(1) 数据分析部分​src/intodata/analysis/CLAUDE.md分析层的护城河## 核心原则 - **零框架依赖**只用 pandas / numpy / 标准库不引入 FastAPI、Pydantic 等 - **纯函数设计**输入 DataFrame → 返回 dataclass / dict / DataFrame - **可独立使用**所有函数可在 Jupyter notebook 中直接调用 ## 编码约定 - 函数返回复杂结构时使用 dataclass不用裸 dict - 不在 analysis 层做 JSON 序列化NaN/Inf 处理留给 api 层 - 新增分析功能先写 analysis 纯函数再写 api 路由包装(2) API层​src/intodata/api/CLAUDE.mdAPI 层的操作手册## Session 模型 - SessionStore内存 dict asyncio.LockUUID cookie 标识2h TTL 自动清理 - SessionData 包含 dataset 和 image_dataset**互斥** ## 端点设计约定 - savefalse只返回预览数据不修改 session - savetrue覆盖 session df → 清除 feature 缓存 → 记录 log → 返回新 meta - **注意**save 时先捕获 response 数据再调 clear_feature_caches()(3) 前端​frontend/CLAUDE.md前端的设计系统## CSS 设计系统 使用 main.css 中定义的工具类**不要硬编码 Tailwind 颜色** - .loading-state — 加载状态 - .status-ok / .status-warn / .status-danger — 语义状态颜色 - .section-title — 渐变下划线章节标题 ## 国际化 - 所有用户可见文本必须用 $t(key) - 新增功能需同步添加 en.ts 和 zh.ts​ 拆完之后Claude 改前端样式时只会读到 CSS 工具类和组件约定改后端 API 时只会看到 Session 模型和端点设计模式。每次对话的上下文里只有相关信息没有噪声。​ 项目根目录的 CLAUDE.md 常驻加载只放全局信息三个子目录各自维护模块级规范Claude 操作哪个目录就加载哪份。改前端时不会看到后端的 Session 机制改 analysis 时不会被前端的 CSS 工具类干扰。3.2 第二刀Custom Commands​ 拆完子目录 CLAUDE.md主文件瘦了很多但还有一块东西很碍眼40 多个 API 端点的完整列表。​ 这个列表有用但不是每次都用。只有在加新端点或排查路由问题时才需要。把它放在 CLAUDE.md 里每次启动都加载浪费。​ 这时候我发现了 Custom Commands。(1) 什么是Custom Commands​ Custom Commands 是 Claude Code 提供的一种轻量级扩展机制在.claude/commands/目录下放一个 Markdown 文件就注册了一个斜杠命令。用的时候手动调用不用的时候不占上下文。.claude/ └── commands/ └── api-ref.md ← 输入 /api-ref 即可调用​ 我把 API 端点列表从 CLAUDE.md 里搬到了api-ref.md# API Endpoints Reference ## Dataset表格 | 方法 | 路径 | 说明 | |------|------|------| | POST | /api/dataset/upload | 上传文件 (multipart) | | POST | /api/dataset/load-path | 从服务器路径加载 | | DELETE | /api/dataset | 清除数据集 | | GET | /api/dataset/info | 获取 DatasetMeta | | GET | /api/dataset/preview | ?modehead|tail|randomn20 | | GET | /api/dataset/download | ?columnsa,b,cformatcsv|tsv|parquet | ## Feature Engineering | 方法 | 路径 | 说明 | |------|------|------| | POST | /api/feature/binning | 分箱累积模式 | | POST | /api/feature/onehot | OneHot 编码 | | POST | /api/feature/woe | WOE 编码需 binary target | | POST | /api/feature/scaling | 缩放 (minmax/zscore/log) | ...​ 现在日常开发时 Claude 不会被这 90 多行端点列表干扰。只有当我需要参考 API 时敲一个/api-ref列表才会注入上下文。(2) 如何使用Custom Commands呢​ 这里有个问题你一定会想到搬出去之后Claude 怎么知道去用它​ 答案是Claude 不会自己主动调用 Custom Commands。这是 Custom Commands 的设计它是用户触发的不是 AI 自主触发的。你敲/api-ref内容才注入你不敲Claude 就看不到。​ 那 Claude 怎么知道这个命令存在呢靠你在 CLAUDE.md 里留一个路标。我在主 CLAUDE.md 的设计原则里写了一句- 完整 API 端点列表运行 /api-ref 查看​ 就这一行。Claude 读到它就知道有这个命令可用。当它需要查端点信息时不会自己去调而是会提醒你“建议运行/api-ref查看端点列表。” 最终还是你来敲那个命令。(2) Custom Commands V.S. Skills​ 这里要区分一下两个容易混淆的概念Custom CommandsSkills位置.claude/commands/*.md.claude/skills/*/SKILL.md触发方式手动输入/command-name系统自动匹配或/skill-name本质一段 prompt 模板调用时注入对话有 frontmatter 元数据的能力模块适合场景按需参考的信息、一次性操作模板需要自动触发的领域知识​ 对于API 端点参考这种按需查阅的信息Custom Commands 比 Skills 更合适不需要自动触发不需要 frontmatter 元数据就是一个 Markdown 文件最轻量。3.3 第三刀主 CLAUDE.md 只留骨架​ 两刀下去主 CLAUDE.md 变成了现在的样子只保留全局性的、每次都需要的信息## Project Overview 数据分析工具是一个面向 ML 工程师的数据集分析工具…… ## Tech Stack ### Backend: Python 3.11, FastAPI, pandas…… ### Frontend: Vue 3, TypeScript, Vite, Pinia…… ## Commands conda activate intodata uvicorn intodata.api.main:app --reload --port 9501 cd frontend pnpm dev ## Architecture目录树 一行说明 ## Key Design Principles4 条 ## Version Roadmap表格​ 不到 100 行。技术栈、构建命令、架构概览、核心原则、版本路线都是无论干什么都需要知道的全局上下文。​ 模块细节去子目录 CLAUDE.md 看。API 参考/api-ref调出来。四、重构前后对比​ 左边是重构前的状态所有信息塞在一个文件里每次对话全量注入token 消耗高、信噪比低。右边是重构后主文件只留骨架模块规范按需加载API 参考手动调用——每次对话只注入真正需要的信息。*​ 用表格再细化一下重构前重构后文件1 个巨型 CLAUDE.md1 主 3 子 1 command主文件大小200 行估算~100 行每次加载的 token全量所有模块 API 列表只加载主文件 当前操作目录的子文件改前端时的噪声看到后端 Session 机制、API 端点列表只看到 CSS 设计系统、组件约定API 参考始终占用上下文/api-ref按需加载维护所有人改同一个大文件各模块维护自己的规范五、我总结的三条原则​ 重构完回头看其实就三条原则5.1 CLAUDE.md 是入职手册不是百科全书​ 新同事入职第一天你会给他一份简明的 onboarding 文档不会把整个内部 Wiki 打印出来。CLAUDE.md 也一样只放无论做什么都需要知道的信息技术栈、构建命令、架构概览、核心设计原则。5.2 谁的规矩放到谁家门口​ analysis 层的纯函数约定只有改 analysis 代码时才需要前端的 CSS 工具类列表只有改前端时才需要。用子目录 CLAUDE.md 做到按需加载而不是全量注入。5.3 不是每次都需要的信息做成按需调用​ API 端点列表、数据库 Schema、环境变量清单这些信息偶尔需要参考但不值得每次对话都占用上下文。Custom Commands 就是为这种场景设计的一个 Markdown 文件一个斜杠命令用的时候调不用的时候不占位。六、给正在踩坑的你​ 如果你的 CLAUDE.md 已经超过 150 行或者你发现 Claude 在做简单任务时莫名其妙地走神大概率是时候重构了。​ 不需要一步到位。我的建议是先审计统计一下你的 CLAUDE.md 里有多少信息是每次都需要的有多少是偶尔参考的有多少是只有改特定模块才需要的。先拆子目录把模块级别的规范搬到子目录 CLAUDE.md这一步收益最大改动最小。再做 Commands把偶尔参考的大块信息提取成 Custom Commands。最后精简主文件拆完之后主文件自然就只剩骨架了。​ Claude Code 的配置体系其实设计得很合理分层加载、按需注入、关注点分离。只是官方文档里不会告诉你什么时候该用哪一层这个只有自己踩过坑才知道。​ 希望我的坑能让你少走一段弯路。