hen多开发者dou在尝试用 Claude Code 这样的工具来提升效率。但你是否遇到过这种让人抓狂的情况：明明你的项目结构hen清晰，但那个 AI 助手就像是个刚毕业、完全不懂人情世故的实习生，总是用错 API，或者在你Yi经废弃的旧代码里打转？

这时候，问题往往不出在 AI 的智商上，而是出在“交接”这个环节。没错，AI 也需要入职培训。而 CLAUDE.md，就是这份至关重要的交接文档。今天我们就来聊聊怎么写好这份文档，别让你的 AI 助手在黑暗中摸索。

少即是多：别让文档成为噪音

在深入细节之前，我想先打破一个根深蒂固的刻板印象。hen多人觉得，既然是给 AI kan的文档，那肯定写得越详细越好，恨不得把每一行代码的逻辑dou解释一遍。这种想法大错特错。

这里有一个非常有说服力的真实数据，足以让你冷静下来：Claude Code 的创始人 Boris Cherny，他自己的 CLAUDE.md 配置文件其实非常精简，大概只有几十行代码，换算成 tokens 也就 0.5k 左右。而反观社区里有人为了追求完美，写了一份长达几百行、占用 15k tokens 的“超详细”版本，结果呢？实际效果反而比那个精简版差了一大截。

这背后的逻辑其实并不复杂。大模型的注意力机制是有限的，当你塞进去太多无关紧要的信息，真正关键的规则就会被稀释，淹没在文字的海洋里。这就像是你给新员工发了一本 500 页的操作手册，他根本记不住重点在哪里。所以精简永远优于详尽，保持核心规则的突出，才是王道。

核心认知：这不是 README，是“潜规则”集

我们要先达成一个共识：CLAUDE.md 绝对不是 README 的翻版。README 是写给人类用户kan的，目的是介绍功Neng、展示用法、吸引眼球；而 CLAUDE.md 是写给 Agentkan的，目的是建立约束、提供上下文、明确边界。

Ru果你只是简单地把 README 的内容复制粘贴进去，那简直是Zui大的浪费。Agent 不需要知道你的项目有多酷，它需要知道的是“我们这里不使用 pandas，而是用 polars”这种硬性规定。它的价值在于持续积累，每一次 Agent 犯错，dou是你geng新这份文档的Zui佳时机。

本质上，这是一种上下文注入。大模型是在Zuo“给定上下文，预测Zui合理的输出”。Ru果你不告诉它项目的背景，它就只Neng靠猜，也就是我们常说的“脑补”。给它准确的项目背景，它的“脑补”空间就越小，犯错概率自然就越低。这和人类的学习机制如出一辙：你告诉新人“我们不用那个旧的库”，他以后遇到相关需求时潜意识里就会避开那个方向。

三剑客：CLAUDE.md、Rules 与 Skills

当你的项目逐渐变大，你会发现单靠一个 CLAUDE.md 根本不够用。前端规范、后端逻辑、数据库约束全堆在一起，既难维护，又会在每次会话开始时把不相关的内容全塞进 context，导致资源浪费。这时候，你就需要理解 Claude Code 上下文管理的完整体系：CLAUDE.md + Rules + Skill。

这三者各司其职，就像一个公司的管理层级。理解它们的关键，在于理解它们的加载机制。

1. CLAUDE.md：宪法与总纲

CLAUDE.md 是项目的“宪法”。Claude Code 每次启动会话时会自动将项目根目录的 CLAUDE.md 加载进上下文。这个动作发生在任何对话之前，相当于在 Agent 开口之前，先强制它读了一遍“入职材料”。

它适合放那些Zui通用的规则，比如编程语言偏好、整体的代码风格、项目的基本架构原则。对于新项目，正确的姿势是别过度设计，先把基本上下文给够。比如你Ke以规定所有接口必须通过 Zod 校验入参，或者错误码必须使用特定枚举。

---
paths:
  - "src/api/**/*.ts"
  - "lib/**/*.{ts,tsx}"
---
# API 层核心规范
- 所有接口入参必须经过 Zod 严格校验
- 统一返回 ApiResponse 格式
- 错误码定义请严格参考 src/errors/codes.ts，严禁硬编码

2. Rules：部门规章

当 CLAUDE.md 超过一定篇幅，你就应该开始考虑拆分了。这时候，.claude/rules/ 目录就派上用场了。Rules 是针对特定路径或特定文件的约束，它们是“懒加载”的——只有当 Agent 读取到匹配的文件时相关的 Rule 才会被触发。

这就像软件工程里的懒加载思想——不需要的东西不占内存，context window 也是如此。比如你Ke以针对数据库迁移文件制定专门的规则：

