用户级内容设定

用户级内容设定承载的是你的全局偏好，即跨所有项目生效的个人偏好，如个人代码风格，沟通语言设置，通用工作习惯等。比如说我希望所有的 PPT 都是 16:9，黑体字。这种设置就应该放在此处。

位置：~/.claude/CLAUDE.md

示例：

# 个人偏好

## 沟通方式
- 使用中文回复
- 代码注释使用英文
- 解释简洁直接，不要过多铺垫

## 通用代码风格
- 缩进使用 2 空格
- 优先使用 async/await
- 变量命名使用 camelCase
- 常量命名使用 UPPER_SNAKE_CASE

## 我的常用工具
- 包管理器: uv
- 编辑器: VS Code
- 终端: zsh

用户级记忆会被项目级覆盖。如果你个人喜欢 2 空格缩进，但项目要求 4 空格，那就用 4 空格。

项目级团队共享规范

团队共享规范是团队共享的项目知识，应该提交到 Git。适合存放的内容包括项目架构和技术栈、团队编码规范、重要的设计决策和常用命令。

位置：项目根目录的 ./CLAUDE.md

示例（一个后端 API 项目）：

# 项目：订单服务 API

## 技术栈
- Node.js 20 + TypeScript
- Fastify（Web 框架）
- Prisma（ORM）
- PostgreSQL + Redis
- Zod（数据验证）

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

## API 响应格式
```typescript
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: { code: string; message: string };
}
```
编码规范
- TypeScript strict 模式
- 禁止使用 any，使用 unknown + 类型守卫
- 所有 API 端点必须有 Zod schema 验证
- 业务错误使用自定义 Error 类
常用命令
- pnpm dev - 启动开发服务器
- pnpm test - 运行测试
- pnpm prisma migrate dev - 运行数据库迁移

本地级个人工作空间

个人工作空间用于记载个人工作笔记，不提交到 Git，适合内容包括本地环境配置、个人调试技巧、当前工作备注，敏感信息（测试账号等）。

位置：项目根目录的./CLAUDE.local.md

示例如下。

# 本地开发笔记

## 我的环境
- 本地 API: http://localhost:3000
- 测试数据库: order_service_dev
- Redis: localhost:6379

## 测试账号
- admin@test.com / test123
- user@test.com / test123

## 当前工作
- 正在重构支付模块
- 参考 PR #234 的讨论
- 周五前完成

## 调试技巧
- 订单状态机日志: LOG_LEVEL=debug pnpm dev
- 查看 Redis 缓存: redis-cli KEYS "order:*"

这里重点强调一下：记得把 CLAUDE.local.md 加入 .gitignore！

echo "CLAUDE.local.md" >> .gitignore

当在项目越来越大，周期越来越长的时候，一个属于自己的本地记忆空间其实还蛮有用的。

规则目录：分类组织

Rules 是按主题组织的规则文件，支持条件作用域（也就是视情况来确定是否加载该记忆内容），适合场景包括 CLAUDE.md 变得太长时，不同文件类型需要不同规范时，以及前后端分离的项目。

