CLAUDE.md 写法速查手册

38 分钟

一、一句话定义

CLAUDE.md = 写给 Claude Code 的"工作备忘录"。每次启动时自动读取，让 Claude Code 记住你的偏好和规则。

二、两大记忆系统

Claude Code 有两套互补的记忆机制，每次会话开始时都会加载：

	CLAUDE.md 文件	Auto-Memory
谁来写	你	Claude 自动写
内容	指令和规则	学到的经验和模式
作用域	项目/用户/组织	按项目（同一 Git 仓库共享）
加载方式	每次会话完整加载	每次会话加载前 200 行或 25KB
适合存放	编码规范、工作流、项目架构	构建命令、调试经验、偏好发现

CLAUDE.md 适合你主动指导 Claude 的行为；Auto-Memory 让 Claude 从你的纠正中自动学习，无需手动维护。

三、三个层级

层级	文件位置	作用范围	共享方式	详见
用户级	`~/.claude/CLAUDE.md`	你的所有项目通用	仅自己	三个层级
项目级	`项目根目录/CLAUDE.md` 或 `.claude/CLAUDE.md`	本项目所有人	通过 Git 共享给团队	三个层级
本地级	`项目根目录/CLAUDE.local.md`	本项目仅自己	自动 gitignore，不提交	三个层级

加载顺序: 所有找到的 CLAUDE.md 文件会被合并加载。更具体的指令优先级更高。

额外层级:

