记忆层：为AI构建项目的“地基”

建筑的地基决定了整栋大楼的承载上限。Claude Code的记忆层亦是如此——它直接定义了Claude对项目“理解”的深度。

为什么需要记忆？

大模型本质上是无状态的。每次开启新对话，它对项目背景、技术栈选择、代码规范及团队约定均一无所知。如果未进行任何配置，我在每次开发时都要反复重申“使用XxxUI组件库，禁止使用ElementUI”、“优先平台xxx工具类”、“前端是Vue2，babel版本较低不能用某语法”等基础设定，还要附上长篇参考文档。这种如同“每日入职”般重复自我介绍的模式，低效得令人疲惫。

这是大模型的根本特征：会话间缺乏持久状态。每当你关闭一个Claude Code会话并开启新会话，Claude面对的都是完全空白的画布。它不记得项目框架、团队代码风格偏好，甚至不记得5分钟前你纠正过的错误。这并非某个特定模型的缺陷，而是当前所有大模型的共性——每一轮对话都必须从零构建上下文。

五层记忆体系

各层职责逐层剖析

Layer 0 · 企业策略层
构成了整个体系的“天花板”，也是开发者通常无法触及的层级。由公司IT管理员通过系统级配置文件（Linux中通常为/etc/claude-code/CLAUDE.md）或Anthropic企业管理后台统一设定。典型策略包括：禁止将代码发送至外部API、所有数据库操作必须经由ORM执行、严禁在代码中硬编码密钥等。这一级确立了企业级的合规底线——无论开发者在下面4层如何配置，均无法绕过此处的强制约束。对个人开发者和小型团队而言，该层级通常为空白，无需特别关注。

Layer 1 · 用户层
相当于“个人偏好档案”，位于~/.claude/CLAUDE.md，对这台机器上打开的所有项目均生效。适合存放与具体业务逻辑无关但体现个人工作习惯的通用偏好，如交流语言选择（中文或英文）、Git提交信息格式规范、个人常用快捷指令等。这些偏好高度稳定，不会因项目切换而改变。

Layer 2 · 项目层
日常开发中使用率最高的层级，是本章的主角。体现为项目根目录下的CLAUDE.md，必须提交至Git仓库，成为项目代码资产的一部分。

Layer 3 · 规则目录层
一项精巧的进阶设计，解决“单一CLAUDE.md难以承载所有复杂规则”的痛点。你可以在.claude/rules/目录下部署多个独立的Markdown文件，每个专注于特定主题（如数据库规范、API设计风格或测试策略）。更关键的是，该层级支持条件化触发机制——规则文件仅在操作特定文件或进入特定上下文时才会被动态加载，避免无关信息对上下文的冗余占用。

Layer 4 · 本地层
开发者的“私人便签”，对应CLAUDE.local.md。该文件不会被提交至Git仓库（Claude Code会自动将其纳入.gitignore），专为个人有价值但不宜共享的信息而设，如测试服务器地址与端口、个人调试心得、临时性工作备忘录等。

文件引用机制

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

例如，在项目层的CLAUDE.md中写入@docs/api-conventions.md，Claude便会自动加载并解析API约定文档。该机制支持最多五层嵌套递归，足以应对绝大多数复杂项目的组织需求。

这为大型项目提供了优雅的文档治理方案：CLAUDE.md不再承载所有细节，而是作为“索引总纲”，灵活指向各专题文档，避免海量信息堆砌于单一文件，让配置结构更清晰、可维护。

分级设计的工程思想

这种分级设计的工程思想，与CSS的层叠优先级机制、软件配置中“全局—用户—项目—本地”的四级覆盖模式如出一辙：每一级均可覆盖上一级的设定，层级越具体（如本地级），优先级越高。

CLAUDE.md 写作范式

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

“CLAUDE.md的内容具有全局持久性，它会在每一次对话初始化时，被完整注入上下文窗口中。这意味着，你写的每一行文字，都会在每一次交互中消耗宝贵的Token配额。”

