CLAUDE.md 项目规范

当你开始认真使用 Claude Code 时，会发现两个问题：单个 CLAUDE.md 文件变得臃肿，超过 200 行后 Claude 遵守度下降；有些知识你不需要手动写，Claude 完全可以从工作中自动学习。今天我们来解决这两个问题。

简介

Claude Code 提供了两套互补的机制来解决项目规范管理问题：

.claude/rules/ 规则拆分系统

自动记忆系统

为什么需要 .claude/rules/

单文件的问题

想象一下这个场景：你的项目有 50 行技术栈说明、30 行 TypeScript 规则、40 行 React 规范、25 行测试要求、20 行 API 设计指南……

一个 CLAUDE.md 文件超过 200 行后，会出现什么问题？

• 上下文消耗增加：每次会话都要加载整个文件
• 遵守度下降：Claude 可能遗漏重要规则
• 团队协作困难：多人维护一个文件容易冲突

规则拆分的优势

使用 .claude/rules/ 目录拆分规则后：

1.claude/
2├── CLAUDE.md           # 核心配置（50 行）
3└── rules/
4    ├── typescript.md   # TypeScript 规则（50 行）
5    ├── react.md        # React 规则（40 行）
6    ├── testing.md      # 测试规则（30 行）
7    └── api/            # 按主题分组
8        └── design.md   # API 设计规则（25 行）

效果：

• 主文件清晰，快速浏览
• 各主题独立维护
• 按需加载，节省上下文
• 团队分工明确

.claude/rules/ 详解

基本设置

第一步：创建规则目录

1mkdir -p .claude/rules

第二步：创建规则文件

每个文件应涵盖一个主题，使用描述性文件名：

1your-project/
2├── .claude/
3│   ├── CLAUDE.md           # 主项目指令
4│   └── rules/
5│       ├── code-style.md   # 代码样式指南
6│       ├── testing.md      # 测试约定
7│       └── security.md     # 安全要求

加载顺序：

• 没有 paths frontmatter 的规则在启动时加载
• 优先级与 .claude/CLAUDE.md 相同

路径特定规则

这是 .claude/rules/ 最强大的功能：让规则只在处理特定文件时生效。

问题场景

你的项目有前端和后端代码，它们有不同的规范：

如果把所有规则放在一个文件，处理前端代码时会加载后端规则（浪费上下文），反之亦然。

解决方案

使用 YAML frontmatter 的 paths 字段限定规则范围：

 1---
 2paths:
 3  - "src/api/**/*.ts"
 4---
 5
 6# API 开发规则
 7
 8- 所有 API 端点必须包括输入验证
 9- 使用标准错误响应格式
10- 包括 OpenAPI 文档注释

效果：只有处理 src/api/**/*.ts 文件时，这些规则才会加载。

Glob 模式参考

多模式匹配

你可以指定多个模式，使用大括号扩展匹配多个扩展名：

1---
2paths:
3  - "src/**/*.{ts,tsx}"
4  - "lib/**/*.ts"
5  - "tests/**/*.test.ts"
6---
7
8# TypeScript 和测试规则
9...

使用符号链接跨项目共享规则

如果你有多个项目，维护多份相同的规则很麻烦。.claude/rules/ 支持符号链接：

1# 链接整个共享目录
2ln -s ~/shared-claude-rules .claude/rules/shared
3
4# 链接单个文件
5ln -s ~/company-standards/security.md .claude/rules/security.md

特性：

• 符号链接被正常加载
• 循环符号链接被检测并处理
• 适合维护公司级标准

用户级规则

~/.claude/rules/ 中的个人规则适用于所有项目：

1~/.claude/rules/
2├── preferences.md    # 你的个人编码偏好
3└── workflows.md      # 你的首选工作流

加载顺序：用户级规则在项目规则之前加载

优先级：项目规则更高（可以覆盖用户级规则）

适合放什么：

• 跨项目的个人偏好（如 2 空格缩进）
• 个人工具习惯（如优先使用 pnpm）
• 沟通风格（如中文回复、英文注释）

自动记忆系统详解

什么是自动记忆

定义：Claude 在工作时为自己保存笔记，无需你手动编写。

Claude 会记录：

• 构建命令（如 npm run dev、cargo build）
• 调试见解（如"这个错误通常是因为…"）
• 架构笔记（如"数据流经过这里…"）
• 代码样式偏好（如"这个项目用 camelCase"）
• 工作流习惯（如"测试前需要启动 Redis"）

