ENZOMEGA.
Clipping 微信公众号

CLAUDE.md 写不好，效率至少下降一半

by 三元同学 原文 ↗
Created: 2026-05-12
#公众号文章

公众号名称：三元同学

作者名称：三元同学

发布时间：2026-03-18 08:24

用 Claude Code 的人越来越多了，但我发现一个很有意思的现象：很多人装好了 Claude Code，上来就开始对话，写得很嗨，但从来没认真搞过 CLAUDE.md。

或者有的人，用 /init 生成了一个，看了一眼觉得”行，差不多”，就再也没动过了。

说实话，这就像你雇了一个很厉害的新同事，但从来不给他做 onboarding，每天早上来了都得重新介绍一遍”我们项目用什么技术栈、测试怎么跑、代码风格有啥要求”。

CLAUDE.md 是你能写的、投入产出比最高的一个文件。 没有之一。

为什么这么说？因为它影响的不是某一次对话，而是你跟 Claude Code 的每一次交互。写好了，Claude 从第一句话就知道该怎么干活；写烂了（或者没写），每次对话都在浪费时间纠正那些本来不该出现的错误。

今天这篇文章，我把自己踩过的坑、社区里看到的最佳实践，全部整理出来了。看完之后你应该能写出一个真正好用的 CLAUDE.md，以及知道如何去避免踩一些常见的坑。

先搞清楚 CLAUDE.md 到底是什么

简单说，CLAUDE.md 是一个 Markdown 文件，Claude Code 在每次会话开始的时候会自动读取它。

你可以把它理解为给 AI 的”项目 onboarding 文档”。不同于 README 是写给人看的，CLAUDE.md 是专门写给 Claude 看的——告诉它你的项目长什么样、代码风格是什么、常用命令有哪些、有哪些坑需要注意。

核心逻辑就一句话：Claude 每次启动都是失忆的，CLAUDE.md 是唯一能让它”记住”你的东西。

没有这个文件，Claude 只能从代码本身去猜你的意图和偏好。有了它，Claude 在动手之前就已经知道了你的项目上下文、规范和约束。

Claude Code 的创始人 Boris Cherny 自己的 CLAUDE.md 也就 2.5k tokens（大概 100 多行），但就是这么一个精简的文件，撑起了他每天同时跑 5 个 Claude 实例的工作流。而且他们团队会把 CLAUDE.md 提交到 git 里，每次 Claude 犯了错就加一条，相当于一个不断进化的”错题本”。

四个存放的位置

很多人不知道 CLAUDE.md 其实有一套层级系统，不同位置的文件覆盖的范围不一样：

1. 全局级别：～/.claude/CLAUDE.md。

2. 项目根目录：./CLAUDE.md。

3. 子目录：./src/api/CLAUDE.md。适合 monorepo 场景。比如前端目录有自己的规范，后端目录有自己的规范，可以各自维护。

4. 本地私有：CLAUDE.local.md。个人偏好，加到 .gitignore 里，不提交。

这四个层级是可以叠加的。Claude 会按顺序全部读取，从全局到具体。

大部分人写 CLAUDE.md 犯的错

在聊怎么写之前，先说说我见过的（以及自己犯过的）最常见的错误。

错误一：写得太长

有的人恨不得把整个项目文档都塞进去，几千行，什么都有。结果呢？Claude 反而开始”无视”你的规则了。

这不是 bug，是模型的客观限制。研究表明，前沿大模型大概能可靠地遵循 150-200 条指令。Claude Code 自身的系统提示已经占了大约 50 条，留给你的空间也就 100-150 条。超了之后，所有指令的执行质量都会下降——不是新加的不管用，是连之前写的也开始不稳了。

经验：控制在 300 行以内。

而且有一个很多人不知道的细节：Claude Code 的系统提示里其实有一行字，大意是”CLAUDE.md 的内容可能与当前任务相关也可能不相关”。也就是说，Claude 会主动过滤它认为跟当前任务无关的内容。写得太多太杂，不但浪费 token，还可能让真正重要的规则被”过滤”掉。

一个简单的检验方法：对每一行问自己——“如果删掉这行，Claude 会不会犯错？” 如果不会，果断删。

错误二：把它当 Linter 用

“用 2 个空格缩进”、“行尾不要分号”、“import 按字母排序”……

我见过很多人把代码风格规则一条条写进 CLAUDE.md 里。

说实话，这是在用大炮打蚊子。代码格式化这种事，ESLint、Prettier、Biome 这些工具干起来又快又准，而且是确定性的。LLM 做这种事既贵又慢，还不一定靠谱。