根据Anthropic的工程实践数据，Claude Code的System Prompt已内置约50条核心指令——这些构成了模型正常运行的“操作系统级”基石。当用户自定义的CLAUDE.md内容加入后，若总指令数突破150条临界值，模型对指令的遵循质量便会呈现显著衰减。其背后的逻辑是：指令密度与遵循概率成反比。指令越冗长繁杂，每条规则被模型“深度关注”和“严格执行”的概率就越低。

高效“三问框架”

那么，什么内容值得写入CLAUDE.md？这里提供一个高效的“三问框架”作为筛选标准：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

反面案例 vs 正面范例

❌ 反面案例：模糊的“正确的废话”

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

问题分析：

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

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

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

尤其致命的是“遵循最佳实践”这条指令。Claude默认会尝试遵循它所认知的“最佳实践”（基于互联网海量数据训练的统计规律），但模型通用的“最佳实践”与团队特定的“技术约定”之间往往存在偏差。而“团队有5个人”“2024年3月开始开发”这类元数据，对代码生成逻辑毫无指导意义，却白白占用宝贵的上下文空间。

✅ 正面范例：精准的“操作手册”

# 订单服务 API

## 技术栈
- Node.js + TypeScript（严格模式）
- Fastify 框架（不使用 Express）
- Prisma ORM + PostgreSQL
- pnpm 包管理（不使用 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数据库迁移

优势分析：

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

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

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

两个辅助工具

/init 命令：在项目根目录执行后，Claude Code会自动扫描项目目录结构、依赖配置文件（如package.json、pyproject.toml、Cargo.toml等）及其他关键配置，随即生成一份CLAUDE.md初稿，涵盖技术栈识别、目录结构概览和常用脚本命令。但仍需手动审查并补充/init无法自动推断的内容，如分层架构的具体约束、API响应格式的统一约定、团队特有的命名规范等——这些“隐性知识”仅存在于团队成员脑海中，必须通过人工干预显性化。

/memory 命令：用于在对话过程中动态更新记忆。执行后，Claude Code会弹出文件选择器，列出当前所有可用的记忆文件供你选择编辑。选中文件后，系统在编辑器中直接打开供即时修改。

典型场景：假设在交互中发现Claude Code再次误用了moment.js，而项目规范明确要求使用date-fns。只需：

1. 输入/memory命令

2. 选择项目级的CLAUDE.md

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

4. 保存并关闭——下次对话启动时，这条新规则即刻生效

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

条件化规则系统

随着项目演进，单一CLAUDE.md终将面临容量瓶颈。当项目涵盖前端组件规范、后端API设计、数据库迁移流程、测试策略及基础设施等全部规则时，将所有内容堆砌在一个文件中将引发两大核心问题：

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

• 注意力分散：编写前端组件时，上下文被迫加载数据库迁移规范和CI配置要求等无关信息，这些噪声稀释模型注意力，导致效率下降甚至忽略关键约束

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

两大核心优势

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

智能激活：通过在文件头部添加YAML Frontmatter，利用paths字段声明Glob模式；只有当Claude Code操作的文件路径匹配该模式时，对应规则才会被激活并注入上下文。

示例：测试规范

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

# 测试规范
使用 vitest 作为测试框架，不使用 jest
每个测试文件必须包含 describe 块，describe 名称与被测模块一致
使用 vi.mock() 进行模块模拟，不使用手动 mock
异步测试统一使用 async/await，不使用 done 回调
测试数据使用 factory 函数生成，不在测试中硬编码

在此配置下，当Claude编辑src/services/order-service.ts时，该测试规范不会被加载；而一旦转向编写tests/order-service.test.ts，这些规则即刻自动生效。

同样思路可推及数据库规范（仅在操作Prisma文件或数据访问层时加载）、API设计规范（仅在编辑路由或Schema文件时生效）等场景。

多⼈协作优势：各领域专家可独立维护其专属规则文件，大幅降低Git合并冲突概率。前端工程师专责frontend.md，后端工程师维护api-design.md，DBA把控database.md——各司其职，互不干扰。

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

