第2章：记忆系统工程实践

2.1 为什么 AI 需要“记忆”

大模型在会话之间通常缺乏持久状态。每次开启新的 Claude Code 会话时，Claude 面对的都是一段全新的上下文：它不记得项目使用的框架、团队的代码风格、分支策略、CI 流程，也不记得上一轮会话中刚刚被纠正过的问题。

这并不是某个模型的缺陷，而是当前大模型的共性：每一轮对话都需要重新构建上下文。Claude 缺失的不是编码能力，而是项目上下文。

从软件工程角度看，这类似于“约定优于配置”的反面。Ruby on Rails 能提升开发效率，是因为它预设了一套明确约定，例如数据库表名使用复数、模型名使用单数、控制器放在 app/controllers 目录下。开发者只需要处理偏离约定的部分。

而 Claude 默认依赖的“约定”并不是项目规范，而是训练数据中的统计规律，也就是公开互联网代码的常见模式。例如，Express 比 Fastify 更常见，npm 比 pnpm 更普遍，JavaScript 的样本量也远大于 TypeScript。因此，在缺少项目上下文时，Claude 会倾向于选择最主流、最常见的方案。这些方案在通用场景下合理，但未必符合具体团队的规范。

解决思路是：为 Claude 准备一份项目级“入职手册”，让它每次启动时都能先读取项目规则。这份手册就是 CLAUDE.md。

CLAUDE.md 是一个 Markdown 文本文件，放在项目约定目录下后，Claude Code 会在启动时自动扫描并加载其中内容，将其作为系统上下文的一部分注入到对话前端。这样，Claude 在开始工作前就能了解项目规范，而不是靠猜测推断项目结构和团队习惯。

这一设计思路在软件工程中早已屡见不鲜。我们利用 .editorconfig 统一编辑器行为，借助 .eslintrc 规范代码风格，通过 tsconfig.json 约束 TypeScript 编译选项，依靠 .prettierrc 固化格式化规则。这些配置文件的本质，皆是将隐性的“团队约定”从人脑中外化为机器可读的声明式规则。

CLAUDE.md 也是同样的逻辑，只是它的读者不再是编译器、格式化工具或 Linter，而是具备自然语言理解能力的大模型。

这体现了 AI 时代的“配置驱动”思维：通过显式配置，让 AI 在执行任务前先获得准确的项目背景和行为边界。

虽然 Claude Code 可以主动读取项目文件，但单靠主动探查并不理想。一方面，读取文件会消耗工具调用次数和上下文窗口；另一方面，像 package.json 这样的文件只能说明项目依赖，无法完整表达架构决策、团队约定、编码偏好、业务规则等深层信息。

因此，CLAUDE.md 的核心价值在于：把分散在代码、文档和团队经验中的隐性知识集中整理成一份显性的指导文档，让 Claude 在编码前建立准确的项目心智模型。

2.2 五层记忆体系

“CLAUDE.md 应该放在哪里？”答案是：不止一个地方。

Claude Code 采用 五层记忆体系（Memory Hierarchy），这种设计与操作系统的配置加载机制有着异曲同工之妙：Linux 操作系统在读取配置时，会依次扫描 /etc/ 目录下的全局配置、用户主目录下的个人配置，以及当前目录下的项目配置，通过层层叠加实现逐步细化。

1. 企业级（Enterprise）

企业管理员统一配置，通常位于 /etc/claude-code/CLAUDE.md 或通过 Anthropic 企业后台管理。

常见规则：

  • 禁止向外部 API 发送代码
  • 必须通过 ORM 操作数据库
  • 禁止硬编码密钥

这是整个体系的最高优先级，属于不可绕过的合规约束。

个人开发者通常不会接触这一层。

2. 用户级（User）

配置位置 ~/.claude/CLAUDE.md 对当前机器上的所有项目生效。

