总体方针

• CLAUDE.md（项目根目录）或 .claude/CLAUDE.md 里的内容在每个对话轮次都会被完整加载，建议保持在 50 行以内，只放最核心的规则（如包管理器、测试命令、目录约束）
• 不要把 CLAUDE.md 当成百科全书，把它当成目录——目录极简，内容散落在其他文件里，Claude 需要时会自己去找。

示例

CLAUDE.md

# 项目概览
这是一个 fast api + vitepress 的电商项目。

# 详细文档（按需读取）
- 架构设计: `docs/architecture.md`
- 数据库规范: `docs/database-conventions.md`  
- 代码风格: `docs/code-style.md`（优先用 Ruff/ESLint 自动格式化）
- 测试策略: `docs/testing-guide.md`

# 核心规则（只有真正通用的几条）
1. 不确定就主动问，不要猜
2. 改代码前先跑测试验证当前行为
3. 多步骤任务每完成一步总结进度

architecture.md

# 生产环境架构设计

## 1. 总体架构
- **前端**：VitePress 静态站点（SSG），部署于 CDN（如 CloudFlare Pages / Netlify）。
- **后端**：FastAPI 应用，容器化运行在云服务器或 Kubernetes（生产建议至少 2 副本）。
- **数据库**：PostgreSQL 13+（主从复制，每日自动备份）。
- **缓存**：Redis 6+（用于会话、限流、异步任务队列）。
- **反向代理**：Nginx（前端路由回退、SSL 终结、负载均衡）。

## 2. 关键目录结构
/backend
├── app/
│ ├── api/ # 路由层（依赖注入、请求/响应模型）
│ ├── core/ # 配置、安全、数据库引擎
│ ├── models/ # SQLAlchemy ORM 模型
│ ├── schemas/ # Pydantic 模型（请求/响应校验）
│ ├── services/ # 业务逻辑层
│ └── utils/ # 通用辅助函数
├── tests/
├── alembic/ # 数据库迁移
└── requirements.txt

/frontend (VitePress)
├── docs/
│ ├── .vitepress/
│ │ ├── config.mts # 站点配置（base、theme、sidebar）
│ │ └── theme/ # 自定义主题组件
│ ├── public/
│ └── index.md
└── package.json

## 3. 生产部署要点
- 前端构建时 `base` 设为 `/docs/` 或子路径，配合 Nginx 反代。
- FastAPI 使用 `gunicorn + uvicorn.workers.UvicornWorker`（多 worker）。
- 环境变量统一通过 `.env.prod` 注入，禁止写入代码。
- 健康检查端点：`GET /health` 返回 `{"status":"ok"}`。
- 日志：JSON 格式输出到 stdout，由日志收集系统（如 Loki）采集。

## 4. 安全约束
- 所有 API 默认要求 JWT（`/docs` 和 `/openapi.json` 除外）。
- 严格使用 HTTPS + HSTS。
- 请求限流：每个 IP 每分钟 60 次，超出返回 429。
- 输入校验完全交给 Pydantic，禁止手动拼接 SQL。

database-conventions.md

# 数据库设计 & 使用规范（生产环境）

## 1. 技术选型
- **主库**：PostgreSQL 13+，开启 `pg_stat_statements` 用于性能监控。
- **迁移工具**：Alembic（所有 DDL 变更必须通过迁移脚本）。
- **ORM**：SQLAlchemy 2.0（异步优先，使用 `asyncpg` 驱动）。

## 2. 命名约定
| 对象类型   | 命名规则                     | 示例                |
|-----------|------------------------------|---------------------|
| 表名       | 蛇形命名，小写，复数         | `user_sessions`     |
| 主键       | `id` (BIGINT / UUID 优先)    | -                   |
| 外键列     | `{referenced_table}_id`      | `organization_id`   |
| 普通索引   | `idx_{table}_{columns}`      | `idx_users_email`   |
| 唯一约束   | `uq_{table}_{columns}`       | `uq_users_email`    |
| 时间戳列   | `created_at`, `updated_at`   | 带时区 (`timestamptz`) |