存储位置

每个项目在 ~/.claude/projects/<project>/memory/ 获得自己的记忆目录：

1~/.claude/projects/<project>/memory/
2├── MEMORY.md          # 简洁索引，加载到每个会话
3├── debugging.md       # 关于调试模式的详细笔记
4├── api-conventions.md # API 设计决策
5└── ...                # Claude 创建的任何其他主题文件

<project> 路径来源：

• 在 git 仓库中：基于 git 仓库路径
• 同一仓库的所有 worktrees 和子目录共享一个自动记忆目录
• 在 git 仓库外：使用项目根目录

工作原理

加载机制

关键点：

• MEMORY.md 的前 200 行在每次对话开始时加载
• 第 200 行之后的内容在会话开始时不加载
• 主题文件在启动时不加载，Claude 按需读取

Claude 如何保持 MEMORY.md 简洁

通过将详细笔记移到单独的主题文件中：

 1# MEMORY.md（简洁索引）
 2
 3## 构建命令
 4- 启动：`npm run dev`
 5- 构建：`npm run build`
 6
 7## 调试笔记
 8详见 @debugging.md
 9
10## API 约定
11详见 @api-conventions.md

你会看到的提示

在 Claude Code 界面中，你可能看到：

• "Writing memory"：Claude 正在更新记忆文件
• "Recalled memory"：Claude 正在读取记忆文件

启用或禁用

默认状态：开启

方法一：通过 /memory 切换

在会话中输入 /memory，使用自动记忆切换。

方法二：通过项目设置

1{
2  "autoMemoryEnabled": false
3}

方法三：通过环境变量

1export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

审计和编辑

一切都是纯 markdown，你可以随时编辑或删除。

查看记忆

运行 /memory 命令：

• 列出所有加载的 CLAUDE.md 和规则文件
• 切换自动记忆开关
• 提供打开自动记忆文件夹的链接

直接编辑

选择任何文件在你的编辑器中打开它：

1# 打开当前项目的记忆
2code ~/.claude/projects/$(basename $(pwd))/memory/

什么时候需要手动编辑？

• Claude 记错了，需要更正
• 想删除不再相关的旧笔记
• 想重组记忆结构

CLAUDE.md vs 自动记忆

核心建议：

• 指导 Claude 行为 → 使用 CLAUDE.md
• 让 Claude 从更正中学习 → 依赖自动记忆

典型工作流

场景一：新项目开始

1# 1. 使用 /init 自动生成基础 CLAUDE.md
2/init
3
4# 2. 根据项目特点，拆分到 rules/
5mkdir -p .claude/rules

场景二：工作中发现规律

1# 你告诉 Claude："这个项目总是用 pnpm，不是 npm"
2# Claude 自动保存到自动记忆
3
4# 如果你想确保它遵守所有命令：
5# 明确告诉 Claude："将其添加到 CLAUDE.md"

场景三：团队协作

1# 项目级规则（团队共享）
2.claude/rules/typescript.md
3
4# 用户级规则（个人偏好）
5~/.claude/rules/preferences.md
6
7# 自动记忆（Claude 自己学习）
8~/.claude/projects/<project>/memory/

高级技巧

规则优先级

当多个规则文件可能适用时，优先级是：

1具体路径规则 > 通用规则 > 用户级规则

示例：

大型团队管理

排除无关的 CLAUDE.md

在大型 monorepos 中，其他团队的 CLAUDE.md 可能被拾取。

使用 claudeMdExcludes 跳过它们：

1{
2  "claudeMdExcludes": [
3    "**/monorepo/CLAUDE.md",
4    "/home/user/monorepo/other-team/.claude/rules/**"
5  ]
6}

组织级规则

1# 部署组织范围的 CLAUDE.md
2# macOS
3sudo vim "/Library/Application Support/ClaudeCode/CLAUDE.md"
4
5# Linux 和 WSL
6sudo vim /etc/claude-code/CLAUDE.md
7
8# Windows
9notepad "C:\Program Files\ClaudeCode\CLAUDE.md"

与 Settings 配合

Claude Code 的设置文件也支持记忆相关配置：

1{
2  "autoMemoryEnabled": true,
3  "claudeMdExcludes": [
4    "**/node_modules/**"
5  ]
6}

实战案例

案例 1：Monorepo 中的规则组织

项目结构：