适合存放个人长期偏好：

  • 回复使用中文
  • Git Commit 规范
  • 编码风格偏好
  • 常用命令映射

例如：

- 回复使用中文，代码注释使用英文
- 优先函数式编程
- 当我说“执行测试”时，自动执行 pnpmtest
- 当我说“启动服务”时，自动执行 pnpmdev

3. 项目级（Project）

配置位置 项目根目录/CLAUDE.md 这是最重要、最常用的一层。

特点：

  • 必须提交到 Git
  • 团队成员共享
  • 新成员 clone 项目即可自动获得项目上下文

通常记录：技术栈、目录结构、编码规范、常用命令、项目约定

可以把它理解为项目的《开发手册》。

4. 规则级（Rule）

配置位置 .claude/rules/ 用于拆分大型项目规则。

规则级是一项精巧的进阶设计，旨在解决“单一CLAUDE.md 难以承载所有复杂规则”的痛点。你可以在 .claude/rules/ 目录下部署多个独立的 Markdown 文件，使每个文件专注于一个特定主题（如数据库规
范、API设计风格或测试策略）。更为关键的是，该层级支持条件化触发机制：规则文件仅在操作特定文件或进人特定上下文时才会被动态加载，从而避免了无关信息对上下文的冗余占用。关于这一机制的深度解析与实战用法，我们将在2.4节中专门探讨。

最大的特点是：按需加载（Conditional Loading）。只有进入对应场景时才会加载相关规则，从而减少上下文占用。

5. 本地级（Local）

配置位置 CLAUDE.local.md

特点：

  • 自动加入 .gitignore
  • 不会提交到仓库
  • 仅自己可见

专为那些对个人极具价值但不宜共享的信息而设，如测试服务器的地址与端口、个人调试过程中积累的独家心得，或是临时性的工作备忘录等。

例如：

# 本地开发备忘
- 数据库连接：postgresql://dev:dev123@10.0.1.50:5432/orders_dev
- 维护窗口：每周三 22:00-23:00 进行数据库维护，严禁在此时段执行迁移操作
- 故障排除：遇到 CORS 报错时，优先检查 Nginx 配置（/usr/local/etc/nginx/nginx.conf）
- 联调配置：前端服务运行于 5173 端口，需要手动配置代理转发

规则冲突如何处理？

五层记忆采用的是：

叠加（Merge），而不是覆盖（Override）

Claude 会读取所有层级内容并合并理解。

当规则冲突时：越具体的规则优先级越高。

例如：

用户级：4 空格缩进
项目级：2 空格缩进

当前项目中会优先采用：

2 空格缩进

因为项目级比用户级更具体。

唯一例外是： 企业级规则具有强制约束力，无法被下层覆盖。

优先级可以理解为：企业级 → 用户级 → 项目级 → 规则级 → 本地级

（实际判断由 Claude 完成，但核心原则是**“具体性优先，企业级绝对优先**”。）

文件引用机制

CLAUDE.md 还内置了强大的文件引用机制。在任何层级的记忆文件中，均可使用 @path/to/file 语法引人其他文件的内容，从而实现配置的模块化组织。

特点：

  • 支持最多 5 层嵌套
  • 避免把所有内容堆进一个 CLAUDE.md

这样 CLAUDE.md 只负责索引，各专题文档负责具体规则，结构更加清晰、易维护。

2.3 CLAUDE.md 写作范式

理解了记忆文件的存储位置与层级职责后，更核心的命题浮出水面：如何撰写？

关键点：少即是多。

一次对话初始化时，被完整注入上下文窗口中。这意味着，你写的每一行文字，都会在每一次交互中消耗宝贵的 Token 配额。”

他打了一个生动的比方：“你可以将上下文窗口想象成一张空间有限的办公桌。桌面的面积是固定的。如果你在 Claude Code 开始实际工作之前，就在桌上堆满了厚厚的参考资料（即冗长的规则文件），那么留给真正需要处理的代码、文件和临时草稿的空间会所剩无几。一旦桌面被占满，Claude Code 就不得不‘扔掉’一些早期的关键信息以腾出空间，这往往导致它‘遗忘”重要的指令或上下文细节。”