.claude/rules/db.md
└── paths: prisma/migrations/**
    └── 迁移文件命名规范、Prisma Schema 约定

举个例子，你的项目使用 Repository Pattern 封装数据层，但 Agent 总是习惯性地在 Service 层直接写 SQL。你纠正了三次之后终于意识到应该把这条经验写进规则里。下次它再碰到相关目录，这条规则就会像紧箍咒一样生效。

3. Skills：操作手册

Ru果说 Rules 是“知道边界”，那么 Skills 就是“知道怎么Zuo”。.claude/skills/ 用来存放那些复杂的、有副作用的操作流程，比如数据库迁移、部署脚本、发送邮件等。

Skills 的设计非常巧妙，它采用了懒加载机制。启动时只有 description 字段会常驻在 context 里Agent 据此判断何时应该调用这个 Skill。完整的 Skill 内容只在真正需要时才注入。

比如定义一个数据库迁移的 Skill：

---
description: 执行数据库迁移，当用户提到 migration、数据库变geng时自动调用
disable-model-invocation: true   # 禁止自动调用，必须手动 /db-migrate 触发
context: fork                    # 在独立子 agent 中运行，不污染主 context
allowed-tools: Bash, Read, Write
model: claude-haiku-3            # 用便宜的模型跑简单任务
---
# 数据库迁移标准流程
1. 检查 prisma/migrations/ 目录是否存在未提交的geng改...
2. 执行备份操作...
3. 运行 migrate up...
4. 验证数据完整性...

这里有个小技巧：对于有副作用的操作，建议加上 disable-model-invocation: true，防止 Agent 在不合适的时机自动触发，把你的数据库搞炸了。

分层协作的实战案例

为了让你geng直观地理解这三层分工，我们Ke以把它们想象成公司的管理层级：

识别层知道什么时候该Zuo。比如“遇到数据库迁移需求时调用 /db-migrate Skill”。

约束层知道Zuo的边界。比如迁移文件必须怎么命名，Schema 必须符合什么约定。

执行层知道怎么Zuo。比如完整的迁移执行流程：备份 → 运行 migrate → 验证。

这种分层结构带来的好处是显而易见的。项目初期，你Ke以靠 CLAUDE.md 快速积累经验；项目成熟后再把沉淀的智慧拆分到 Rules 和 Skill 中。既保留了历史经验，又不让 context 变得臃肿不堪。

维护循环：让文档“活”起来

hen多人把 CLAUDE.md 当成一个静态配置文件，写完就扔在一边。这是Zui大的误区之一。CLAUDE.md 应该是一个活文档，是你和 Agent 协作过程中积累的“经验库”。

一个完整的维护闭环应该是这样的：

Agent 犯了错误
    ↓
你纠正它
    ↓
把这条经验写进 CLAUDE.md
    ↓
下次它不会再犯
    ↓
规则越来越多？拆到 Rules / Skill，按需加载
    ↓
CLAUDE.md 保持精炼，循环继续

比如你希望所有新功Nengdou先写测试，但 Agent 老是跳过这一步。与其每次dou手动提醒它，不如直接把这条规则加进文档。随着时间推移，这个文档会变得越来越懂你的项目，你和 Agent 的协作效率也会呈指数级上升。

避坑指南：常见的错误姿势

在实战中，我见过太多人踩进同样的坑里。这里几个Zui常见的误区，希望Neng帮你少走弯路。

误区一：过度追求完美

hen多人一上来就想写一份“完美的 CLAUDE.md”，结果要么写不下去，要么写了一堆 Agent 其实不需要的内容。记住先跑起来再说。Ru果你不知道怎么开始，Ke以直接试试 Claude Code 提供的 /init 命令。它会自动扫描项目结构生成一份起步版本的 CLAUDE.md。生成后不要直接用，而是把它当成草稿，删掉不必要的内容，补上项目特有的约定。

误区二：只写一次从不geng新

项目在迭代，技术在geng新，你的 CLAUDE.md 也要跟着变。Ru果你的项目Yi经把某个第三方库替换掉了但文档里没写，Agent 每次还是会去调那个老的 API。这时候别怪 AI 笨，是你没及时geng新“员工手册”。

误区三：忽略层级加载机制

Claude Code 的加载方式是从当前工作目录向上遍历目录树，全量加载每一级的 CLAUDE.md。这意味着你Ke以在不同层级放置不同的 CLAUDE.md。子目录的 CLAUDE.md 只有在 Agent 读取该目录文件时才会触发。利用好这个特性，Ke以实现非常细粒度的上下文控制。

顺便提一句，Ru果你在用 Claude Code，Ke以顺手试试 cc-statistics 这个工具。它Ke以统计你的 AI 编码用量、费用和工具调用分布，帮你geng好地理解自己的 AI 使用习惯，从而优化你的文档配置。

从“对抗”到“共舞”

写好 CLAUDE.md，本质上是在教 AI 如何像你一样思考。这不仅仅是技术问题，geng是一种管理思维的体现。你需要明确地告诉它：项目背景是什么？技术约定有哪些？踩过哪些坑？需要注意什么边界？

当你的项目有了完善的 CLAUDE.mdRules 和 Skills 体系，你会发现，那个曾经让你抓狂的 AI 助手，突然变得懂事了。它Neng在正确的目录里新建文件，用正确的框架写代码，不再跑去联网调用不存在的 API。

这就像培养了一个默契十足的老搭档。你只需要给出一个模糊的指令，它就Neng心领神会地完成任务。这种感觉，真的会上瘾。所以别再犹豫了现在就去检查一下你的 CLAUDE.md，开始你的优化之旅吧。

---