五层记忆体系

• 企业级构成了整个体系的“天花板”，也是开发者通常无法触及的层级。该层级由公司的IT管理员通过系统级配置文件（在Linux操作系统中通常为/etc/claudecode/CLAUDE.md）或Anthropic企业管理后台进行统一设定。
• 用户级相当于用户的“个人偏好档案”。该配置文件位于用户主目录下的~/.claude/CLAUDE.md，对在这台机器上打开的所有项目均生效
• 项目级是日常开发中使用率最高的，也是本章的主角。它体现为项目根目录下的CLAUDE.md，必须提交至Git仓库，成为项目代码资产的一部分。
• 规则级是一项精巧的进阶设计，旨在解决“单一CLAUDE.md难以承载所有复杂规则”的痛点。你可以在.claude/rules/目录下部署多个独立的Markdown文件，使每个文件专注于一个特定主题（如数据库规范、API设计风格或测试策略）。
• 本地级是开发者的“私人便签”，对应CLAUDE.local.md。

1.CLAUDE.md写作范式

• 第一问：WHY（为什么这样做）
• 第二问：WHAT（做什么、不做什么）
• 第三问：HOW（如何一步步做）

点击查看代码

# 订单服务 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数据库迁移

2.条件化规则系统

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

点击查看代码

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

点击查看代码

<!-- .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字段

3.实战：3种典型项目配置

3.1 React前端项目配置

点击查看代码

# 电商平台前端项目规范
## 技术栈
- 核心：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 代码检查

</details>

3.2 Node.js后端项目配置

<details>
<summary>点击查看代码</summary>

订单微服务后端规范

技术栈

• 运行时：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 响应标准

所有接口必须统一返回格式：{ success: boolean, data?: T, error?: { code: string, message:
string } }
分页规范：page（从1开始），limit（默认20，最大值100）
错误码：必须使用UPPER_SNAKE_CASE格式

常用命令

pnpm test # 运行vitest 测试套件
pnpm build # tsc 编译
pnpm db:migrate # 执行Prisma 数据库迁移
pnpm db:studio # 启动Prisma Studio 可视化界面

</details>

3.3 Python数据项目配置

<details>
<summary>点击查看代码</summary>

用户行为分析系统规范

技术栈

• 环境：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副本

常用命令

uv run pytest # 运行测试套件
uv run jupyter lab # 启动Jupyter Lab uv run python -m src.train # 执行模型训练脚本

</details>