## 3. 生产关键规则
- **禁止** `SELECT *`，只取需要的列。
- **软删除**：使用 `deleted_at` 字段（可为空），查询时通过基类 mixin 或 repository 层统一过滤 `WHERE deleted_at IS NULL`。
- **审计字段**：每张表必须包含 `created_by`, `updated_by`（存储用户 ID 或系统标识）。
- **迁移要求**：
  - 每个迁移文件必须包含 `upgrade()` 和 `downgrade()`。
  - 变更前先在 staging 环境执行，并用 `sqlalchemy-utils` 检查。
- **性能规范**：
  - 所有查询必须加 `limit`（翻页用 `offset+limit` 或游标）。
  - 避免在循环中执行 SQL（N+1 问题）。
  - 使用 `explain` 分析慢查询，关键表需创建统计信息。

## 4. 示例模型（SQLAlchemy 2.0）
```python
from datetime import datetime
from sqlalchemy import String, DateTime, func
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from sqlalchemy.dialects.postgresql import UUID

class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = "users"
    id: Mapped[UUID] = mapped_column(UUID(as_uuid=True), primary_key=True)
    email: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
    full_name: Mapped[str | None] = mapped_column(String(100))
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
    deleted_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

code-style.md

# 代码风格规范（生产环境）

## 核心原则
**自动格式化优先**：所有代码必须通过工具检查和格式化，人工评审只关注逻辑。

## 前端（VitePress / Vue / TypeScript）
| 规则项         | 工具                   | 配置要求                                    |
|---------------|------------------------|---------------------------------------------|
| 格式化        | Prettier 3.x           | `trailingComma: "es5"`, `semi: true`, `singleQuote: true` |
| Linting       | ESLint 8 + Vue plugin  | 继承 `@vue/typescript/recommended`          |
| 类型检查      | `vue-tsc --noEmit`     | 必须零错误才能提交                           |

**提交前自动执行**：
npm run format   # prettier --write .
npm run lint     # eslint --fix .
npm run type-check

## 后端（FastAPI / Python）生产强制规则
- 所有函数必须带类型注解（参数与返回值均需标注）。
- 禁止 `from module import *`。
- FastAPI 路径函数应短小（<20 行），复杂逻辑下沉到 service 层。
- 使用 Pydantic 的 `Field` 添加描述和校验（如 `min_length`、`pattern`）。

### 例外情况:
- 自动生成的迁移文件（alembic/versions/*）不强制类型检查。
- VitePress 临时构建文件（.vitepress/dist）不进行 lint。

testing-guide.md

# 测试策略（生产环境）

## 测试层级
| 层级       | 工具链               | 执行时机      | 目标覆盖率 |
|-----------|----------------------|--------------|------------|
| 单元测试   | Pytest (backend) / Vitest (frontend) | 每次提交  | ≥ 80%      |
| 集成测试   | Pytest + FastAPI TestClient | PR 合入前 | 关键路径 100% |
| E2E 测试   | Playwright (可选)    | 部署前        | 核心用户流程 |

## 后端（FastAPI）必写测试
- **每个 API 端点至少测试**：
  - 正常返回 (200/201)
  - 鉴权失败 (401)
  - 参数错误 (422)
  - 资源不存在 (404)
- **使用 `pytest-asyncio`** 测试异步端点。
- **数据库测试**：使用 `pytest-postgresql` 创建临时数据库，事务回滚确保隔离。

示例（pytest）：
async def test_create_user(client, db_session):
    resp = await client.post("/users", json={"email": "test@example.com"})
    assert resp.status_code == 201
    assert "id" in resp.json()

## 前端（VitePress）测试
VitePress 主要是静态站点，但若包含自定义 Vue 组件：
- 组件单元测试：@vue/test-utils + Vitest。
- 快照测试：确保 UI 渲染稳定。
- 链接检查：vitepress build && npx linkinator ./docs/.vitepress/dist。

## 生产环境预检清单
- 单元测试 + 集成测试全部通过（CI 必须）。
- 关键业务 API 的集成测试覆盖至少 3 种场景。
- 运行 pytest --cov 并检查报告，未达标的需补充测试。
- 自动测试完成后，在 staging 环境手动执行冒烟测试（创建/更新/删除核心资源）。

## 反模式（禁止）
- 跳过测试提交（如 git commit --no-verify）。
- 硬编码依赖外部生产数据库的测试。
- 只测成功路径，不测异常。