这个比喻不仅形象，更有坚实的数据支撑。根据 Anthropic 的工程实践数据，Claude Code 的 System Prompt（系统提示词）已内置了约50条核心指令，这些构成了模型正常运行的“操作系统级”基石。

当用户自定义的 CLAUDE.md 内容加人后，若总指令数突破 150 条的临界值，模型对指令的遵循质量便会呈现显著衰减。其背后的逻辑是：指令密度与遵循概率成反比。指令越长繁杂，每一条规则被模型“深度关注”和“严格执行”的概率就越低。 在 AI 协作中，精简不仅是节省 Token 的手段，更是确保指令有效落地的关键策略。

那么，究竟什么内容值得写入 CLAUDE.md？可以由一个高效的“三问框架”作为筛选标准。

第一问：WHY（为什么这样做）

核心价值：赋予 Claude 模型“举一反三”的推理能力。

这类信息旨在揭示决策背后的底层逻辑，帮助 Claude 理解项目的核心关切。一旦掌握了“为什么”，即便遇到未被明确规定的边缘场景，模型也能基于原则进行正确推导。

示例：“我们选择 Fastify 而非 Express，因为 Fastify 的 schema-basedvalidation 与本项目‘类型安全优先’的战略一致。”

效果：当 Claude 理解了“类型安全”是最高优先级后，即便你在某处未指定库，它也会主动倾向于选择类型定义更完善的方案，而非仅仅机械地匹配关键词。

第二问：WHAT（做什么、不做什么）

核心价值：划定不可逾越的“行为边界”。

这是最直接、最刚性的行为指令，明确界定允许与禁止的范围。此类规则通常不需要解释原因，要求的是绝对的服从与执行。绝大多数项目规范属于此列。

示例：“必须使用 pnpm 作为包管理器；禁止使用 npm 或 yarn。

效果：建立清晰的“红线”，消除模型在工具选型上的不确定性，确保技术栈的统一性。

第三问：HOW（如何一步步做）

核心价值：固化“标准作业程序”。

这类内容适用于常用命令、固定流程或特定操作范式。模型不需要理解命令背后的复杂原理，只需要准确执行既定的步骤即可。

示例：执行数据库迁移请运行 pnpmdb:migrate；填充测试数据请运行 pnpm db:seed。

效果：将团队的最佳实践转化为模型的“肌肉记忆”，减少命令拼写错误或参数遗漏导致的低级失误，提升执行效率。

并非所有信息都需要同时回答这 3 个问题。大多数规则只需要在 WHAT 层面用一句话明确界定即可。只有那些容易被误解或者模型容易“好心办坏事”的关键决策，才值得补充 WHY 层面的深度解释。

如果你发现在自己的 CLAUDE.md 中，每一条规则后面都附带了一大段背景阐述或情感抒发，那通常意味着内容过载了。精简，才是高效协作的王道。

下面通过一个反面案例与后续的正面范例对比，帮助你快速建立直觉。

先来看一个反面案例：模糊的“正确的废话”。

# 项目说明

这是一个电商平台的后端服务，我们团队有5个人，项目从2024年3月开始开发。
使用 Node.js 编写，是一个 RESTfulAPI 服务。
代码要写得好一些，注意性能。
测试要全面。
请遵循最佳实践。

这份 CLAUDE.md 充满了人类社交语境下的客套话和模糊指令，对 AI 而言，几乎等同于无效信息。

  • “写得好一些”：好到什么程度？是符合 Prettier 格式，还是运用了设计模式?

  • “全面”：覆盖到哪些场景？是单元测试、集成测试，还是 E2E 测试？覆盖率要求是 80% 还是 100%？

  • “最佳实践”：是谁的最佳实践？

