▶

10-Claude.md介绍与编写

Claude Code
CLAUDE.md 是 Claude Code 每次启动都自动加载的“开场白”文件——写一次它就永远记得，比每次会话重新交代偏好划算太多。
一、CLAUDE.md 是什么

把 Claude Code 想成一个能力很强的新同事，但他有个毛病：每次开新会话就彻底失忆。

你昨天跟他说“我喜欢用中文”、“别随便删我文件”、“我的项目用 React”——今天全忘了，你得从头讲一遍。

CLAUDE.md 就是你给这个“失忆同事”写的一份入职须知。Claude Code 每次启动，第一件事就是读这份文件。你写一次，它就永远记得。

不写行不行？行。但你会发现有些约定的规则每次都得重复说。写了之后，这些话再也不用说第二遍。

二、CLAUDE.md 分三层

打个比方：

•
全局 CLAUDE.md = 你公司的员工手册。所有员工都要遵守——“用中文沟通”、“先确定需求再执行”——这些跟具体项目无关
•
项目 CLAUDE.md = 具体项目的操作手册。“这个项目用什么技术”、“文件夹命名规范”——只适用这个项目的规则
•
子目录 CLAUDE.md = 某个部门的内部规定。Claude 操作哪个目录的文件，就会自动加载那个目录的规则

文件位置：

全局
~/.claude/CLAUDE.md　每个人都该有
项目
项目目录/CLAUDE.md　每个项目都该有
子目录
项目目录/sub/CLAUDE.md　知道有这层就行

都叫 CLAUDE.md。一般来说全局和项目的都是必备，子目录的没那么必要——我在部分项目里也用过，目的是压缩项目根 CLAUDE.md 的内容。

启动 Claude Code 时，它先读全局、再读项目，两份叠加生效。操作到某个子目录的文件时，再叠加那个子目录的规则。三层内容注意不要互相冲突。

三、全局 CLAUDE.md：先把“你这个人”讲清楚

这是每个人都该有的，五分钟搞定。全局只解决一个问题：不管你今天干什么项目，哪些规矩都适用。

3.1　通用模板（30 行左右，复制粘贴就能用）
# 关于我
[填实身份、技术水平、主要用途]

## 沟通偏好
- 默认中文回复，代码/命令/变量名保持英文
- 结论先行再给理由
- 不要谄媚，方案有问题直接说

## 自主程度
- 小改动：直接做完验证
- 中等改动：先给方案摘要，确认后执行
- 大改动：Plan Mode 出方案

## 代码风格
- 能短就别长，小需求别给企业级架构
- 没让改的地方别碰
- 不靠注释报错或绕过标记让代码跑起来

## 红线（必须停下来问我）
- 删除文件/目录/git 历史
- 修改 .env、密钥、CI/CD 配置
- 数据库 schema 变更
- git push/rebase/reset --hard
- 安装全局依赖或修改系统配置
- 公开发布

## Git
- Commit 英文，Conventional Commits 格式
- 提交前跑验证（具体命令见项目 CLAUDE.md）
3.2　这 6 块讲什么
•
关于我——你是谁、技术水平、用 Claude Code 干什么。写给程序员和写给小白的回答是有差异的
•
沟通偏好——中文回复、结论先行、不要谄媚
•
自主程度——小改动直接做、中改动先报方案、大改动进 Plan Mode
•
代码风格——能短就别长、没让改的别碰、不靠注释绕报错
•
红线——删文件、改密钥、git push 这些操作，不管什么情况都必须先问你
•
Git——我所有项目都用 git 做版本管理，所以这条也是通用规则
3.3　怎么放到 Claude Code 里

两种方式：

方式一　让 AI 帮你写

把上面模板复制发给 Claude Code，跟它说“帮我写到全局 CLAUDE.md 里”，写完还可以继续让 AI 帮你优化。

方式二　自己手动放
# Mac
nano ~/.claude/CLAUDE.md

# Windows
notepad "$HOME/.claude/CLAUDE.md"

完事之后随便启动一个 Claude Code 会话，问它一句“你认识我吗”——它会按你“关于我”里写的那段自我介绍。这就是全局生效了。

四、项目 CLAUDE.md：三步走

全局搞定了，再来搞项目级。

1
规划项目基础——把“做什么、技术栈、目录结构”想清楚，让 AI 帮你列方案
2
敲 /init 生成草稿——cd 进项目根，启动 Claude Code，敲 /init。它会扫一遍目录自动生成 30 到 50 行的草稿。这是起点，不是终版——打开看一遍，把项目特有的红线加上去，把验证命令（npm test、pytest 等）补上
3
边干边补——每条规则都对应一个具体踩过的坑，不是凭空想出来的。AI 走偏、纠正三次以上的事，加进去

如果项目还很简单、或根本不是代码项目（比如就是个“装东西的目录”），/init 可能扫不出啥。这时直接跟 Claude Code 聊就行：“我这个目录是用来 XX 的，希望你以后帮我做事的时候 YY，能不能帮我写一份 CLAUDE.md 放在根目录？”非程序员尤其推荐这条路，全程对话搞定。

五、长度红线 + 四个坑
5.1　长度红线：写得越多 ≠ 越听话

一句话——越短越好，80 行以内是安全区，不要超过 300 行。

两个原因：

1
AI 有“中段失忆”——文件开头和结尾记得牢，中间那段最容易被忽略
2
每次启动都加载——越长每次消耗的 token 越多，挤压 AI 思考实际问题的“脑容量”

控制长度的诀窍：

•
重要的放最前面——红线、护栏全放顶部
•
用短句不用长段——“改 .env 前必须先问我”抵得过一段铺垫
•
每月翻一遍删掉过时规则——精简的核心是删，不是加
5.2　四个不要踩的坑
第一坑　不要往里塞大段文档
有人把整份 API 文档、整个风格指南粘进去，几千上万 token 每次白烧，AI 反而更笨。让 AI 帮你提炼成 10 行关键参数就够了。
第二坑　不要写模糊的废话
“写出高质量代码”、“聪明一点”——AI 不知道这是什么意思。要写就写具体的，比如“函数超过 50 行先停下来想想能不能拆”。
第三坑　不要让 Claude 自己往里加东西
放任几周 CLAUDE.md 就膨胀到 300 行。正确做法：让 Claude 提议，你审核通过了才加。
第四坑　全局和项目不要重复写
“用中文回复”全局已经覆盖所有项目了，项目级只写这个项目特有的事。
本章小结

CLAUDE.md 是给“AI 同事”的入职手册——开始套我的模板，用着用着再长成你自己的。

下一步我们把这份“入职手册”真正用起来，让 Claude Code 按你定的规矩干活。

AI 助手