给 CLAUDE.md 减减负：让配置文档更清爽的实用方法

为什么我们需要调整

使用 Claude Code 进行项目开发一段时间后，许多用户发现 CLAUDE.md 文件逐渐变得庞大。最初可能只有几段简单的项目介绍，但随着部署步骤、测试流程、数据库操作说明以及各种“踩过的坑”提醒的加入，文件不知不觉间变成了包含数百上千行的“大部头”。

实际问题在于，每次 Claude 读取配置时都需要扫描整个文件，然而大部分内容在当前对话中可能并不实用。例如，你可能只需要 Claude 帮你修复一个小 bug，但它却要先读取整个部署文档和迁移指南，这就像想找一颗螺丝却得翻遍整个工具箱一样繁琐。

换个思路管理项目文档

核心思路非常直接：将“具体操作步骤”和“项目基本信息”分开存放。

• CLAUDE.md：保留项目概览、技术栈选择、架构设计等“为什么这么做”的背景信息。
• Skills 文件：将具体的操作流程拆分出去，需要时再告诉 Claude 去查看相应的文件。

举个例子，原来的 CLAUDE.md 中可能包含以下内容：

## 生产环境部署流程
1. 先在本地跑测试：npm run test
2. 构建生产版本：npm run build
3. 检查环境变量配置... （后面还有好几十行具体步骤）

优化后，内容变为：

## 生产环境部署
详细步骤看这里：`/deploy-production`
简单说就是通过 GitHub Actions 自动部署，需要提前配好 AWS 凭证。

具体的操作细节则放到 .claude/skills/deploy-production.md 这个专门的文件里。

动手实践步骤

1. 先做个备份，安心一点

开始改动前，先将当前文件存一份：

cp CLAUDE.md CLAUDE.md.备份-$(date +%Y%m%d)

2. 判断哪些内容适合拆出去

适合单独做成 Skills 的：

• 分步骤的操作流程（部署、数据迁移、跑测试）
• 常见问题的排查步骤
• 需要连续执行多个命令的操作
• 环境配置的具体指南

建议留在 CLAUDE.md 里的：

• 项目架构的整体说明
• 当初为什么选这些技术
• 重要配置项的速查表
• 核心概念的解释

3. 创建 Skills 文件

推荐这样组织目录结构：

.claude/skills/
├── deploy-production.md    # 生产部署
├── database-migration.md   # 数据库迁移
├── troubleshoot-api.md     # API问题排查
└── setup-dev-env.md       # 开发环境搭建

每个 Skill 文件可以按这个模板来写：

# 技能名称

简单说明这个技能是干嘛用的，一般在什么情况下会用到。

## 什么时候用

- 场景1：比如要上线新版本时
- 场景2：比如遇到某个特定错误时

## 具体步骤

1. 第一步要做什么（附上具体的命令）
2. 第二步...
3. 依次往下

## 怎么确认成功了

做完之后，通过哪些方法可以验证操作是成功的。

## 可能遇到的问题

- 问题1：如果遇到...，可以试试...
- 问题2：有时候会...，这时候应该...

4. 更新主配置文件

在 CLAUDE.md 里把大段步骤换成简洁的引用：

## 数据库迁移
完整流程看：`/database-migration`
我们用 Prisma 管理数据库结构，迁移文件都放在 `prisma/migrations/` 目录下。

实际效果怎么样？

以我们自己的一个项目为例，具体拆出了这些操作指南：

• 生产部署流程
• 数据库迁移步骤
• API问题排查方法
• 邮件功能测试配置
• 新同事开发环境搭建
• 性能监控设置
• 日志查看和分析
• 紧急回滚操作

建议的提取顺序

先处理这些（最重要）：

• 部署上线的流程
• 数据库相关操作
• 常见故障排查

然后处理这些（比较重要）：

• 测试流程
• 环境配置
• 监控告警设置

最后处理这些（不太常用）：

• 一次性操作
• 特殊场景处理

需要注意的几点

1. 每个文件要独立：尽量让每个 Skill 自己就能说清楚，不用来回翻其他文件
2. 名字要直观：用像 deploy-production 这样的命名，别用简写
3. 记得加验证步骤：每个操作都要说明怎么判断成功了没
4. 把踩过的坑写上：把常见问题和解决办法也放进去，帮后面的人省时间

如果文件已经很大了，试试这个办法

如果你的 CLAUDE.md 已经很长了，可以直接请 Claude 帮你分析整理。把下面这段话发给它：

能帮我分析一下当前项目的 CLAUDE.md 吗？我想把适合的部分提取成单独的 Skills 文件。

第一步：先创建个备份文件，比如 CLAUDE.md.backup-[时间戳]

第二步：帮我看看哪些内容适合拆出来
- 分步骤的具体流程
- 故障排查指南
- 环境配置说明
- 需要执行多个命令的操作

第三步：创建 Skills 文件
- 放在 .claude/skills/ 目录里
- 文件用英文短横线连接命名
- 包含：什么时候用、具体步骤、怎么验证、常见问题

第四步：更新 CLAUDE.md
- 把大段步骤换成简短引用
- 保留2-3句概括说明

优先处理：部署流程、数据库迁移、故障排查

整理完后：
1. 备份文件创建了没
2. 提取了哪些 Skills
3. 文件大小减少了多少

总结一下

这个方法的本质是让不同的内容各归其位：

• CLAUDE.md：主要回答“这是什么项目”“为什么这样设计”
• Skills 文件：主要回答“具体怎么操作”

这样做的好处很明显：

• Claude 读取配置时速度更快
• 操作文档模块化了，更容易维护
• 主配置文件清爽多了，重点更突出
• 新同事接手时，能更快找到需要的信息

如果你的 CLAUDE.md 已经超过 500 行，不妨试试这个方法，应该能明显感受到变化。