Claude 读完这段话，获得的可操作信息几乎为零。

尤其致命的是“遵循最佳实践”这条指令。它看似正确，实则空洞无物。因为 Claude 默认会尝试遵循它所认知的“最佳实践”（基于互联网海量数据训练的统计规律）。问题的核心恰恰在于：模型通用的“最佳实践”与你团队特定的“技术约定”之间往往存在偏差。

此外，“团队有5个人”“2024年3月开始开发”这类元数据，对代码生成逻辑没有任何指导意义，却白白占用了宝贵的上下文空间。

再看一个正面范例：精准的“操作手册”。

# 订单服务 API
## 技术栈
- Node.js 20 + TypeScript 5.3（严格模式）
- Fastify 4 框架（不使用 Express）
- Prisma ORM + PostgreSQL 15
- pnpm 8 包管理（不使用npm/yarn）
## 项目结构
- src/routes/     路由定义，只做参数解析和响应构造
- src/services/  业务逻辑层，所有核心逻辑在此
- src/repositories/    数据访问层，封装 Prisma 调用
- src/schemas/       Zod 验证 schema，与路由一一对应
## 关键约定
- API统一返回格式：{success：boolean，data?：T，error?：{code: string, message:string }}
- 错误码使用 UPPER_SNAKE_CASE，如 ORDER_NOT_FOUND
- 数据库表名 snake_case复数形式，主键UUID，必带created_at和updated_at
## 常用命令
pnpm dev            # 启动开发服务器，端口3000 
pnpm test           # 运行全部测试（vitest） 
pnpm build          # TypeScript 编译+类型检查 
pnpm db: migrate    # 执行 Prisma 数据库迁移

两份文件的差距一目了然。优秀的版本简洁、具体且具备高度可操作性，每一条规则都能直接锚定 Claude 模型的行为逻辑。

  • 技术栈锁定：看到“Fastify 4 框架（不使用 Express）”，Claude 会立即排除 Express 相关方案，直接生成基于 Fastify 的代码。

  • 架构规范落地：看到目录结构说明后，Claude 能精准判断新路由文件应置于 src/routes/目录下，而非随意堆砌。

  • 执行零误差：看到常用命令及其注释后，Claude 能准确执行构建与测试任务，杜绝了在 npm run build 还是 yarn build 之间盲目猜测的可能。

除手动编写以外，Claude Code 还提供了两个便捷工具来辅助管理记忆文件。

第一个是 /init 命令。在项目根目录执行该命令后，Claude Code 会自动扫描项目的目录结构、依赖配置文件（如 package.json、pyproject.toml、Cargo.toml 等）以及其他关键配置，随即生成一份 CLAUDE.md 初稿。这份初稿通常涵盖技术栈识别、目录结构概览和常用脚本命令，是一个极佳的起步基础。

然而，仍需要手动审查并补充 /init 无法自动推断的内容，如分层架构的具体约束、API 响应格式的统一约定、团队特有的命名规范等。

这些“隐性知识”仅存在于团队成员的脑海中，无法单纯从配置文件中提取，必须通过人工干预将其显性化，才能确保 AI 的行为完全符合团队预期。

第二个是 /memory 命令，用于在对话过程中动态更新记忆。执行该命令后，Claude Code 会弹出文件选择器，列出当前所有可用的记忆文件供你选择编辑。这些文件覆盖了不同的作用范围，具体如下表所示。

文件类型 路径 作用范围
项目记忆 ./CLAUDE.md 或 ./.claude/CLAUDE.md 团队共享：可纳入版本控制，适用于统一团队规范
用户记忆 ~/.claude/CLAUDE.md 个人全局：个人偏好配置，对当前用户的所有项目均生效
项目本地记忆 ./CLAUDE.local.md 个人局部：仅针对当前项目的个人偏好，通常会自动被 .gitignore 排除，避免提交至代码仓库