层级	文件位置	说明
组织策略级	macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`	IT/DevOps 部署的全组织策略，无法被排除
项目规则	`.claude/rules/*.md`	模块化的项目规则文件，自动加载；支持 `paths` frontmatter 按文件类型条件加载
用户规则	`~/.claude/rules/*.md`	个人规则文件，对所有项目生效
子目录级	子目录中的 `CLAUDE.md`	当 Claude 访问该子目录时按需加载
Auto-Memory	`~/.claude/projects/<项目>/memory/MEMORY.md`	Claude 自动保存的工作笔记（前 200 行或 25KB 加载）；同一 Git 仓库的所有 worktree 共享

四、推荐结构模板

通用模板（面向所有人）

# 项目概述
[1-3 行描述这个项目是什么]
 
# 工作偏好
- 用中文回复，技术术语保留英文
- 回复简洁，使用要点列表
- 修改文件前先说明修改计划并等待确认
 
# 重要提醒
- 不要删除任何文件，除非我明确要求
- 不要修改 .env 文件

非程序员模板

# 工作说明
我是[你的职位]，主要用 Claude Code 来[主要用途]。
 
# 工作偏好
- 用中文回复
- 回复要专业但不过于正式
- 文档格式使用 Markdown
- 数字和日期使用中国格式（如 2026年2月24日）
 
# 文件操作规则
- 整理文件前先列出整理方案让我确认
- 不要删除任何文件，只能移动或重命名
- 创建的文件名使用中文
 
# 写作风格
- 邮件语气要礼貌专业
- 报告要有清晰的标题层级
- 数据展示优先使用表格

开发者模板

# 项目概述
[项目名] - [技术栈，如 Node.js 22 + Express + PostgreSQL]
 
# 编码规范
- [语言/框架特定规范]
- 所有导出函数必须有注释
- [命名约定]
 
# 常用命令
- 启动: [命令]
- 测试: [命令]
- 构建: [命令]
 
# 工作偏好
- 用中文回复
- 修改文件前先说明内容和原因
- 改完代码后运行测试
 
# 安全规则
- 不要修改 .env 或迁移文件
- 不要执行 git force push 或 reset --hard
- 删除文件前必须确认

五、好指令 vs 坏指令

坏指令	好指令	为什么好
写好的代码	所有函数必须有 JSDoc 注释，变量名使用 camelCase	具体到可以逐项检查
注意代码风格	缩进使用 2 个空格，每行不超过 100 个字符	有明确数字标准
小心处理文件	修改任何文件前，先列出修改清单并等待确认	有具体操作步骤
尽量简洁	回复控制在 200 字以内，使用要点列表而非长段落	量化了"简洁"
做好测试	每个新函数必须有对应的单元测试，测试文件放在 tests/ 下	明确测试要求和位置
用合适的方式处理错误	所有错误必须用 try-catch 捕获，包含操作名称和原因	指定了错误处理方式
注意安全	不要修改 .env；不要执行 rm -rf；敏感操作先确认	列出了具体禁止项

三原则: 具体、可执行、可验证

六、常用指令模板（15 个分类示例）

语言与风格

#	指令	适用场景
1	`用中文回复，技术术语保留英文`	通用
2	`回复控制在 200 字以内，使用要点列表`	通用
3	`代码注释用中文，变量名和函数名用英文`	编码

工作流程

#	指令	适用场景
4	`修改文件前先列出修改计划并等待确认`	通用
5	`如果有多种实现方式，列出优缺点让我选择`	通用
6	`不确定的事情要问我，不要自己猜`	通用
7	`每次只修改一个文件，不要批量操作`	安全优先

编码规范

#	指令	适用场景
8	`每个导出函数必须有注释说明入参、返回值和功能`	编码
9	`使用 pnpm 而不是 npm 或 yarn`	Node.js
10	`遇到错误时显示完整的错误信息和堆栈`	调试
11	`创建文件时遵循现有项目的目录结构`	代码组织

安全规则

#	指令	适用场景
12	`不要修改 .env、.gitignore 和迁移文件`	安全
13	`不要执行 rm -rf 命令`	安全
14	`不要执行 git force push 或 reset --hard`	安全
15	`删除任何文件前必须获得我的明确确认`	安全

七、@path 导入语法

在 CLAUDE.md 中用 @路径 引入其他文件的内容：

# 项目说明
参见 @README.md 了解项目概述，@package.json 查看可用命令。
 
# 额外规则
- Git 工作流 @docs/git-instructions.md
- API 规范 @docs/api-style.md

导入规则

规则	说明
相对路径	相对于 CLAUDE.md 文件所在目录解析
绝对路径	支持绝对路径
家目录导入	`@~/.claude/my-instructions.md`（跨 worktree 共享）
递归导入	被导入文件可以继续导入其他文件，最多 5 层
首次审批	首次遇到外部导入时会弹出审批对话框
代码块内不解析	反引号内的 `@路径` 不会被当作导入

八、/init 命令使用

操作	说明	详见
`/init`	让 Claude Code 分析项目并自动生成 CLAUDE.md	用 /init 创建
手动创建	在项目根目录创建名为 `CLAUDE.md`（全大写）的文件	CLAUDE.md 是什么

注意

文件名必须是 CLAUDE.md，全部大写。claude.md 或 Claude.md 不会被识别。

九、/memory 命令使用

操作	说明	详见
`/memory`	列出所有已加载的 CLAUDE.md 和 Rules 文件；启用/禁用 Auto-Memory；打开记忆文件夹	/memory 记忆管理
对话中说 "记住这个..."	Claude 自动保存到 Auto-Memory（MEMORY.md）	/memory 记忆管理
对话中说 "把这个加到 CLAUDE.md"	Claude 直接编辑 CLAUDE.md（而非 Auto-Memory）	/memory 记忆管理

/memory 会列出所有可编辑的记忆文件，包括：

用户级 CLAUDE.md
项目级 CLAUDE.md
本地级 CLAUDE.local.md
Auto-Memory MEMORY.md（可直接打开文件夹浏览）
Auto-Memory 开关切换

十、.claude/rules/ 模块化规则

将规则按主题拆分到独立文件中：

项目根目录/
├── .claude/
│   ├── CLAUDE.md              # 主项目指令
│   └── rules/
│       ├── code-style.md      # 代码风格
│       ├── testing.md         # 测试规范
│       ├── security.md        # 安全要求
│       └── frontend/
│           ├── react.md       # React 规则
│           └── styles.md      # 样式规则

路径条件规则

使用 YAML frontmatter 的 paths 字段，让规则只对特定文件生效：

---
paths:
  - "src/api/**/*.ts"
  - "lib/**/*.ts"
---
 
# API 开发规则
- 所有 API 端点必须包含输入验证
- 使用标准错误响应格式

十一、Auto-Memory 系统

工作原理

Auto-Memory 让 Claude 在跨会话间积累知识，无需你手动编写。Claude 在工作过程中自动保存笔记：构建命令、调试经验、架构笔记、代码风格偏好和工作流习惯。

存储结构

~/.claude/projects/<项目>/memory/
├── MEMORY.md          # 简洁索引，每次会话加载前 200 行或 25KB
├── debugging.md       # 调试模式的详细笔记
├── api-conventions.md # API 设计决策
└── ...                # Claude 按需创建的其他主题文件

关键行为

