CLAUDE.md 最佳实践：写出真正有效的配置文件

## 关于本项目
这个项目是一个用 Next.js 15 和 TypeScript 构建的电商平台。
我们通常偏好函数式编程模式，力求保持代码整洁和可维护。
团队重视可读性和……

## 技术栈
- Next.js 15 (App Router) + TypeScript 5.7 (strict mode)
- Tailwind CSS + shadcn/ui + Zustand
- PostgreSQL + Prisma

## 规则
- 仅使用函数组件，禁止类组件。
- 所有函数必须有 TypeScript 类型注解。
- 函数不超过 30 行，重复逻辑提取为辅助函数。

# 项目配置

## 架构
@docs/architecture.md

## API 规范
@docs/api-conventions.md

## 测试标准
@docs/testing-guide.md

## 部署
@docs/deploy-runbook.md

## 关键规则

- IMPORTANT：所有数据库查询必须按 `tenantId` 过滤，没有例外。
  多租户数据泄露属于安全事故。
- NEVER 将 `.env` 文件或 API 密钥提交到 Git。
- NEVER 删除或修改数据库迁移文件。只能创建新的迁移。
- YOU MUST 在创建任何提交前运行 `pnpm test`。

# SaaS 仪表盘

## 技术栈
- Next.js 15 (App Router) + TypeScript 5.7 (strict)
- Tailwind CSS + shadcn/ui
- Zustand 管理客户端状态
- TanStack Query 管理服务端状态
- Vitest + Testing Library

## 命令
```bash
pnpm dev           # 开发服务器 localhost:3000
pnpm build         # 生产构建
pnpm test          # 运行测试
pnpm lint          # ESLint 检查
pnpm db:push       # 推送 Prisma schema
```

## 规则
- 仅使用函数组件，禁止类组件。
- Props 接口命名为 `[Component]Props`（如 `UserCardProps`）。
- 文件名：kebab-case。组件名：PascalCase。
- 所有 API 调用使用 TanStack Query 的 `useQuery`/`useMutation`。
- 禁止 `any` 类型。如果确实未知，使用 `unknown`。
- 所有面向用户的文本必须使用 i18n 系统（`t()` 函数）。

## 关键规则
- NEVER 直接从 `node_modules` 导入，使用 `src/lib/` 中的重新导出。
- 所有数据库查询 MUST 按 `organizationId` 过滤（多租户）。
- NEVER 提交 `.env.local` 或在客户端代码中暴露 API 密钥。

# 支付服务 API

## 技术栈
- Python 3.12 + FastAPI 0.115
- SQLAlchemy 2.0 + Alembic
- PostgreSQL 16 + Redis 7
- Poetry 管理依赖
- pytest 测试

## 命令
```bash
poetry run uvicorn src.main:app --reload    # 开发服务器
poetry run pytest -x -v                     # 测试（首次失败即停止）
poetry run alembic upgrade head             # 应用迁移
poetry run ruff check . && ruff format .    # 检查 + 格式化
```

## 架构
- 路由层保持精简：验证输入 → 调用服务 → 返回响应。
- 业务逻辑放在 `src/services/` 中。
- 数据库操作通过 `src/repositories/` 中的仓储类。
- 后台任务使用 Celery，定义在 `src/tasks/` 中。

## 规则
- 所有函数必须有类型注解，没有例外。
- 所有请求/响应验证使用 Pydantic 模型。
- 文档字符串使用 Google 风格。
- NEVER 执行原始 SQL 查询，使用 SQLAlchemy ORM。
- 所有金额以整数（分）存储，在 API 边界转换。
- 新端点 MUST 至少有一个正常路径和一个错误路径的测试。

# Acme 平台 Monorepo

## 结构
```
apps/
├── web/           # Next.js 客户门户（见 apps/web/CLAUDE.md）
├── admin/         # Next.js 管理后台（见 apps/admin/CLAUDE.md）
└── api/           # FastAPI 后端（见 apps/api/CLAUDE.md）
packages/
├── ui/            # 共享组件库
├── config/        # 共享配置（ESLint, TypeScript, Tailwind）
└── types/         # 共享 TypeScript 类型
```

## 全局规则（适用于所有应用）
- 包管理器：pnpm。NEVER 使用 npm 或 yarn。
- 提交格式：`type(scope): description`（如 `feat(web): add login page`）
- 范围：web, admin, api, ui, config, types, infra
- 所有 PR 必须通过 CI 才能合并。
- 共享类型放在 `packages/types/` 中。NEVER 重复类型定义。

## 命令
```bash
pnpm install              # 安装所有依赖
pnpm --filter web dev     # 运行 web 应用
pnpm --filter api dev     # 运行 API
pnpm -r test              # 运行所有测试
pnpm -r build             # 构建所有包
```

## 跨应用规则
- 前端应用仅通过 API 获取数据，禁止直接访问数据库。
- `packages/ui/` 中的共享组件必须与框架无关。
- API 变更必须保持向后兼容。破坏性变更需要版本控制。

# HealthTrack 移动应用

## 技术栈
- React Native 0.76 + Expo SDK 52
- TypeScript 5.7 (strict)
- Zustand + MMKV 本地存储
- React Navigation v7

## 命令
```bash
npx expo start        # 开发服务器
npx expo run:ios      # 在 iOS 模拟器运行
npx expo run:android  # 在 Android 模拟器运行
pnpm test             # Jest 测试
```