选中文件后，系统将在编辑器中直接打开它，供你即时修改。

假设你在交互中发现 Claude Code 再次误用了 moment.js，而项目规范明确要求使用 date-fns。此时，你不需要退出对话或手动查找文件，只需要执行以下步骤。

第1步，输入/memory 命令。

第2步，选择项目级的 CLAUDE.md。

第3步，追加规则：日期处理统一使用 date-fns，禁止使用 moment.js。

第4步，保存并关闭。

下次对话启动时，这条新规则即刻生效。若该偏好仅属于个人习惯而不愿影响团队，可选择写入 CLAUDE.local.md，该文件默认被·gitignore 排除，不会提交至代码仓库。

这一机制构建了一个 “犯错→纠正→记忆写入→避免再犯” 的良性闭环。随着时间的推移，你的记忆文件将愈发精准，Claude Code 在项目中的表现也将随之持续进化。

2.4 条件化规则系统

随着项目的演进，单一 CLAUDE.md 终将面临容量瓶颈。

当项目涵盖前端组件规范、后端 API 设计、数据库迁移流程、测试策略（覆盖率/mock）以及基础设施（Docker 和 CI/CD）等全部规则时，如果将所有内容堆砌在一个文件中，将引发两大核心问题。

  • 维护噩梦：文件变得极度冗长，查找和更新特定规则变得困难。

  • 注意力分散：例如，当 Claude 编写一个简单的前端组件时，其上下文被迫加载了数据库迁移规范和 CI 配置要求等无关信息，这些噪声会稀释模型的注意力，导致其在处理当前任务时效率下降，甚至产生幻觉或忽略关键的前端约束。

这正是 .claude/rules/ 目录的核心价值所在。它将记忆系统从“一本大而全的厚重手册”进化为“一个按需取用的模块化知识库”。

该机制具备两大核心优势。

  • 领域拆分：允许将庞大的规则集拆解为多个主题文件，每个文件专注于特定领域，极大地提高了可维护性。

  • 智能激活：通过在文件头部添加 YAML Frontmatter，利用 paths 字段声明 Glob 模式；只有当 Claude Code 操作的文件路径匹配该模式时，对应的规则才会被激活并注入上下文；在不匹配的场景下，这些规则文件安静地存储在磁盘上，不消耗任何 token 或上下文空间。

来看一个示例。若需要规范测试文件的编写，可创建如下规则文件。.claude/rules/testing.md

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
  - "tests/**"
---

# 测试规范
- 采用 `vitest` 作为测试框架，禁用 `jest`
- 每个测试文件必须包含 `describe` 代码块，且其名称需要与被测模块保持一致
- 模块模拟统一使用 `vi.mock()`，禁止手动 Mock
- 异步测试一律采用 `async/await` 语法，禁止使用 `done` 回调
- 测试数据需要通过 `factory` 函数生成，严禁在测试中硬编码

在此配置下，当 Claude 编辑 src/services/order-service.ts 时，该测试规范不会被加载；而一旦转向编写 tests/order-service.test.ts，这些规则即刻自动生效。这种“按需加载”的设计思路，与编程语言中的懒加载（Lazy Loading）理念一脉相承：不需要在启动时预载所有潜在资源，仅需要在真正需要时动态调用。

同样的思路可推广到其他开发领域。例如，数据库规范仅在操作 Prisma 文件或数据访问层时加载，而 API 设计规范则仅在编辑路由或 Schema 文件时生效。

.claude/rules/database.md 

---
paths:
  - "prisma/**"
  - "src/repositories/**"
---

# 数据库规范

- 迁移文件一旦提交至 `main` 分支，严禁修改，仅运行创建新迁移
- 所有查询必须经由 `repository` 层，`service` 层禁止直接调用 Prisma 客户端
- 批量操作必须包裹在事务中，单次写入超过 100 条记录时强制分批处理

