# 创建你的第一个 CLAUDE.md
touch CLAUDE.md

项目根目录
├── CLAUDE.md          ← Claude Code 自动读取
├── src/
├── package.json
└── ...

# 全局编码偏好

## 语言偏好
- 所有解释、注释、commit message 优先使用中文
- 代码标识符、变量名使用英文

## 交互风格
- 做任何可能产生副作用的操作前先确认（如删除文件、git push）
- 遇到不确定的决策时，列出选项让我选择，而不是自作主张
- 回复简洁，不要过度解释已知概念

## 工具偏好
- 优先使用 ripgrep (rg) 搜索代码，而不是 grep
- 构建工具优先用 pnpm，其次是 npm，不要用 yarn

# 项目：用户管理系统 API

## 技术栈
- 后端：Python 3.12+ / FastAPI / SQLModel / PostgreSQL 16
- 测试：pytest + pytest-asyncio，覆盖率要求 ≥85%
- 部署：Docker + docker-compose

## 代码规范
- 所有 API 返回统一格式：`{"code": 0, "data": ..., "message": "ok"}`
- 错误处理：使用项目封装的 `AppError` 异常类，不要直接 `raise HTTPException`
- 数据库查询：用 SQLModel 的 `select()` 语法，不要手写 SQL
- 类型注解：所有函数参数和返回值必须有完整类型注解

## 项目结构
- `src/models/` - 数据模型
- `src/routes/` - API 路由
- `src/services/` - 业务逻辑
- `src/utils/` - 工具函数

# src/backend/CLAUDE.md - 后端子系统规则

## 缓存策略
- 所有读接口必须有 Redis 缓存层（TTL 默认 300s）
- 缓存键命名：`{服务名}:{资源类型}:{资源ID}`
- 写操作必须主动 invalidate 相关缓存

## 日志规范
- 使用 structlog，不要用 print 或 logging.info
- 每条日志包含：request_id, user_id, action, duration_ms

# CLAUDE.md - Python 后端项目模板

## 核心约束（Always）
- Python 版本：3.12+
- 依赖管理：uv（不要用 pip/poetry）
- Web 框架：FastAPI（不要用 Flask/Django）
- ORM：SQLModel（不要用纯 SQLAlchemy）
- 类型检查：mypy --strict 模式，零容忍

## 代码风格
- 遵循 ruff 规则集（自动格式化由 pre-commit 处理）
- 函数最大行数：50 行
- 类最大方法数：无限制，但单个方法不超过 30 行
- 不要写 `# type: ignore` — 把类型写对，而不是屏蔽检查

## 错误处理模式
```python
# ✅ 正确：使用项目自定义异常
from app.errors import NotFoundError, ValidationError
raise NotFoundError(f"用户 {user_id} 不存在")

# ❌ 错误：不要用 HTTPException
from fastapi import HTTPException
raise HTTPException(status_code=404)  # 禁止

### 模板2：React + TypeScript 前端项目

```markdown
# CLAUDE.md - React 前端项目模板

## 技术栈
- React 19 + TypeScript 5.6+
- 状态管理：Zustand（不要用 Redux）
- 样式：Tailwind CSS v4
- 构建：Vite 6
- 包管理：pnpm

## TypeScript 规范
- strict 模式必须开启
- 禁止使用 `any` — 用 `unknown` + 类型守卫代替
- Props 类型必须导出：`export interface ButtonProps {}`
- 事件处理器类型用 React 内置类型：
  ```tsx
  // ✅ 正确
  const handleClick: React.MouseEventHandler<HTMLButtonElement> = (e) => {}
  // ❌ 错误
  const handleClick = (e: any) => {}
  ```

## 组件规范
- 一个文件一个组件（除非是纯工具函数）
- 组件命名：PascalCase
- 文件命名：kebab-case（button-group.tsx → ButtonGroup）
- 导出方式：named export，不要 default export

## 样式规范
- 始终用 Tailwind，不写自定义 CSS 文件
- 复用样式用 `@apply` 或提取组件，不复制 class 字符串
- 响应式设计：移动端优先（从 sm: 开始加断点）

# CLAUDE.md - AI 创业者通用模板

## 工作原则
- 快速迭代优先于完美架构：先做出能跑的 MVP，再优化
- 每个功能从用户故事开始，不要从技术方案开始
- 我是一名独立开发者，不需要企业级的过度工程

## 技术选型偏好
- 能用 SaaS 就不自建（支付用 Stripe/Lemon Squeezy，不自己写）
- 能用 Serverless 就不自己管服务器（Cloudflare Workers > VPS）
- 数据库优先选 SQLite + Turso/Litestream，够用且运维成本为零

## 开发流程
1. 先讨论方案（5-10分钟，列出 trade-offs）
2. 再写代码（专注于核心功能，延后非关键特性）
3. 每个功能完成后 commit（commit message 用中文）

## 成本意识
- 提醒我可能产生费用的操作（API 调用、云服务创建资源）
- 优先推荐有免费层的服务
- 估算新功能带来的月成本变化

# CLAUDE.md

## 项目概述
[简短描述]

## 规则文件
详见以下文件：
- 代码规范：@./docs/CODING_STANDARDS.md
- API 设计规范：@./docs/API_DESIGN.md  
- 部署流程：@./docs/DEPLOY.md

## 快速参考
[最常违反的 3 条规则]

# ❌ 低效（Claude 经常忽略）
- 使用 async/await
- 添加错误处理
- 写单元测试

# ✅ 高效（Claude 严格遵守）
- 禁止：使用同步代码进行 I/O 操作
- 禁止：让异常逃逸到 API 层（必须用 AppError 包装）
- 禁止：提交没有测试的新代码

## 数据访问层
- 使用 Prisma Client 而不是手写 SQL
- 使用 Zod 做输入验证，而不是 if/else 手动检查
- 使用 tRPC 的过程调用，而不是手动定义 REST endpoint

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(pnpm run *)", "Bash(git *)", "Bash(npx tsc *)"],
    "deny": ["Bash(rm -rf *)", "Bash(git push --force *)", "Bash(git reset --hard *)"]
  },
  "model": "claude-sonnet-4-20250514"
}