正确的做法是：让 Claude 写代码，linter 自动格式化，Claude 根据 linter 的报错来修正。 用 hooks 把这个流程自动化，比写一堆代码风格规则管用多了。

错误三：嵌入大段代码或文档

有人在 CLAUDE.md 里用 @ 引用了好几个大文档，结果每次启动的时候这些文件全部被嵌入到上下文里，几千甚至上万 token 就这么没了。

更好的做法是：在 CLAUDE.md 里只写一句指引，告诉 Claude 什么时候去读哪个文件。

# 参考文档

- 遇到认证相关的问题，先看 @docs/auth-patterns.md
- 数据库操作的规范在 @docs/database-conventions.md
- API 设计的约定参考 @docs/api-guidelines.md

这样 Claude 只在需要的时候才去读，不会每次都加载所有内容。核心思路就是：不要一股脑把所有信息都塞给它，告诉它去哪找就行了。

错误四：只写”不要做什么”

“不要用 —force 参数”、“不要直接操作数据库”、“不要修改 migrations 目录”……

光说不要做什么，不说应该做什么，Claude 有时候会卡住——它觉得必须用某个方法，但你又不让它用，它就不知道该怎么办了。

每个”不要”后面都应该跟一个”应该”。 比如：“不要用 —force 推送，应该用 —force-with-lease” 或者 “不要直接操作数据库，应该通过 Prisma migration 来修改 schema”。

错误五：用 /init 生成了就不管了

/init 确实很方便，一行命令就能生成一个基本的 CLAUDE.md。但它只是一个起点。

自动生成的内容通常包含太多无关信息，同时又缺少真正重要的架构决策和业务上下文。这些东西只有你自己知道。

CLAUDE.md 应该是手动精心打磨的，就像对待一段关键的基础设施代码一样。

一个好的 CLAUDE.md 应该长什么样

核心框架：WHAT、WHY、HOW

HumanLayer 的工程团队提出了一个非常清晰的框架：

​

  • WHAT：你的项目是什么？用了什么技术栈？目录结构长什么样？

  • WHY：每个模块的职责是什么？为什么用这个方案而不是那个？

  • HOW：怎么跑测试？怎么构建？怎么部署？用什么包管理器？

围绕这三个维度组织内容，基本上就够了。

我推荐的骨架

以下的骨架是我觉得比较精简并且有足够信息量的：

# 项目名：简短描述

这是一个 Next.js 14 项目，使用 App Router + TypeScript。

## 技术栈

- 前端：React 18 + TypeScript + Tailwind CSS
- 状态管理：Zustand
- 后端：Next.js API Routes + Prisma + PostgreSQL
- 包管理器：pnpm

## 常用命令

-`pnpm dev`：启动开发服务器
-`pnpm test`：运行测试（优先跑单个测试文件，不要跑全量）
-`pnpm lint`：代码检查
-`pnpm typecheck`：类型检查（改完代码之后务必跑一次）

## 项目结构

-`/app` - 页面和路由
-`/components/ui` - 通用 UI 组件
-`/lib` - 工具函数和共享逻辑
-`/prisma` - 数据库 schema 和 migrations

## 代码规范

- 使用 ES Modules（import/export），不用 CommonJS
- 组件用函数式写法，不用 class
- 尽量用 named export，避免 default export

## 重要约定

- 所有 API 路由必须做错误处理
- 环境变量在 .env.local 中，不要提交到 git
- PR 标题用英文，格式：`feat: xxx` / `fix: xxx`

## 注意事项

- Prisma 的 migration 不要手动修改生成的 SQL 文件
- 遇到认证相关的问题，先看 @docs/auth-patterns.md
- 测试用 vitest，mock 数据放在 **fixtures** 目录下

注意几个要点：

​

  1. 开头一行话说清楚项目是什么。

  2. 命令要写精确的语法——比如 Claude 猜不到你用 pnpm 还是 npm。

  3. 只写 Claude 猜不到的东西——TypeScript、React 的基本语法不用教它。

  4. 架构决策要写”为什么”——不只是告诉它目录结构，还要说清楚每个目录的职责。

进阶技巧

技巧一：用 @imports 保持主文件精简

CLAUDE.md 支持 @path/to/file 语法来引用其他文件：

# 项目概览

...

# 详细文档

- Git 工作流：@docs/git-workflow.md
- API 设计规范：@docs/api-conventions.md
- 个人偏好：@～/.claude/my-preferences.md