.claude/rules/api-design.md 

---
paths:
  - "src/routes/**"
  - "src/schemas/**"
---

# API 设计规范

- 每个路由必须配置对应的 Zod schema 以进行入参验证
- 列表接口统一支持分页参数：
  - `page`（从 1 开始计数）
  - `limit`（默认 20，最大值 100）
- 错误响应结构必须包含：
  - 机器可读的 `code` 字段
  - 人类可读的 `message` 字段

这好比为企业不同岗位的员工量身定制了专属操作手册：前台遵循前台流程，仓库恪守仓库规范，不需要人人背诵全公司的制度。唯有当你步入仓库作业时，才需要翻开那本《仓库管理手册》。

这种模块化的规则组织方式另有一大实效：在多人协作场景下，各领域专家可独立维护其专属规则文件，从而大幅降低 Git 合并冲突的概率。前端工程师专责 frontend.md，后端工程师维护 api-design.md，DBA 把控 database.md，各司其职，互不干扰。随着团队规模的扩张，这种‘分而治之’策略的价值将愈发凸显。

**若规则文件未配置 paths 前置元数据，系统将视其为全局无条件规则，在每次会话中强制加载一其效果等同于直接写入 CLAUDE.md 主文件。**因此，务必为每个规则文件设定精准的 paths 限定，方能真正发挥记忆系统“按需加载”的核心优势。

2.5 实战: 3种典型项目配置

理论阐述至此，让我们通过 3 种典型项目的 CLAUDE.md 实战写法来融会贯通。请留意它们在侧重点上的显著差异。

  • 前端项目：围绕组件规范与状态管理策略展开。

  • 后端项目：聚焦分层架构设计与 API 约定。

  • 数据项目：强调数据处理流程严谨性与实验复现规范。

这些差异绝非偶然，它们精准反映了不同技术领域中“最高频出错点”的分布。优秀的 CLAUDE.md 应当像精确制导武器，将火力集中覆盖在那些最容易引发问题的关键地带。

2.5.1 React 前端项目配置

在 React 前端项目中，组件粒度划分、状态归属以及样式方案选择往往是分歧的“重灾区”，也是Claude最容易“自作主张”导致代码风格割裂的地方。若未明确指定状态管理策略，Claude 极有可能在同一项目中混用 Redux、ContextAPI 和本地 State，造成架构混乱。

以下是一份针对电商平台前端项目的 CLAUDE.md 实战范例。

# 电商平台前端项目规范

## 技术栈

- 核心：React 18 + TypeScript（严格模式）
- 构建 / 包管理：Vite 5 + pnpm
- 状态管理：
  - 服务器状态：TanStack Query（React Query）
  - 客户端全局状态：Zustand
- 样式方案：Tailwind CSS（严禁使用 CSS Modules 或 styled-components）

## 组件规范

- 范式：仅使用函数组件 + Hooks，禁止 class 组件
- 命名：
  - 文件采用 PascalCase（如 `ProductCard.tsx`）
  - Props 类型命名为组件名 + Props（如 `ProductCardProps`）
- 目录结构：
  - 通用 UI 原子组件 → `src/components/ui/`
  - 业务领域组件 → `src/components/features/`

## 状态管理决策树

- 服务器数据（API 响应、缓存、同步）→ TanStack Query
- 全局客户端状态（主题切换、用户登录态、购物车临时态）→ Zustand
- 组件局部状态（表单输入值、Dropdown 展开/折叠、Modal 显示）→ `useState`

## 常用命令

```bash
pnpm dev      # 启动开发服务器，端口 5173
pnpm build    # 生产环境构建
pnpm test     # 运行 vitest 单元测试
pnpm lint     # ESLint 代码检查
```

