构建专属 AI 编程助手

构建专属 AI 编程助手

本节摘要:前三节讲了「为什么」「怎么写」「怎么检索」,本节是综合实战:为一个 FastAPI 后端项目和一个 React + TypeScript 前端项目分别定制完整的 AI 编程规范,然后讲清团队共享的最佳实践。读完本节,你应该能直接给自己的项目写一份高质量的 .cursorrules,让 AI 从「通用助手」变成「懂你项目的专属搭档」。

一、实战:FastAPI 后端项目规范

假设你的项目技术栈:FastAPI + SQLAlchemy 2.0(async)+ Pydantic v2 + PostgreSQL + pytest。

# 项目规范 - FastAPI 后端

## 技术栈
- Python 3.12, FastAPI 0.115+, SQLAlchemy 2.0 (async mode)
- Pydantic v2 (用 model_config, 不用 class Config)
- PostgreSQL 16, 异步驱动 asyncpg
- 测试: pytest + httpx (AsyncClient)
- 迁移: Alembic

## 目录结构
- src/api/ — 路由(按模块分文件: user.py, order.py)
- src/services/ — 业务逻辑(不依赖 FastAPI,可独立测试)
- src/models/ — SQLAlchemy 模型
- src/schemas/ — Pydantic 请求/响应模型
- src/core/ — 配置、安全、数据库连接
- tests/ — 镜像 src 结构

## 代码约定
- 所有函数使用 type hints
- 路由函数只做参数校验和调用 service,不写业务逻辑
- Service 层不导入 FastAPI 的任何模块(保持框架无关)
- 错误统一继承 AppError,由全局 exception_handler 处理
- 数据库操作用 async session,禁止同步 session

## API 设计
- RESTful 风格,URL 用复数名词: /users, /orders
- 响应格式: {"code": 0, "data": ..., "message": "ok"}
- 分页参数: page(从1开始) + size(默认20,最大100)
- 认证: Bearer JWT, 通过 Depends(get_current_user) 注入

## 禁止事项
- 不用 Flask/Django 的写法(如 @app.route)
- 不用 Pydantic v1 语法(如 .dict(), class Config)
- 不在路由中直接写 SQL
- 不用 print() 调试(用 logging 模块)
​

二、实战:React + TypeScript 前端项目规范

假设技术栈:Next.js 14(App Router)+ TypeScript 5 + Tailwind CSS + Zustand。

# 项目规范 - React 前端

## 技术栈
- Next.js 14 (App Router), React 18, TypeScript 5 (strict)
- 样式: Tailwind CSS (不写自定义 CSS 文件)
- 状态管理: Zustand (不用 Redux)
- 请求: 自定义 useFetch hook (不用 axios)
- 测试: vitest + @testing-library/react

## 目录结构
- src/app/ — 页面(App Router 约定)
- src/components/ — 可复用组件(PascalCase 命名)
- src/components/ui/ — 基础 UI 组件(Button, Input, Modal)
- src/stores/ — Zustand stores
- src/lib/ — 工具函数和 hooks
- src/types/ — 全局类型定义

## 组件规范
- 只用函数式组件,禁止 class 组件
- Props 用 interface 定义,命名为 XxxProps
- 事件处理函数命名: handleXxx (如 handleClick)
- 组件文件: PascalCase.tsx (如 UserCard.tsx)
- 工具文件: camelCase.ts (如 formatDate.ts)

## 样式规范
- 只用 Tailwind utility classes
- 响应式: 移动优先 (默认样式为移动端, lg: 为桌面)
- 颜色用项目定义的 design token (如 text-primary, bg-surface)
- 不写 style={{}} 内联样式

## 状态管理
- 服务端状态: 用 useFetch hook + SWR 缓存
- 客户端状态: Zustand store
- 组件内部状态: useState
- 禁止: prop drilling 超过 3 层

## 禁止事项
- 不用 any 类型(用 unknown + 类型守卫)
- 不引入 lodash / moment(用原生方法 / date-fns)
- 不用 CSS Modules / styled-components
- 不在组件中直接调用 fetch(用 useFetch hook)
- 不用 useEffect 做数据请求(用 SWR 或 React Query)
​

三、团队共享最佳实践

提交到 Git

git add .cursorrules
git commit -m "chore: add AI coding rules for team"
​

新同事 clone 项目后,Cursor 自动加载规范——不需要任何额外配置。

规范迭代

• 发现 AI 反复犯同一个错 → 加一条禁止事项
• 引入新技术(如从 Redux 迁移到 Zustand)→ 更新技术栈声明
• 团队 code review 发现风格不一致 → 补充代码约定

分文件组织(大项目)

对于 monorepo 或大型项目,可以用 .cursor/rules/ 目录:

.cursor/rules/
├── backend.md    ← 后端规范
├── frontend.md   ← 前端规范
├── testing.md    ← 测试规范
└── api-design.md ← API 设计规范
​

Cursor 会把所有文件合并注入上下文。好处是:各模块负责人维护自己的规范文件,互不干扰。

规范审查

像审查代码一样审查规范变更:

• 新加的规则是否具体可执行?
• 是否跟现有规则冲突?
• 是否会让文件超过 1500 字?

四、效果验证

配好规范后,验证效果:

测试 1:开新对话,说「帮我写一个用户删除接口」

• 无规范:可能给你 Flask 写法、同步数据库操作、try-catch 错误处理
• 有规范:FastAPI 路由 + async service + AppError + 统一响应格式

测试 2:说「创建一个按钮组件」

• 无规范:可能用 class 组件、CSS Modules、引入 UI 库
• 有规范:函数式组件 + Tailwind + TypeScript Props interface

如果输出明显符合你的规范 → 配置成功。如果偶尔还是「忘记」→ 检查规范是否写得够具体。

本节要点回顾

1. 后端规范核心:技术栈版本 + 目录结构 + 分层约定 + API 设计 + 禁止事项
2. 前端规范核心:组件模式 + 样式方案 + 状态管理 + 命名约定 + 禁止事项
3. 团队共享:提交到 Git,新人 clone 即用;像审查代码一样审查规范变更
4. 大项目:用 .cursor/rules/ 目录分文件组织,各模块独立维护
5. 持续迭代:发现 AI 反复犯错就加规则;技术栈变了就更新
6. 验证方法:开新对话测试输出是否符合规范

第 4 章完成。你现在拥有了让 AI「懂规矩」(Skills)和「看材料」(RAG)的完整能力。最后一章,我们把所有技能综合运用到实战中:从零构建一个全栈项目。