本文为转载内容，保留原帖观点与结构；如有侵权请联系我处理。

为什么我们需要调整

用 Claude Code 做项目时间长了，不少朋友都发现 CLAUDE.md 这个文件越来越“胖”。一开始可能只有几段简单的项目介绍，后来逐渐加上了部署步骤、测试流程、数据库操作说明，还有各种“踩过的坑”提醒……不知不觉就变成了几百上千行的“大部头”。

这里有个实际问题：每次 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 行，不妨试试这个方法，应该能明显感受到变化。

---

延伸阅读 ：

• Claude Code Skills 官方文档
• 这个思路最初来自 Reddit 上的 ClaudeAI 社区讨论

微信群 聊天，讨论技术