这样主文件保持简洁，详细的内容按需加载。

你也可以用 .claude/rules/ 目录来组织模块化的规则：

.claude/
├── CLAUDE.md
└── rules/
    ├── code-style.md
    ├── testing.md
    └── security.md

放在 .claude/rules/ 里的 Markdown 文件会跟主文件一起自动加载，不需要手动 import。

更强大的是，这些规则文件支持 YAML frontmatter 的 paths 字段，可以用 glob 匹配来限定作用范围：

---
paths: src/auth/**/*
---

# 认证模块规则

- 所有认证相关的接口必须做 rate limiting
- Token 刷新逻辑不要手动实现，用 @lib/auth-utils.ts 里的工具函数

这样只有当 Claude 处理 src/auth/ 下面的文件时，这些规则才会生效。非常适合大型项目里不同模块有不同约定的场景。

技巧二：用强调语法提升关键规则的权重

如果某条规则 Claude 老是不遵守，可以试试加重语气：

IMPORTANT: 所有数据库操作必须通过 Prisma ORM，绝对不要写原生 SQL。

YOU MUST: 改完代码之后跑一次 typecheck。

Anthropic 官方文档明确说了，IMPORTANT、YOU MUST 这类关键词可以提升模型对特定指令的遵循程度。当然，不要滥用，每条都加”IMPORTANT”就等于没加。

技巧三：自定义压缩策略

Claude Code 在上下文快满的时候会自动压缩对话历史。你可以在 CLAUDE.md 里指定压缩时要保留什么：

## 压缩策略

压缩对话的时候，务必保留：

- 所有修改过的文件列表
- 测试命令和测试结果
- 当前的实现计划和进度

这样即使对话被压缩了，关键信息也不会丢。

技巧四：定期让 Claude 帮你优化

每隔几周，可以让 Claude 自己来审查和优化你的 CLAUDE.md：

帮我看看当前的 CLAUDE.md，有没有过时的内容？有没有冗余的规则？
有没有表述不清楚的地方？帮我优化一下。

它会基于项目的当前状态给出修改建议，删掉过时的、合并重复的、改清楚含糊的。

技巧五：结合 hooks 实现硬性约束

CLAUDE.md 里的规则本质上是”建议性”的——Claude 大概率会遵守，但不是 100%。如果某个规则必须严格执行，比如”每次编辑文件后跑 lint”，那就用 hooks。

Hooks 是在 Claude 工作流特定节点自动执行的脚本，是确定性的，保证会执行。

你可以直接让 Claude 帮你写 hooks：

写一个 hook，每次编辑文件之后自动跑 eslint、e2e 测试用例

CLAUDE.md 负责”软约束”（建议和偏好），hooks 负责”硬约束”（必须执行的规则）。 两者配合使用效果最好。

还有一件事：CLAUDE.md 不只是给 Claude Code 用的

现在各家 AI 编程工具都有类似的配置文件：

​

  • Claude Code → CLAUDE.md

  • Cursor → .cursor/rules

  • GitHub Copilot → .github/copilot-instructions.md

  • Open Code → OPENCODE.md

  • Gemini CLI → GEMINI.md

如果你的团队里有人用 Cursor，有人用 Claude Code，可以考虑维护一个 AGENTS.md 作为通用版本，然后各个工具的配置文件从它派生。这样不用维护多份重复的规则。比如在以上所有的配置文件里面都写上：

Include:
@./AGENTS.md

然后，把具体的内容全放到 AGENT.md 里面，这样就免得为不同的 Agent 维护不同的文档了。

总结一下

最后，如果你只记住几条的话，我推荐是下面这些：

​

  1. 控制长度：300 行以内，最好更短。每一行都要”值得”占用指令预算

  2. 只写 Claude 猜不到的：代码规范交给 linter，标准用法不用教，重点写你项目特有的东西

  3. 用渐进式信息披露：主文件精简，详细内容放到独立文件里按需加载

  4. “不要”后面要跟”应该”：给 Claude 明确的替代方案

  5. 定期维护：当成活文档来管理，过时的删掉，新发现的坑及时加进去

一个好的 CLAUDE.md，是你跟 Claude Code 之间效率的放大器。值得你花半小时认真写一次，然后持续迭代。

有什么问题欢迎评论区交流，如果觉得有帮助，欢迎一键三连。我是三元同学，我们下一期再见。

cover_image

原创 三元同学 三元同学

内容效果不满意？点此反馈

输入关键词开始搜索