位置：.claude/rules/*.md

目录结构：

.claude/
└── rules/
    ├── typescript.md      # TypeScript 规范
    ├── testing.md         # 测试规范
    ├── api-design.md      # API 设计规范
    └── security.md        # 安全规范

条件作用域示例：.claude/rules/testing.md

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

# 测试规范

## 命名
- 单元测试: `*.test.ts`
- 集成测试: `*.integration.test.ts`

## 结构
使用 Arrange-Act-Assert 模式：

```typescript
describe('OrderService', () => {
  describe('createOrder', () => {
    it('should create order when stock is available', async () => {
      // Arrange
      const mockProduct = createMockProduct({ stock: 10 });

      // Act
      const order = await orderService.createOrder(mockProduct.id, 1);

      // Assert
      expect(order.status).toBe('created');
    });
  });
});
```

## 覆盖率要求
- 业务逻辑: > 80%
- 工具函数: > 90%
- 路由/控制器: 可以较低

此处的关键特性是 paths 字段让这个规则只在编辑测试文件时生效，不会浪费其他场景的上下文空间。

编写高效的 CLAUDE.md

核心原则 1：Less is More

CLAUDE.md 的每一行，都会在每一次对话开始时被自动注入上下文。这意味着一件事：冗余不是无害的，而是持续消耗的。所以保持精简不是建议，而是必须。

核心原则 2：具体优于泛泛

先来看一个非常常见、但几乎没有任何效果的写法。

# 项目规范
## 代码质量
请写出高质量的代码。代码应该是可读的。使用有意义的变量名。
保持代码整洁。遵循最佳实践。不要写重复的代码。

这些话没有一句是错的，但问题在于——Claude 本来就知道这些。它们不会改变 Claude 的任何决策，只会白白占用上下文空间。这些话对人类尚且含糊，对模型来说，更是几乎等于什么都没说。

真正有价值的 CLAUDE.md，应该长这样。

# 项目规范

## TypeScript
- 使用 `interface` 定义对象结构，`type` 用于联合类型
- 禁止 `any`，使用 `unknown` + 类型守卫
- 函数参数 > 3 个时，使用对象参数

## 错误处理
```typescript
// 业务错误
throw new BusinessError('ORDER_NOT_FOUND', '订单不存在');

// 验证错误（Zod 自动抛出）
const data = orderSchema.parse(input);

// controller 中不要 try-catch
// 由全局错误中间件统一处理
```

两者的差异非常明确。后者不是模糊要求“要高质量”，而是给出了如何做才算高质量；不是“注意错误处理”，而是具体的错误模型；不是抽象描述，而是可直接模仿的代码形态。

这里有个简单的判断标准——如果你不写，Claude 也大概率会做对，那就不要写。

核心原则 3：关键三问题 WHY / WHAT / HOW

WHY —— 为什么要这样做？

## 为什么使用 Zod？
- TypeScript 只有编译时类型检查
- API 输入需要运行时验证
- Zod 可以同时生成 TS 类型和验证逻辑
- 错误信息自动生成，对用户友好

这一部分的作用，不是让 Claude “记住一个库”，而是让它理解背后的决策逻辑。当 Claude 明白了为什么，它在面对相似但不完全相同的场景时，才更可能做出一致的判断。

WHAT —— 具体要做什么，不要做什么？

## 数据库操作规范
- 所有查询通过 Prisma ORM
- 复杂查询封装在 `src/repositories/`
- 禁止在 controller/service 中直接写 SQL
- 事务使用 `prisma.$transaction()`

这一部分的重点是边界。什么是允许的，什么是禁止的，决策应该发生在哪一层？对 Claude 来说，这比“最佳实践”四个字重要得多。

HOW —— 按什么步骤去做？

## 创建新 API 端点

1. 在 `src/schemas/` 创建请求/响应 Zod schema
2. 在 `src/routes/` 添加路由定义
3. 在 `src/controllers/` 实现请求处理
4. 在 `src/services/` 实现业务逻辑
5. 在 `tests/` 添加测试用例

示例参考: `src/routes/orders.ts`

当步骤清晰、路径明确、还有参考文件时，Claude 才会稳定复用同一套工作流，而不是每次自由发挥。

核心原则 4：渐进式披露：不要把一切都塞进 CLAUDE.md

CLAUDE.md 的职责是定义默认决策，而不是承载全部知识。对于非核心、但可能被用到的内容，正确的做法是引用，而不是复制。

# 项目规范

## 核心
[精简的核心规范]

## 详细文档
- 数据库设计: 见 `docs/database.md`
- API 规范: 见 `docs/api-spec.md`
- 部署流程: 见 `docs/deployment.md`

这样做有两个好处：

CLAUDE.md 保持轻量，启动成本低。
当 Claude 需要进一步的细节信息时，可以按需读取引用文件。

这里补充一下，Claude code 团队对于 CC 关于Claude.md的一个最佳实践

认真维护你的 CLAUDE.md

每次纠正完 Claude，都用这句话收尾：“更新你的 CLAUDE.md，这样你就不会再犯这个错误了。“Claude 在给自己写规则这件事上强得有点”诡异“。

随着时间推移，毫不留情地打磨你的 CLAUDE.md。持续迭代，直到你能明显量化地看到 Claude 的出错率下降。

有位工程师会让 Claude 为每个任务/项目维护一个 notes 目录，每次 PR 后都更新，然后在 CLAUDE.md 里指向这个目录。

原文：https://x.com/bcherny/status/2017742752566632544

一份模板 CLAUDE.md

# CLAUDE.md

This file provides comprehensive guidance to AI assistants (like Claude Code) when working with code in this repository.

## Important Notes for AI Assistants

### Coding Rules (CRITICAL - MUST FOLLOW)

1. **不要自作聪明瞎写代码** - 写代码前要先确认方案再执行
2. **不要添加冗余代码** - 只做必要的校验，不添加各种无关的校验
3. **精简代码** - 如果已有功能/组件/函数，优先重构和抽象
4. **不要瞎改之前的代码** - 确认改完不会影响其他功能
5. **不要重复造轮子** - 优先使用已有的类似功能
6. **严格按照示例文档** - 有参考文档时严格按照示例写代码
7. **打印清晰的调试日志** - 每个步骤都要打印正确的上下文
8. **不要硬编码可配置信息** - 写到环境变量文件 .env 中
9. **首先考虑快速简单完成任务** - 别搞复杂的东西
10. **不要做任何格式化代码的操作**
11. **不准启动服务，不得占用 3006 端口**
12. **每次写完功能后测试正确性** - 通过 API 调用或网页请求测试
13. **测试正确后清理调试日志等信息**
14. **通过 chrome devtools mcp 调试时禁止关闭用户正在使用的实例** - 启动新的 isolated 实例