特性	说明
默认开启	v2.1.59+ 默认启用
加载限制	仅 `MEMORY.md` 前 200 行或 25KB 在会话启动时加载；主题文件按需读取
作用域	同一 Git 仓库的所有 worktree 和子目录共享同一个 Auto-Memory 目录
启用/禁用	`/memory` 菜单切换；或 `settings.json` 中设置 `autoMemoryEnabled: false`；或环境变量 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`
自定义路径	`settings.json` 中设置 `autoMemoryDirectory`（仅接受 user/local/policy 级别，不接受 project 级别）
可编辑	纯 Markdown 文件，随时可以手动编辑或删除

与 CLAUDE.md 的分工

你想实现什么	放在哪里
主动指导 Claude 的行为（"用 2 个空格缩进"）	CLAUDE.md
让 Claude 记住你的纠正（"记住用 pnpm 不用 npm"）	Auto-Memory
团队共享的项目规范	CLAUDE.md (项目级)
Claude 自己发现的构建命令和调试技巧	Auto-Memory

十二、HTML 注释行为

CLAUDE.md 中的块级 HTML 注释（）会在注入 Claude 上下文前被自动剥离。适合留给人类维护者的备注，不消耗 Token。

场景	行为
CLAUDE.md 中的块级 HTML 注释	自动剥离，不进入 Claude 上下文
代码块内的 HTML 注释	保留不变
使用 Read 工具直接打开 CLAUDE.md	注释可见

<!-- 这段注释只有人类看得到，Claude 看不到 -->
# 项目规范
用 TypeScript 严格模式

十三、编写清单

写完 CLAUDE.md 后，用这个清单自检：

每条指令是否足够具体？（能检查"是否遵守"）
是否有矛盾的指令？
总行数是否在 200 行以内？（官方建议 ~500 行上限）
是否分区组织，容易查找？
通用偏好是否放在了用户级？
项目特定规则是否放在了项目级？
个人私有设置是否放在了本地级？
留给人类的备注是否用了 HTML 注释？（自动剥离，不消耗 Token）
Auto-Memory 是否已启用？（默认开启；用 /memory 检查）

十四、层级选择指南

你想配置什么	放在哪里	文件
所有项目通用的偏好（语言、风格）	用户级	`~/.claude/CLAUDE.md`
团队共享的项目规范	项目级	`项目/CLAUDE.md`
只属于自己的项目设置	本地级	`项目/CLAUDE.local.md`
按主题拆分的详细规则	项目规则	`.claude/rules/*.md`
个人的全局规则模块	用户规则	`~/.claude/rules/*.md`

十五、常见问题速查

问题	解决方案
Claude Code 没有读取 CLAUDE.md	确认文件名全大写 `CLAUDE.md`，放在项目根目录
写了规则但没被遵守	改写为更具体、量化的版本；避免"尽量""最好"等模糊词
修改后没有立即生效	退出后重新启动 Claude Code，或开始新的对话
CLAUDE.md 越来越长	使用 `@path` 导入拆分，或使用 `.claude/rules/` 目录
通用偏好每个项目都要重复写	移到用户级 `~/.claude/CLAUDE.md`
团队成员风格不统一	统一项目级 CLAUDE.md，个人偏好放 CLAUDE.local.md
Auto-Memory 太多/不准确	用 `/memory` 打开记忆文件夹，手动编辑或删除 MEMORY.md 和主题文件
想禁用 Auto-Memory	`/memory` 菜单切换，或 `settings.json` 中设置 `autoMemoryEnabled: false`
`/compact` 后指令丢失	CLAUDE.md 完整保留；如果丢失的指令只存在于对话中而非文件中，请加入 CLAUDE.md

十六、高级用法

三层架构概览

Claude Code 的持久化指令体系由三层组成：

层次	机制	谁写	稳定性
CLAUDE.md	项目/用户/组织指令	你	最稳定
Rules	模块化规则（`.claude/rules/`）	你	按主题拆分
Auto-Memory	自动积累的学习笔记	Claude	持续演化

团队共享的内容放 CLAUDE.md / Rules（Git 追踪）；Claude 自己的学习放 Auto-Memory（本地私有）。

多层级配置优先级

CLAUDE.md 的多层级配置遵循以下覆盖关系（后者覆盖前者）：

组织策略级 < 用户级 < 项目级 < 本地级 < 子目录级

层级	文件位置	覆盖关系	详见
组织策略级	`/Library/Application Support/ClaudeCode/CLAUDE.md`	最低优先级（全组织）	三个层级
用户级	`~/.claude/CLAUDE.md`	覆盖组织级	三个层级
项目级	`项目根目录/CLAUDE.md` 或 `.claude/CLAUDE.md`	覆盖用户级	三个层级
本地级	`项目根目录/CLAUDE.local.md`	覆盖项目级	三个层级
子目录级	子目录中的 `CLAUDE.md`	当 Claude 访问该子目录时按需加载	三个层级

实际行为: 所有找到的 CLAUDE.md 文件会被合并加载。当指令冲突时，更具体（更靠近工作目录）的指令优先。

CLAUDE.md 与 Rules 文件的配合

文件类型	位置	特点	适用场景
`CLAUDE.md`	项目根目录	通过 Git 共享，团队统一	项目概述、编码规范、常用命令
`.claude/rules/*.md`	`.claude/rules/` 目录	模块化组织，自动加载	按主题拆分的详细规则
`~/.claude/rules/*.md`	用户规则目录	对所有项目生效	个人全局规则模块
`CLAUDE.local.md`	项目根目录	自动 gitignore	个人私有的项目设置

最佳组合: 项目 CLAUDE.md 保持简短（项目概述 + 核心规范），详细规则拆分到 .claude/rules/ 目录，个人偏好放 ~/.claude/CLAUDE.md 或 ~/.claude/rules/。

高级指令模式

在 CLAUDE.md 中可以使用条件规则和角色定义，实现更精细的控制：

# 工作规则
 
## 按文件类型应用不同规则
- 修改 TypeScript 文件时: 运行 `pnpm lint` 检查
- 修改测试文件时: 运行 `pnpm test` 验证
- 修改 Markdown 文件时: 检查拼写和链接
 
## 按任务阶段应用不同规则
- 探索阶段（Plan Mode）: 只读取文件、不做修改
- 实施阶段: 每修改一个文件后立即运行相关测试
- 审查阶段: 对比变更前后的差异

提示: 使用"IMPORTANT"、"YOU MUST"等强调词可以提高 Claude 的遵守率。官方建议问自己："去掉这一行 Claude 会犯错吗？"——如果不会就删掉。

与 Skill 的协同

在 CLAUDE.md 中可以引用 Skill 并设置工作流偏好：

# 工作流偏好
 
## 代码审查
项目优先使用代码审查 Skill 进行审查
审查时关注安全漏洞和性能问题
 
## 重构
重构时先使用 Plan Mode 列出方案
大规模重构使用 SubAgent 并行处理

Skill 在 .claude/skills/ 目录中以 SKILL.md 文件定义，Claude 在相关时自动匹配应用（详见 Skill 概念）。

与 Hook 的配合

CLAUDE.md 定义偏好（建议性），Hook 自动执行检查（确定性）：

机制	性质	示例
CLAUDE.md 指令	建议性，Claude 尽力遵守	"修改代码后运行测试"
Hook 脚本	确定性，保证每次执行	SessionStart 时自动运行 `npm install`

分工原则: CLAUDE.md 用于 Claude "应该知道"的偏好和规则；Hook 用于"必须每次执行、零例外"的动作。

企业级 CLAUDE.md 管理

层级	管理方	用途
组织策略级	IT/DevOps	安全策略、合规要求、禁止项
托管设置	管理员控制台	覆盖项目和用户设置
项目级	团队 Lead	项目规范、编码标准、工作流
用户级	个人开发者	个人偏好、语言、风格

托管设置文件（managed settings）具有最高优先级，会覆盖项目和用户的 settings.json 配置。

十七、速查卡（打印用）

=== CLAUDE.md 速查 ===
 
【三层级】
  用户级:  ~/.claude/CLAUDE.md        (所有项目通用)
  项目级:  项目/CLAUDE.md             (Git 共享)
  本地级:  项目/CLAUDE.local.md       (个人私有)
 
【扩展层级】
  组织策略:  /Library/.../ClaudeCode/CLAUDE.md  (IT 部署)
  项目规则:  .claude/rules/*.md                 (模块化)
  用户规则:  ~/.claude/rules/*.md               (个人全局)
  子目录:    子目录/CLAUDE.md                   (按需加载)
 
【Auto-Memory】
  存储位置:  ~/.claude/projects/<项目>/memory/
  加载限制:  MEMORY.md 前 200 行 / 25KB
  作用域:    同 Git 仓库所有 worktree 共享
  管理:      /memory → 启用/禁用/浏览
 
【三层架构】
  CLAUDE.md = 你写的指令 (最稳定)
  Rules     = 模块化规则 (按主题拆分)
  Memory    = Claude 自动学习 (持续演化)
 
【推荐结构】
  # 项目概述  → 是什么
  # 编码规范  → 怎么写
  # 工作偏好  → 怎么合作
  # 常用命令  → 常用什么
 
【写法原则】具体 + 可执行 + 可验证
【长度建议】≤ 200 行（官方上限 ~500 行）
【HTML注释】<!-- --> 自动剥离，不消耗 Token
 
【快速操作】
  /init     → 自动创建 CLAUDE.md
  /memory   → 编辑 CLAUDE.md / Auto-Memory
  @path     → 导入其他文件
 
【高级协同】
  CLAUDE.md = 建议性偏好  |  Hook = 确定性执行
  Skill = 可重用专业指令  |  Rules = 模块化规则

相关速查手册: 斜杠命令速查 | 快捷键速查 | CLI 参数速查

参考速查5/5

CLI 启动参数速查手册术语表

38 分钟

参考速查5/5