## 规则
- 优先使用 Expo API。如果 Expo 已覆盖的功能，不要安装原生 RN 模块。
- 页面放在 `src/screens/`，组件放在 `src/components/`。
- 导航类型 MUST 在 `src/navigation/types.ts` 中定义。
- 使用 `StyleSheet.create()` 定义样式，禁止内联样式对象。
- 所有网络请求通过 `src/api/client.ts`，禁止直接调用 fetch。
- IMPORTANT：必须在 iOS 和 Android 上都测试。平台特定代码使用 `.ios.tsx` / `.android.tsx` 后缀。
- NEVER 在 AsyncStorage 中存储敏感数据（token、密码），使用 expo-secure-store。

# 通知服务

## 技术栈
- Go 1.23
- Chi 路由 + sqlc 数据库查询
- PostgreSQL 16 + Redis 7
- Docker 本地开发

## 命令
```bash
go run ./cmd/server              # 运行服务器
go test ./...                    # 运行所有测试
make migrate-up                  # 应用迁移
make generate                    # 重新生成 sqlc + protobuf
docker compose up -d             # 启动本地依赖
```

## 规则
- 遵循标准 Go 项目布局。入口在 `cmd/`，包在 `internal/`。
- 错误处理：用 `fmt.Errorf("context: %w", err)` 包装错误。不要丢弃错误。
- 接口由消费者定义，而非实现者。
- 数据库查询在 `internal/db/` 中由 sqlc 生成。编辑 `.sql` 文件，然后运行 `make generate`。
- NEVER 直接修改生成的代码。修改源文件（SQL、proto）然后重新生成。
- 日志：使用 `slog` 的结构化日志。禁止 `fmt.Println` 或 `log.Println`。
- Context 必须是任何执行 I/O 的函数的第一个参数。

# AI 工程博客

## 技术栈
- Hugo v0.153.2+（Extended）
- 主题：hermit-V2（git submodule）

## 命令
```bash
hugo server -D         # 含草稿预览
hugo server            # 不含草稿预览
hugo --minify          # 生产构建
```

## 内容规则
- 所有新文章 MUST 使用英文撰写。
- NEVER 修改已有的中文文章。
- Front matter 使用 TOML 格式（+++）。
- 分类：仅限 'AI Guides' 或 'Comparisons'，不可自定义分类。

## 文章结构
- 目录：content/posts/ai/YYYY-MM-DD-english-slug/index.md
- 封面图：MUST 命名为 cover.webp（1200x630px，<200KB）
- 封面图 MUST 在 front matter 之后第一行引用
- 标签：3-5 个英文标签
- 描述：120-160 字符，包含主关键词

## Git
- 工作分支：code
- 提交信息：中文
- 推送到 code 触发自动部署

# 开发者配置

我是一名高级全栈工程师。主要语言：TypeScript、Python、Go。

## 偏好
- 所有对话用中文回复
- 提交信息用中文
- 代码注释用英文
- 偏好函数式模式而非面向对象
- 函数不超过 30 行
- 使用描述性变量名——除了循环计数器外不用单字母

## 工作流
- 约定式提交格式：type: description
- 每次提交前运行 linter
- 小而聚焦的提交优于大批量提交
- 当在两种方案间犹豫时，选择更简单的那个

# 仓库准则

## 技术栈
- Next.js 15 + TypeScript 5.7
- Tailwind CSS + shadcn/ui
- PostgreSQL + Prisma

## 编码标准
- 仅使用函数组件
- Props 接口命名为 [Component]Props
- 所有 API 调用必须处理加载态和错误态

## 测试
- Vitest + Testing Library
- 新功能需要测试
- 提交前运行 pnpm test

See @AGENTS.md

## Claude 专属配置
- 上下文变长时使用 /compact
- 常规任务用 Sonnet，架构决策用 Opus
- 编写 Skills 时，遵循 .claude/skills/ 中的模式

## 经验教训（不要重复这些错误）
- 本项目使用 ESM 模块。NEVER 使用 require() 或 module.exports。
- `user` 表有软删除列 `deleted_at`。所有查询必须添加
  `WHERE deleted_at IS NULL`，除非明确查询已删除的用户。
- 测试不得使用生产数据库。使用 conftest.py 中的测试 fixtures。
- /api/v1/upload 端点有 nginx 强制的 10MB 限制，不是应用层的。
  不要添加应用层的大小验证——已经被处理了。

## API 开发
- 创建新端点时：参考 src/api/v1/users.py 中的模式
- 修改已有端点时：保持向后兼容。添加新字段，不要重命名或删除现有字段。
- 编写迁移时：NEVER 修改或删除现有迁移文件。创建新的。

## 前端开发
- 创建新页面时：使用 src/app/(dashboard)/template/page.tsx 中的模板
- 添加表单时：使用 react-hook-form + Zod。参见 src/components/forms/ 中的模式。
- 添加新 API 调用时：在 src/hooks/api/ 中使用 TanStack Query 添加 query/mutation。

.claude/
└── rules/
    ├── coding-standards.md
    ├── git-conventions.md
    ├── testing-requirements.md
    └── security-policies.md

## 自动化检查（不要手动重复这些）
- Pre-commit：ESLint + Prettier 通过 hooks 自动运行
- Pre-push：完整测试套件自动运行
- 见 .claude/settings.json 了解 hook 配置

## 你仍然必须做的
- 写有意义的提交信息
- 为新业务逻辑添加测试
- 当端点变更时更新 API 文档