完美 CLAUDE.md 写法指南：三大支柱结构、防踩坑清单和可直接复用的模板

## 项目概览
电商平台，三个服务：
- `/api` — Node.js + Express REST API（TypeScript strict 模式）
- `/web` — Next.js 14 前端，使用 App Router
- `/shared` — 两个服务共用的类型和工具函数

数据库：PostgreSQL 16，通过 Prisma ORM
队列：BullMQ on Redis
认证：Clerk

## 架构决策
- 默认使用 Server Components，只在需要交互时才用 Client Components
- 所有数据库查询走 `/api/src/repos/` 的 Repository 模式
  （不直接在路由处理器里查询），保持业务逻辑可测试
- 选择 BullMQ 而不是 cron，因为多个工作流需要重试和死信处理

## 命令
- 安装：`pnpm install`（不是 npm，我们用 pnpm workspaces）
- 开发服务器：`pnpm dev`（同时启动 API 和 Web）
- 运行所有测试：`pnpm test`
- 运行单个测试：`pnpm test -- --grep "测试名称"`
- 类型检查：`pnpm typecheck`
- Lint + 修复：`pnpm lint:fix`
- 数据库迁移：`pnpm prisma migrate dev`

## 工作流
1. 从 `main` 创建功能分支
2. 实现改动
3. 运行 `pnpm typecheck && pnpm lint:fix && pnpm test`
4. 用 conventional commit 格式提交：`feat(scope): description`

# 错的写法（浪费指令预算）
## 风格规则
- 使用 2 空格缩进
- 始终用分号
- import 按字母排序

# 对的写法
## 格式化
代码格式由 Biome 处理。Git pre-commit hook 自动强制执行。

## 文档
详细文档在 `/docs/agent/` 目录：
- `docs/agent/testing.md` — 测试模式和 fixtures
- `docs/agent/api-conventions.md` — API 接口规范
- `docs/agent/database.md` — 迁移和 Schema 模式

在相关目录工作前，请先读取对应文件。

# 项目：[名称]

## 概览
[一句话描述项目做什么]

## 技术栈
- 语言：[e.g., TypeScript 5.4, strict 模式]
- 框架：[e.g., Next.js 14 with App Router]
- 数据库：[e.g., PostgreSQL 16 via Prisma]
- 包管理器：[e.g., pnpm 9]

## 架构
[2-3 句话描述代码库组织方式]
- 关键模式：[e.g., Repository 模式处理 DB 访问]
- 关键决策：[e.g., 默认 Server Components]

## 命令
- 安装：`[command]`
- 开发：`[command]`
- 测试：`[command]`
- 单测：`[command]`
- 类型检查：`[command]`
- Lint：`[command]`
- 构建：`[command]`

## 工作流
1. 从 `main` 创建分支
2. 实现改动
3. 运行 `[test + lint + typecheck 命令]`
4. 按 [提交格式] 提交

## 约定
- [约定 1]
- [约定 2]
- [约定 3]

## 文档
详细文档在 `[路径]`

## 领域术语
- [术语]：[定义]