请注意其中 “状态管理决策树” 这一部分，它不仅仅是罗列技术栈名称，而是构建了 “场景到工具的映射逻辑” 。这种 “决策指导” 远比单纯的工具清单有效得多，它直接告诉 Claude 在遇到具体问题时“该选哪把钥匙”，从而在源头上杜绝了架构风格的飘忽问题。

2.5.2 Node.js 后端项目配置

Node.js 后端项目的核心命脉在于分层架构的职责边界与数据格式的统一。后端代码的“正确性”往往取决于各层之间是否严守依赖规则—如果 route 层直接调用 Prisma，绕过了 service 层和 repository 层，业务逻辑便会泄漏到基础设施层，导致后续维护陷人泥潭。

以下是一份针对订单微服务的 CLAUDE.md 实战范例。

# 订单微服务后端规范

## 技术栈

- 运行时：Node.js 20 + TypeScript 5.3
- 框架：Fastify 4（严禁使用 Express）
- 数据库：Prisma ORM + PostgreSQL 15
- 工具链：pnpm（包管理）、Zod（数据验证）

## 分层架构（严格单向依赖）

- `routes/`
  - 解析请求参数
  - 校验输入
  - 调用 controller
  - 构造 HTTP 响应

- `controllers/`
  - 编排 service 调用
  - 处理 HTTP 语义
  - 异常捕获与转换

- `services/`
  - 核心业务规则实现
  - 事务控制
  - 多 repository 协调

- `repositories/`
  - 封装 Prisma 查询
  - 数据映射
  - 严禁其他层级直接调用 Prisma

## API 响应标准

所有接口必须统一返回格式：

```ts
{
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
  };
}
```

### 分页规范

- `page`（从 1 开始）
- `limit`（默认 20，最大值 100）

### 错误码规范

- 必须使用 `UPPER_SNAKE_CASE` 格式

## 常用命令

```bash
pnpm dev         # 启动开发服务器，端口 3000
pnpm test        # 运行 vitest 测试套件
pnpm build       # tsc 编译
pnpm db:migrate  # 执行 Prisma 数据库迁移
pnpm db:studio   # 启动 Prisma Studio 可视化界面
```

在此配置中，最具核心价值的一条规则莫过于 “严禁其他层级直接调用 Prisma” 。这绝非单纯的代码风格偏好，而是一条不可逾越的架构铁律，它直接决定了项目的可维护性与生命力。

2.5.3 Python 数据项目配置

Python 数据项目呈现出与 Web 开发截然不同的面貌。若 Claude 不了解数据科学领域的工程习惯，极易生成违背最佳实践的代码，例如，滥用 inplace=True 来修改 DataFrame，破坏了数据流的可追溯性；或者，混用 None 与 pd.NA，导致缺失值处理逻辑混乱。

以下是一份针对用户行为分析系统的 CLAUDE.md 实战范例。

# 用户行为分析系统规范

## 技术栈

- 环境：Python 3.11 + uv（管理依赖与虚拟环境）
- 核心库：
  - 数据处理：pandas 2.x
  - 机器学习：scikit-learn
  - 可视化：matplotlib + seaborn
- 代码规范：
  - 类型标注：严格使用 `typing` 模块
  - 文档字符串：强制采用 Google Style

## 项目结构

- `notebooks/`
  - 探索性数据分析（Jupyter）
  - 命名格式为 `"序号-描述.ipynb"`
  - 例如：`01-数据探索.ipynb`

- `src/data/`
  - 数据加载、清洗与管道构建

- `src/features/`
  - 特征工程逻辑

- `src/models/`
  - 模型定义、训练流程与评估指标

- `tests/`
  - pytest 单元测试套件

## 数据处理约定

- 缺失值：
  - 统一使用 `pd.NA`
  - 禁止使用 `None` 或裸用的 `np.nan`

- 日期列：
  - 统一转换为 `datetime64` 类型
  - 输出/存储格式为 `YYYY-MM-DD`