1company-monorepo/
2├── frontend/
3│   └── .claude/rules/react.md
4├── backend/
5│   └── .claude/rules/api.md
6└── shared/
7    └── .claude/rules/typescript.md

效果：

• 前端开发者只加载前端规则
• 后端开发者只加载后端规则
• 共享规则（如 TypeScript）在 shared/ 中

案例 2：个人偏好 + 项目规则

用户级规则（~/.claude/rules/prefs.md）：

1# 我的个人偏好
2
3## 代码风格
4- 使用 2 空格缩进
5- Git commit message 用英文
6
7## 工具偏好
8- 优先使用 pnpm 而非 npm

项目规则（.claude/rules/typescript.md）：

 1---
 2paths:
 3  - "src/**/*.ts"
 4---
 5
 6# TypeScript 规则
 7
 8## 必须
 9- 启用 strict 模式
10- 禁止使用 any 类型

效果：处理 src/**/*.ts 文件时，项目规则覆盖个人偏好。

案例 3：自动记忆的实际用途

场景：你在调试一个复杂的多服务应用。

Claude 记住了：

 1# MEMORY.md
 2
 3## 调试笔记
 4
 5### API 超时问题
 6- 通常是因为 Redis 未启动
 7- 检查：`redis-cli ping`
 8- 启动：`brew services start redis`
 9
10### 数据库迁移
11- 迁移前先备份数据库
12- 使用 `npm run migrate:down` 回滚

下次遇到类似问题时，Claude 会直接回忆起这些经验。

常见问题

Q：Claude 不遵循我的规则怎么办？

调试步骤：

1. 运行 /memory 验证规则被加载
2. 检查路径：文件是否在正确的位置？
3. 检查路径特定规则：glob 模式是否匹配当前文件？
4. 检查冲突：是否有多个规则文件提供不同指导？
5. 使指令更具体："使用 2 空格缩进" 比 "格式化代码好"

Q：路径特定规则没有生效？

检查清单：

• glob 模式是否正确？
• 文件路径是否真的匹配？
• YAML frontmatter 格式是否正确？
• 文件是否以 .md 结尾？

调试命令：

1# 检查 Claude 看到哪些文件
2/memory
3
4# 手动测试 glob 模式
5ls -la src/api/**/*.ts

Q：自动记忆保存了错误的内容？

解决：

1. 运行 /memory 打开记忆文件夹
2. 找到错误的笔记
3. 编辑或删除
4. 告诉 Claude 正确的信息，它会更新记忆

Q：MEMORY.md 超过 200 行了怎么办？

Claude 会自动处理：

Claude 通过将详细笔记移到单独的主题文件中来保持 MEMORY.md 简洁。

你也可以手动重组：

1# MEMORY.md（保持简洁）
2
3## 核心规则
4...
5
6## 详细笔记
7- 调试：@debugging.md
8- API：@api-conventions.md

最佳实践

规则组织

推荐做法：

• 每个规则文件专注一个主题
• 使用描述性文件名
• 路径特定规则用于特定文件类型
• 共享规则用符号链接

避免：

• 一个文件包含太多主题
• 文件名不清晰（如 rules1.md、stuff.md）
• 复制粘贴相同内容到多个文件

自动记忆

推荐做法：

• 让 Claude 自然学习
• 定期审计记忆内容
• 手动更正错误的记忆

避免：

• 过度依赖自动记忆（核心规则应在 CLAUDE.md）
• 从不查看 Claude 记住了什么
• 在机器间同步记忆文件（可能导致冲突）

团队协作

推荐做法：

• 项目规则通过 Git 管理
• 个人规则用 ~/.claude/rules/
• 使用符号链接共享公司级标准

避免：

• 将个人偏好提交到项目 CLAUDE.md
• 在团队中硬编码本地路径（如 /Users/username/...）

总结

.claude/rules/ 的核心价值

• 模块化维护
• 路径特定规则节省上下文
• 符号链接支持跨项目共享
• 用户级规则适用于所有项目

自动记忆的核心价值

• Claude 自动学习，无需手动编写
• 记录构建命令、调试见解等实战经验
• 通过 200 行限制保持高效

两者配合

• CLAUDE.md 和 rules/ 用于指导行为
• 自动记忆用于从经验中学习

参考资源

• Claude Code 官方文档
• Claude Code 记忆体系详解
• 真正会用 Claude Code 的人，都先做这一步