实战：3种典型项目配置

1. React 前端项目

# React 电商前端

## 技术栈
React 18 + TypeScript
Vite 构建工具
TanStack Query (数据获取)
Zustand (状态管理)
Tailwind CSS (样式)
React Router v6 (路由)

## 目录结构
src/
├── components/      # 可复用组件
│   ├── ui/         # 基础 UI 组件
│   └── features/   # 功能组件
├── pages/          # 页面组件
├── hooks/          # 自定义 Hooks
├── stores/         # Zustand stores
├── api/            # API 调用
├── types/          # TypeScript 类型
└── utils/          # 工具函数

## 编码规范
### 组件规范
- 使用函数组件 + Hooks
- Props 使用 interface 定义，命名为 ComponentNameProps
- 组件文件使用 PascalCase：ProductCard.tsx
- 每个组件一个目录，包含 index.tsx 和样式

### 状态管理
- 全局状态使用 Zustand
- 服务器状态使用 TanStack Query
- 本地状态使用 useState/useReducer

### 样式规范
- 使用 Tailwind 工具类
- 复杂样式抽取为组件
- 响应式使用 sm/md/lg/xl 断点

## 常用命令
pnpm dev          # 启动开发服务器
pnpm build        # 构建生产版本
pnpm test         # 运行测试
pnpm lint         # 代码检查
pnpm preview      # 预览构建结果

## API 集成
基础 URL: import.meta.env.VITE_API_URL
使用 axios 实例，配置在 src/api/client.ts
所有 API 调用封装在 src/api/ 目录