- 内存优化：
  - 低基数的分类变量必须显式转换为 `category` 类型

- DataFrame 操作：
  - 禁止使用 `inplace=True`
  - 所有转换操作必须返回新的 DataFrame 副本

## 常用命令

```bash
uv sync                      # 安装/同步依赖环境
uv run pytest                # 运行测试套件
uv run jupyter lab           # 启动 Jupyter Lab
uv run python -m src.train   # 执行模型训练脚本
```

这3份文件的篇幅均控制在二三十行，但字字珠玑，每一行都是‘干货”。它们摒弃了 Claude 早已熟知的通用知识，你不需要向它解释什么是 React，也不必赘述 Python 的缩进规则，而是精准聚焦于特定领域与本项目独有的约定和抉择。

这正是 CLAUDE.md 写作的核心法则：只记录那些 Claude 必须知晓、却无法自行推断的关键信息。请牢记一条黄金检验标准：如果删去某条规则后，Claude 依然能做出正确的行为，那么这条规则不该出现在 CLAUDE.md 中。

本章小结

回到本章开篇的场景：小冰每次开启全新会话时，Claude 总是习惯性地用 Express 替代 Fastify，用 npm 替代 pnpm。现在我们明白，这并非 Claude 模型的能力缺陷，而是因为它缺失了一份关键的“入职手册”。

CLAUDE.md 正是解决这一痛点的关键机制。它将团队的技术选型、编码规范、项目结构以及常用命令，固化为一份 Claude 可读的配置文档。每当会话启动时，Claude Code 便会自动加载这些信息，从而彻底跳过那些反复纠正的无效沟通，直接进入高效协作状态。

五层记忆体系的设计，深刻体现了软件工程中“关注点分离”的经典原则。

  • 企业级：严守安全底线，由组织统一管理。

  • 用户级：沉淀个人偏好，尊重个体差异。

  • 项目级：承载团队共识，确保协作一致。

  • 规则级：实现规则的模块化与条件化加载。

  • 本地级：容纳私人备忘，提供灵活的临时上下文。

每一级均拥有明确的职责边界与管理主体，既有力支撑了团队协作，又充分尊重个人习惯。

其中，条件化规则系统更是一项精巧的工程设计。它利用 Glob 模式精准限定规则的作用域，实现了“在恰好的时刻，将恰当的信息投递给上下文” 的智能化机制。这种设计彻底摒弃了将所有规则一股脑倾倒在 Claude 面前的粗放模式，确保了上下文的纯净与高效。

关于写作范式，“少即是多”绝非一句空洞的口号，其背后有着严肃的技术原理支撑。

上下文窗口是模型最稀缺的战略资源，每一个 Token 都承载着高昂的机会成本。

将无关信息强行塞人 CLAUDE.md，无异于在高峰期的地铁车厢里硬塞进不需要乘车的乘客——这不仅占用了宝贵的空间，更导致真正需要上车的“关键信息”被挤在门外，无法进人模型的视野。

一份优秀的 CLAUDE.md 应当像一份精炼的作战备忘录，严格遵循以下3条铁律。

  • 必要性：每一条都是 Claude 必须知道且无法自行推断的信息。

  • 可操作性：每一条都是具体、明确且可执行的指令。

  • 脆弱性测试：每一条若被删去，都会直接导致 Claude 犯错或偏离预期。

在第3章中，我们将正式踏人 Skills 的广阔世界。如果说 CLAUDE.md 是赋予 Claude 基础认知的“入职手册”，那么 Skills 则是为其量身定制的“专业培训教材”。

当你的“入职手册”变得日益臃肿，试图将庞杂的领域知识全部塞人其中时，不仅会导致上下文资源的浪费，更会降低核心规则响应效率。此时，你就需要一种更优雅、更智能的按需加载机制，这正是 Skills 系统的核心价值：让专业知识在真正需要的那一刻，精准地注入对话上下文中。