## Git 规范
Commit: type(scope): message
分支: feature/, bugfix/, hotfix/*
PR 必须通过 CI 检查

其中“状态管理决策树”不仅仅是罗列技术栈名称，而是构建了“场景到工具的映射逻辑”——这种“决策指导”远比单纯工具清单有效，直接在源头杜绝了架构风格漂移问题。

2. Node.js 后端项目

# 订单服务 API

## 概述
订单微服务，处理订单创建、支付、发货等业务逻辑。

## 技术栈
Node.js 20 + TypeScript
Fastify (Web 框架)
Prisma (ORM)
PostgreSQL (主数据库)
Redis (缓存 + 消息队列)
Zod (数据验证)

## 目录结构
src/
├── routes/         # 路由定义
├── controllers/    # 请求处理
├── services/       # 业务逻辑
├── repositories/   # 数据访问
├── schemas/        # Zod schemas
├── middlewares/    # 中间件
├── utils/          # 工具函数
└── types/          # 类型定义

prisma/
├── schema.prisma   # 数据库模型
└── migrations/     # 迁移文件

## API 规范
### 响应格式
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
  };
  meta?: {
    page: number;
    limit: number;
    total: number;
  };
}

### 错误码
ORDER_NOT_FOUND - 订单不存在
INVALID_STATUS - 状态转换无效
PAYMENT_FAILED - 支付失败
STOCK_INSUFFICIENT - 库存不足

### 端点命名
GET    /api/v1/orders          # 订单列表
GET    /api/v1/orders/:id      # 订单详情
POST   /api/v1/orders          # 创建订单
PUT    /api/v1/orders/:id      # 更新订单
DELETE /api/v1/orders/:id      # 取消订单
POST   /api/v1/orders/:id/pay  # 支付订单

## 数据库规范
表名使用 snake_case 复数形式
主键统一使用 UUID
必须有 created_at, updated_at 字段
软删除使用 deleted_at 字段

## 认证
JWT Bearer Token
Token 通过 Authorization header 传递
公开端点在路由中标记 { auth: false }

## 常用命令
pnpm dev              # 启动开发服务器
pnpm build            # 构建
pnpm start            # 生产启动
pnpm test             # 运行测试
pnpm prisma migrate   # 运行迁移
pnpm prisma generate  # 生成 Prisma Client

3. Python 数据项目

# 用户行为分析系统规范

## 技术栈
- 环境：Python + uv（管理依赖与虚拟环境）
- 核心库：
  - 数据处理：pandas
  - 机器学习：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
- 日期列：统一转换为 datetime 类型，输出/存储格式为 YYYY-MM-DD
- 内存优化：低基数的分类变量必须显式转换为 category 类型
- DataFrame：禁止使用 inplace=True，所有转换操作必须返回新的 DataFrame 副本

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

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

核心法则：只记录那些Claude必须知晓、却无法自行推断的关键信息。

黄金检验标准：如果删去某条规则后，Claude依然能做出正确的行为，那么这条规则不该出现在CLAUDE.md中。

实战：基于某工业互联网平台项目配置

下面是以实际项目中的场景举例：

# XXX 平台 全栈项目

## 项目概述

XXX 平台演示 monorepo，展示平台核心能力。

- **后端**：Spring Boot 2.7 + Spring Cloud Alibaba 微服务（Java 8）
- **前端**：Vue 2 + Element UI 微前端子应用（qiankun）

## 目录结构

| 目录 | 说明 | 端口 |
|------|------|------|
| `backend/` | Java 后端微服务 | 9026（默认） |
| `frontend/xxx-web-demo/` | Vue 2 前端微应用 | 9999（开发） |

各子目录有独立的 `CLAUDE.md`，包含详细的技术规范和编码约定。

## 跨端约定

- **API 代理**：前端通过 `/mainApi/` 路径代理访问后端接口
- **开发联调**：前端 devServer proxy → `10.44.2.105:30010`（可在 `vue.config.js` 中修改）
- **部署**：两端均 Docker 容器化，nginx 反向代理 `/mainApi/` 到后端（通过 `BACKEND` 环境变量）

## 启动方式

```bash
# 后端
cd backend
mvn clean package -DskipTests
java -jar xxx-business-demo/target/xxx-business-demo.jar

# 前端
cd frontend/xxx-web-demo
npm install
npm run serve
```

## 开发命令速查

| 命令 | 作用域 | 说明 |
|------|--------|------|
| `/new-crud` | 后端 | 生成完整 CRUD 骨架（Entity + Mapper + Service + ServiceImpl + Controller + XML） |
| `/new-page` | 前端 | 生成新页面模板（路由注册 + Vuex module + API 文件） |
| `/new-component` | 前端 | 生成新组件模板 |

## 注意事项

- 后端有 `.claude/rules`（7 个规则文件），涵盖编码规范、Controller、Entity、Feign、Mapper、MyBatis XML、新功能生成模板。大型参考文档（平台 SDK、数据库规范、通知模块、**组织机构数据**）已移至 `backend/docs/references/` 按需查阅
- 前端有 `.claude/rules`（6 个规则文件），涵盖 Vue 组件、状态管理、API 调用、微前端集成、样式、新功能生成模板。组件 API 参考文档（60 个组件）已移至 `frontend/xxx-web-gnbbdz/docs/components/` 按需查阅
- **新功能生成**：后端 `new-module-backend.md` + 前端 `new-module-frontend.md`，均为 `alwaysApply: false`，需要生成新 CRUD 模块时由 Claude 主动 Read。参照：外包承包商管理模块（已 review）
- **字典获取**：前后端接口不对称——前端 HTTP `/dict/getDictItemsByCodes` 返回 Map 的 key 是字典项的 `code`（非标准），后端 Feign `ISysClient.getDictItemsByDictCodes` 返回 Map 的 key 才是真正的字典编码（如 `ism_yes_no`）。**后端必须用 Feign 接口**，详见 `backend/.claude/rules/feign.md` 的"平台字典获取"章节；前端业务层统一走 `this.sciyonSystem.getDict(s)`（`base.js` 已做适配 + 5 分钟 TTL 缓存），详见 `frontend/xxx-web-gnbbdz/.claude/rules/api-calls.md` 的"平台字典获取"章节
- 修改跨端接口时，需同时更新前后端相关代码