第 8 课：AI 编程工具

┌─────────────────────────────────────────────────────────────────┐
│  🎯 核心观点：AI 编程工具不只是代码补全，而是 AI 结对编程        │
├─────────────────────────────────────────────────────────────────┤
│  📚 你将学到：                                                   │
│    • 理解 AI 编程工具的三个层次（补全→对话→Agent）              │
│    • 深度掌握 Cursor 的核心功能和高级技巧                        │
│    • 学习 .cursorrules 和 Memory 管理的最佳实践                  │
│    • 横向对比 Cursor、Windsurf、Claude Code 等主流工具           │
│    • 掌握结构化 Prompt 提高 AI 输出质量的技巧                    │
└─────────────────────────────────────────────────────────────────┘

// 你写了
function getUserBy
// AI 补全
function getUserById(id: string) { ... }

// 你说
"创建一个用户资料页面，包含头像上传、表单验证、
保存到数据库。使用 Server Actions + Zod + shadcn/ui"

// AI 生成完整的页面代码

Prompt: "创建一个用户认证模块，包含：
1. 登录页面 (app/login/page.tsx)
2. 注册页面 (app/register/page.tsx)
3. Server Actions (app/actions/auth.ts)
4. Zod 验证 (lib/validations/auth.ts)
5. 用户类型定义 (types/user.ts)"

创建一个博客文章管理功能，要求：
1. 文章列表页面，支持分页和搜索
2. 文章详情页面，支持 Markdown 渲染
3. 文章编辑页面，使用富文本编辑器
4. Server Actions 处理 CRUD 操作
5. 使用 Prisma 操作数据库
6. 所有表单使用 React Hook Form + Zod 验证
7. 使用 shadcn/ui 组件库

import { Suspense } from 'react'
import { BlogList } from '@/components/features/blog/blog-list'
import { SearchBar } from '@/components/features/blog/search-bar'
import { Skeleton } from '@/components/ui/skeleton'

export default function BlogPage({
  searchParams,
}: {
  searchParams: { page?: string; q?: string }
}) {
  return (
    <div className="container mx-auto py-8">
      <h1 className="text-3xl font-bold mb-8">博客文章</h1>
      <SearchBar />
      <Suspense fallback={<Skeleton className="h-96" />}>
        <BlogList
          page={Number(searchParams.page) || 1}
          query={searchParams.q}
        />
      </Suspense>
    </div>
  )
}

import { notFound } from 'next/navigation'
import { getPostById } from '@/app/actions/blog'
import { MarkdownRenderer } from '@/components/features/blog/markdown-renderer'
import { Card } from '@/components/ui/card'

export default async function BlogPostPage({
  params,
}: {
  params: { id: string }
}) {
  const post = await getPostById(params.id)
  if (!post) notFound()

  return (
    <article className="container mx-auto py-8 max-w-4xl">
      <Card className="p-8">
        <h1 className="text-4xl font-bold mb-4">{post.title}</h1>
        <div className="text-muted-foreground mb-8">
          {new Date(post.createdAt).toLocaleDateString('zh-CN')}
        </div>
        <MarkdownRenderer content={post.content} />
      </Card>
    </article>
  )
}

'use server'

import { revalidatePath } from 'next/cache'
import { prisma } from '@/lib/prisma'
import { blogPostSchema, type BlogPostInput } from '@/lib/validations/blog'

export async function createPost(data: BlogPostInput) {
  const validated = blogPostSchema.parse(data)
  const post = await prisma.post.create({ data: validated })
  revalidatePath('/blog')
  return { success: true, post }
}

export async function updatePost(id: string, data: BlogPostInput) {
  const validated = blogPostSchema.parse(data)
  const post = await prisma.post.update({
    where: { id },
    data: validated,
  })
  revalidatePath('/blog')
  revalidatePath(`/blog/${id}`)
  return { success: true, post }
}

export async function deletePost(id: string) {
  await prisma.post.delete({ where: { id } })
  revalidatePath('/blog')
  return { success: true }
}

export async function getPosts(page = 1, query?: string) {
  const pageSize = 10
  const where = query
    ? {
        OR: [
          { title: { contains: query, mode: 'insensitive' as const } },
          { content: { contains: query, mode: 'insensitive' as const } },
        ],
      }
    : {}

  const [posts, total] = await Promise.all([
    prisma.post.findMany({
      where,
      skip: (page - 1) * pageSize,
      take: pageSize,
      orderBy: { createdAt: 'desc' },
    }),
    prisma.post.count({ where }),
  ])

  return { posts, total, pages: Math.ceil(total / pageSize) }
}

import { z } from 'zod'

export const blogPostSchema = z.object({
  title: z.string().min(1, '标题不能为空').max(200, '标题最多 200 字'),
  content: z.string().min(1, '内容不能为空'),
  excerpt: z.string().max(500, '摘要最多 500 字').optional(),
  published: z.boolean().default(false),
})

export type BlogPostInput = z.infer<typeof blogPostSchema>

'use client'

import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { blogPostSchema, type BlogPostInput } from '@/lib/validations/blog'
import { createPost, updatePost } from '@/app/actions/blog'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
import { Textarea } from '@/components/ui/textarea'
import { Form, FormControl, FormField, FormItem, FormLabel } from '@/components/ui/form'
import { useRouter } from 'next/navigation'
import { toast } from 'sonner'

interface BlogEditorProps {
  post?: BlogPostInput & { id: string }
}

export function BlogEditor({ post }: BlogEditorProps) {
  const router = useRouter()
  const form = useForm<BlogPostInput>({
    resolver: zodResolver(blogPostSchema),
    defaultValues: post ?? { title: '', content: '', published: false },
  })

  async function onSubmit(data: BlogPostInput) {
    const result = post
      ? await updatePost(post.id, data)
      : await createPost(data)

    if (result.success) {
      toast.success(post ? '文章已更新' : '文章已创建')
      router.push('/blog')
    }
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
        <FormField
          control={form.control}
          name="title"
          render={({ field }) => (
            <FormItem>
              <FormLabel>标题</FormLabel>
              <FormControl>
                <Input placeholder="输入文章标题" {...field} />
              </FormControl>
            </FormItem>
          )}
        />
        <FormField
          control={form.control}
          name="content"
          render={({ field }) => (
            <FormItem>
              <FormLabel>内容</FormLabel>
              <FormControl>
                <Textarea
                  placeholder="输入文章内容（支持 Markdown）"
                  className="min-h-[400px]"
                  {...field}
                />
              </FormControl>
            </FormItem>
          )}
        />
        <Button type="submit" disabled={form.formState.isSubmitting}>
          {form.formState.isSubmitting ? '保存中...' : '保存文章'}
        </Button>
      </form>
    </Form>
  )
}

你：这个组件的性能有什么问题？
Cursor：我看到这个组件在每次渲染时都会重新创建 handleClick 函数，
建议用 useCallback 包裹。另外，UserList 组件没有用 React.memo，
当父组件重新渲染时会导致不必要的重渲染。

你：@ProductList.tsx 这个组件渲染很慢，帮我分析一下性能问题

Cursor：我分析了 ProductList.tsx，发现以下性能问题：

1. **重复计算**：第 23 行的 filteredProducts 在每次渲染时都会重新计算，
   但 products 和 filter 并不是每次都变化。建议用 useMemo：

   const filteredProducts = useMemo(
     () => products.filter(p => p.category === filter),
     [products, filter]
   )

2. **子组件重渲染**：ProductCard 没有用 React.memo 包裹，
   当列表重新渲染时，所有卡片都会重新渲染，即使 props 没变。

3. **大列表没有虚拟化**：你有 2000+ 条产品数据，建议使用
   @tanstack/react-virtual 做虚拟滚动，只渲染可视区域的元素。

4. **图片没有懒加载**：ProductCard 里的图片建议使用 next/image
   的 loading="lazy" 属性。

需要我帮你逐一修复吗？

你：先修复前两个问题

Cursor：好的，我来修改...
[Cursor 直接在编辑器中修改代码，你可以看到 diff]

你：用户反馈登录后偶尔会被踢出来，帮我排查一下认证相关的代码
    @middleware.ts @lib/auth.ts @app/api/auth/[...nextauth]/route.ts

Cursor：我检查了这三个文件，发现一个潜在问题：

在 middleware.ts 第 15 行，你检查 token 是否过期用的是：
  if (token.exp < Date.now())

这里有个 Bug：JWT 的 exp 字段是秒级时间戳，而 Date.now() 返回的是
毫秒级时间戳。正确的写法应该是：
  if (token.exp < Date.now() / 1000)

或者用 Math.floor：
  if (token.exp < Math.floor(Date.now() / 1000))

这会导致 token 看起来"总是过期的"，但因为你在 lib/auth.ts 里有
refresh 逻辑，所以大部分时候能自动续期。但在网络延迟较高时，
refresh 请求还没回来，用户就被踢出了。

你：太好了，帮我修复

Cursor：[直接修改 middleware.ts 中的代码]

选中一个 div，输入："改成 shadcn/ui 的 Card 组件，添加 hover 动画"

// 选中这段代码
<div className="border rounded p-4">
  <img src={user.avatar} />
  <h3>{user.name}</h3>
  <p>{user.email}</p>
  <button onClick={handleEdit}>编辑</button>
</div>

改成 shadcn/ui 的 Card 组件，头像用 Avatar，按钮用 Button，
添加 hover 时 shadow-lg 的过渡动画

<Card className="p-4 transition-shadow hover:shadow-lg">
  <CardHeader className="flex flex-row items-center gap-4">
    <Avatar>
      <AvatarImage src={user.avatar} alt={user.name} />
      <AvatarFallback>{user.name[0]}</AvatarFallback>
    </Avatar>
    <div>
      <CardTitle>{user.name}</CardTitle>
      <CardDescription>{user.email}</CardDescription>
    </div>
  </CardHeader>
  <CardFooter>
    <Button variant="outline" onClick={handleEdit}>编辑</Button>
  </CardFooter>
</Card>

// 选中这段代码
async function fetchUsers() {
  const res = await fetch('/api/users')
  const data = await res.json()
  setUsers(data)
}

添加 try-catch 错误处理、loading 状态、错误提示 toast

async function fetchUsers() {
  setLoading(true)
  try {
    const res = await fetch('/api/users')
    if (!res.ok) {
      throw new Error(`请求失败: ${res.status}`)
    }
    const data = await res.json()
    setUsers(data)
  } catch (error) {
    console.error('获取用户列表失败:', error)
    toast.error('获取用户列表失败，请稍后重试')
  } finally {
    setLoading(false)
  }
}

// 选中这段代码
function formatPrice(price, currency, locale) {
  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency: currency,
  }).format(price)
}

转成 TypeScript，添加完整的类型定义，currency 用联合类型限制常用货币

type CurrencyCode = 'CNY' | 'USD' | 'EUR' | 'JPY' | 'GBP'

interface FormatPriceOptions {
  price: number
  currency: CurrencyCode
  locale?: string
}

function formatPrice({
  price,
  currency,
  locale = 'zh-CN',
}: FormatPriceOptions): string {
  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency,
  }).format(price)
}

# .cursorrules

## 技术栈
- React 19 + Next.js 15 App Router
- TypeScript (strict mode)
- Tailwind CSS v4
- shadcn/ui + Radix UI
- Zustand + TanStack Query
- React Hook Form + Zod

## 代码规范
- 使用函数式组件 + Hooks
- Props 类型使用 interface
- 导出使用命名导出
- 样式只用 Tailwind utility classes
- 优先使用 shadcn/ui 组件

## 文件路径
- UI 组件: components/ui/
- 业务组件: components/features/
- Hooks: hooks/
- Utils: lib/
- Types: types/

## 导入顺序
1. React 相关
2. 第三方库
3. 本地组件
4. 本地 hooks
5. 本地 utils
6. 类型定义

## 禁止
- 不使用 any
- 不写内联样式
- 不使用 CSS-in-JS
- 不直接修改 shadcn/ui 组件源码
- 不使用 useEffect 做数据请求

# .cursorrules - Next.js 全栈项目

## 技术栈
- Next.js 15 App Router + React 19
- TypeScript strict mode
- Tailwind CSS v4 + shadcn/ui
- Prisma ORM + PostgreSQL
- NextAuth.js v5 认证
- Zustand 状态管理
- TanStack Query 数据请求

## 路由规范
- 页面路由: app/(routes)/
- API 路由: app/api/
- Server Actions: app/actions/
- 布局: app/(routes)/layout.tsx
- 错误边界: app/(routes)/error.tsx

## 数据获取规范
- 服务端数据: 直接在 Server Component 中 await
- 客户端数据: 使用 TanStack Query 的 useQuery
- 表单提交: 使用 Server Actions + useActionState
- 禁止在 useEffect 中 fetch 数据

## 认证规范
- 服务端获取 session: auth() from @/lib/auth
- 客户端获取 session: useSession() from next-auth/react
- 受保护路由: 在 middleware.ts 中统一处理
- API 路由认证: 每个路由开头检查 session

# .cursorrules - React 组件库

## 技术栈
- React 19 + TypeScript
- Storybook 8 文档
- Vitest + Testing Library 测试
- Tailwind CSS v4
- Radix UI 无障碍基础

## 组件规范
- 每个组件一个文件夹: components/Button/
  - Button.tsx (组件实现)
  - Button.stories.tsx (Storybook 文档)
  - Button.test.tsx (单元测试)
  - index.ts (导出)
- 所有组件必须支持 ref 转发 (forwardRef)
- 所有组件必须支持 className 合并 (cn 工具函数)
- 所有交互组件必须支持键盘操作
- 必须提供 aria-label 或 aria-labelledby

## 样式规范
- 使用 cva (class-variance-authority) 管理变体
- 使用 tailwind-merge 合并 className
- 支持 size: sm | md | lg 和 variant: default | outline | ghost

## 测试规范
- 每个组件至少覆盖: 渲染、交互、无障碍
- 使用 @testing-library/user-event 模拟用户操作
- 使用 axe-core 检查无障碍合规

# .cursorrules - Taro 小程序项目

## 技术栈
- Taro 4 + React 19
- TypeScript strict mode
- NutUI 组件库
- Zustand 状态管理

## 文件规范
- 页面: src/pages/[name]/index.tsx
- 组件: src/components/[Name]/index.tsx
- 样式: 与组件同目录，使用 CSS Modules (.module.scss)
- API: src/services/[module].ts
- 类型: src/types/[module].ts

## 小程序特殊规范
- 使用 Taro.navigateTo 而非 window.location
- 使用 Taro.getStorageSync 而非 localStorage
- 图片必须使用 CDN 地址，不要用本地图片
- 页面配置写在 [page].config.ts 中
- 注意包体积，单个分包不超过 2MB

## 禁止
- 不使用 DOM API (document.querySelector 等)
- 不使用 window 对象
- 不使用 CSS 动画 (用 Taro.createAnimation)
- 不引入超过 50KB 的第三方库

# 项目 AI 开发指南

## 项目概述
- 项目名称：AI Todo App
- 技术栈：Next.js 15 + TypeScript + Tailwind v4 + shadcn/ui

## 技术决策历史
- 2026-03-15: 选择 Tailwind v4 而非 UnoCSS（生态更成熟）
- 2026-03-10: 使用 Zustand 而非 Redux（更轻量）

## 已知问题
- UserProfile 组件的性能问题已在 PR #123 修复
- Safari 浏览器的 Flexbox 问题需要 -webkit- 前缀

## 团队约定
- 所有 API 请求必须有错误处理
- 表单必须使用 React Hook Form + Zod
- 新功能必须有单元测试

## 禁止事项
- ❌ 不要使用 any 类型
- ❌ 不要直接修改 components/ui/ 下的组件
- ❌ 不要使用 useEffect 做数据请求

# AGENTS.md - [项目名称] AI 开发指南
# 最后更新: 2026-03-26
# 维护人: [团队负责人]

## 一、项目概述

### 基本信息
- 项目名称: 智能客服管理平台
- 项目类型: B 端 SaaS 应用
- 目标用户: 企业客服团队管理者
- 当前版本: v2.3.0
- 仓库地址: https://github.com/company/cs-platform

### 技术栈
- 框架: Next.js 15 (App Router)
- 语言: TypeScript 5.x (strict mode)
- 样式: Tailwind CSS v4 + shadcn/ui
- 状态管理: Zustand (全局) + TanStack Query (服务端)
- 表单: React Hook Form + Zod
- ORM: Prisma + PostgreSQL
- 认证: NextAuth.js v5
- 测试: Vitest + Testing Library + Playwright
- 部署: Vercel + Neon Database

### 项目结构
app/
├── (auth)/          # 认证相关页面 (登录/注册)
├── (dashboard)/     # 主面板 (需要登录)
│   ├── tickets/     # 工单管理
│   ├── customers/   # 客户管理
│   ├── analytics/   # 数据分析
│   └── settings/    # 系统设置
├── api/             # API 路由
└── actions/         # Server Actions

components/
├── ui/              # shadcn/ui 组件 (不要修改)
├── features/        # 业务组件 (按功能模块分)
├── layouts/         # 布局组件
└── shared/          # 通用业务组件

lib/
├── prisma.ts        # Prisma 客户端
├── auth.ts          # NextAuth 配置
├── utils.ts         # 工具函数
└── validations/     # Zod schemas

## 二、技术决策记录 (ADR)

### ADR-001: 状态管理选型 (2026-01-15)
- 决策: Zustand + TanStack Query
- 原因: Redux 对于本项目过重，Zustand API 更简洁
- TanStack Query 专门处理服务端状态，避免手动管理缓存
- 影响: 所有服务端数据请求必须通过 useQuery/useMutation

### ADR-002: 表单方案 (2026-01-20)
- 决策: React Hook Form + Zod
- 原因: 性能好（非受控组件），Zod 提供运行时类型验证
- 影响: 所有表单必须定义 Zod schema，禁止手动 validate

### ADR-003: 样式方案 (2026-02-01)
- 决策: Tailwind CSS v4 + shadcn/ui
- 原因: 原子化 CSS 减少样式冲突，shadcn/ui 可定制性强
- 影响: 禁止使用 CSS Modules、styled-components 等方案

### ADR-004: 测试策略 (2026-02-10)
- 决策: 单元测试 Vitest + 集成测试 Testing Library + E2E Playwright
- 覆盖率要求: 核心业务逻辑 > 80%
- 影响: 每个 PR 必须包含对应测试

## 三、编码规范

### 组件规范
- 使用函数式组件 + Hooks
- Props 类型使用 interface，命名为 [组件名]Props
- 导出使用命名导出 (export function)，不用 default export
- 组件文件名使用 kebab-case (user-profile.tsx)
- 组件名使用 PascalCase (UserProfile)

### 命名规范
- 变量/函数: camelCase (getUserById)
- 类型/接口: PascalCase (UserProfile)
- 常量: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)
- 文件名: kebab-case (user-profile.tsx)
- CSS 类名: Tailwind utility classes

### 导入顺序 (已配置 ESLint 自动排序)
1. React / Next.js
2. 第三方库
3. @/components/ui
4. @/components/features
5. @/hooks
6. @/lib
7. @/types
8. 相对路径导入

### 错误处理规范
- Server Actions: 返回 { success, data?, error? } 格式
- API 路由: 使用统一的 ApiResponse 类型
- 客户端: 使用 toast 提示用户，console.error 记录详情
- 异步操作: 必须有 try-catch，必须有 loading 状态

## 四、已知问题和注意事项

### 已知 Bug
- [OPEN] #234: Safari 下日期选择器偶尔闪烁
- [FIXED] #198: 工单列表分页在筛选后重置 (v2.2.1 修复)

### 性能注意事项
- tickets 列表超过 1000 条时需要虚拟滚动
- analytics 页面的图表数据需要在服务端聚合，不要在客户端处理
- 图片上传必须先压缩到 500KB 以下

### 安全注意事项
- 所有 Server Actions 必须检查用户权限
- 用户输入必须经过 Zod 验证后才能入库
- 敏感数据 (密码、token) 不要出现在日志中

## 五、常用命令

- 开发: pnpm dev
- 构建: pnpm build
- 测试: pnpm test
- Lint: pnpm lint
- 数据库迁移: pnpm prisma migrate dev
- 生成 Prisma 客户端: pnpm prisma generate

## 六、团队成员和职责

- 前端负责人: @zhangsan - 架构决策、代码审查
- 后端对接: @lisi - API 设计、数据库 schema
- UI 设计: @wangwu - 设计稿在 Figma，链接见 README

好的示例：
"我正在重构用户认证模块。已完成登录页面（使用 React Hook Form + Zod），
现在要做注册页面。要求保持与登录页面一致的风格和验证逻辑。
登录页面的 Zod schema 在 lib/validations/auth.ts"

不好的示例：
"帮我做注册页面"  ← 缺少上下文

# preferences.md

## 代码风格
- 我喜欢函数式组件
- 我喜欢用 const 而非 let
- 我喜欢用解构赋值

## 工具偏好
- 包管理器：pnpm
- 测试框架：Vitest
- 状态管理：Zustand

# Memory 月度检查清单

## 1. AGENTS.md 检查
- [ ] 技术栈版本是否需要更新？（比如 Next.js 升级了）
- [ ] 有没有新的技术决策需要记录？
- [ ] 已知问题列表：哪些已经修复了？标记为 [FIXED]
- [ ] 有没有新发现的 Bug 需要加进去？
- [ ] 团队约定有没有变化？（比如新的代码规范）
- [ ] 项目结构有没有变化？（比如新增了模块）
- [ ] 安全注意事项有没有更新？

## 2. .cursorrules 检查
- [ ] 技术栈版本号是否最新？
- [ ] 有没有新引入的库需要加到规范里？
- [ ] 禁止事项有没有需要更新的？
- [ ] 文件路径规范是否还准确？

## 3. 个人 Memory 检查
- [ ] 工具偏好有没有变化？
- [ ] 代码风格偏好有没有调整？
- [ ] 有没有新的快捷方式或工作流值得记录？

## 4. 清理
- [ ] 删除超过 3 个月的已修复 Bug 记录
- [ ] 删除已废弃的技术决策
- [ ] 合并重复的规范条目

第一步：小王 clone 项目，打开 Cursor

第二步：Cursor 自动读取 AGENTS.md 和 .cursorrules

第三步：小王在 Chat 里问：
"我是新加入的成员，帮我梳理一下这个项目的整体架构和开发规范"

Cursor 回答（基于 AGENTS.md）：
"这是一个智能客服管理平台，使用 Next.js 15 App Router...
主要模块有工单管理、客户管理、数据分析...
代码规范要求使用函数式组件、命名导出...
表单统一使用 React Hook Form + Zod...
状态管理用 Zustand（全局）和 TanStack Query（服务端）..."

第四步：小王开始写第一个功能
"我要在工单管理模块添加一个批量操作功能"

Cursor 生成的代码自动遵循项目规范：
- 使用了正确的文件路径 (app/(dashboard)/tickets/)
- 使用了 shadcn/ui 组件
- 使用了 Server Actions
- 添加了权限检查（因为 AGENTS.md 里写了安全规范）
- 使用了 Zod 验证

## 已知问题
- [OPEN] Safari 不支持 YYYY-MM-DD 格式的日期字符串。
  解决方案：使用 dayjs 或 date-fns 解析日期，不要直接 new Date(string)。
  相关 PR: #156

[角色] + [上下文] + [任务] + [约束] + [输出格式]

你是一个 React 前端工程师。
我们的项目使用 Next.js 15 + Tailwind v4 + shadcn/ui。
请创建一个用户设置页面，包含个人信息表单和通知设置。
要求：使用 React Hook Form + Zod 验证，支持暗色模式。
输出完整的 TypeScript 代码。

"使用 shadcn/ui 的 Card、Form、Input、Button 组件"

"使用 Tailwind 的 grid 布局，移动端单列，桌面端双列"

"表单提交时显示 loading 状态，成功后显示 toast 提示"

创建 [页面名称] 页面。

技术要求：
- 路由路径: app/(dashboard)/[path]/page.tsx
- 使用 shadcn/ui 的 [具体组件列表]
- 数据通过 Server Component 直接获取
- 支持响应式布局（移动端单列，桌面端 [N] 列）

功能要求：
- [功能点 1]
- [功能点 2]
- [功能点 3]

参考现有页面: @[已有的类似页面路径]

创建一个 [表单名称] 表单组件。

字段：
- [字段名] ([类型]): [验证规则]
- [字段名] ([类型]): [验证规则]

要求：
- 使用 React Hook Form + Zod 验证
- 使用 shadcn/ui 的 Form 组件
- 提交时调用 Server Action: [action 名称]
- 提交中显示 loading，成功显示 toast
- 支持编辑模式（传入初始值）

创建一个 [数据名称] 的数据表格。

列定义：
- [列名]: [数据类型], [是否可排序], [特殊渲染]
- [列名]: [数据类型], [是否可排序], [特殊渲染]

功能要求：
- 使用 @tanstack/react-table
- 支持分页（每页 [N] 条）
- 支持按 [字段] 搜索
- 支持按 [字段] 筛选
- 每行有操作按钮：[查看/编辑/删除]
- 使用 shadcn/ui 的 Table + DropdownMenu

分析 @[文件路径] 的性能问题。

关注点：
- 不必要的重渲染
- 缺少 memoization 的计算
- 大列表是否需要虚拟化
- 图片和资源加载优化
- Bundle size 影响

请给出具体的优化建议和修改后的代码。

为 @[文件路径] 编写单元测试。

测试框架: Vitest + Testing Library
覆盖场景：
- 正常渲染
- 用户交互（点击、输入、提交）
- 边界情况（空数据、错误状态、loading 状态）
- Props 变化

Mock 说明：
- [需要 mock 的依赖]
- API 请求使用 msw

重构 @[文件路径]。

当前问题：
- [问题 1]
- [问题 2]

重构目标：
- [目标 1]
- [目标 2]

约束：
- 不改变外部 API（Props 和导出保持不变）
- 保持现有测试通过
- 拆分后的文件放在同一目录下

创建与 [API 名称] 的集成代码。

API 信息：
- 基础 URL: [URL]
- 认证方式: [Bearer Token / API Key]
- 需要对接的接口：
  - GET [endpoint]: [描述]
  - POST [endpoint]: [描述]

要求：
- 创建类型安全的 API 客户端 (lib/api/[name].ts)
- 创建对应的 TanStack Query hooks (hooks/use-[name].ts)
- 统一错误处理
- 请求/响应类型定义 (types/[name].ts)

将 @[文件路径] 改为响应式布局。

断点要求：
- 移动端 (< 768px): [布局描述]
- 平板 (768px - 1024px): [布局描述]
- 桌面 (> 1024px): [布局描述]

使用 Tailwind 的响应式前缀 (sm/md/lg/xl)。
导航栏在移动端改为汉堡菜单。
表格在移动端改为卡片列表。

创建 [模块名] 的状态管理。

状态结构：
- [状态字段]: [类型] - [描述]
- [状态字段]: [类型] - [描述]

Actions：
- [action 名]: [描述]
- [action 名]: [描述]

要求：
- 使用 Zustand
- 支持 devtools 中间件
- 支持 persist 中间件（存储到 localStorage）
- 创建对应的 selector hooks

为 @[目录路径] 添加完整的错误处理。

要求：
- 创建 error.tsx 错误边界组件
- 创建 loading.tsx 加载状态组件
- 创建 not-found.tsx 404 页面
- 错误边界支持重试功能
- loading 使用 shadcn/ui 的 Skeleton
- 所有异步操作添加 try-catch
- 用户友好的错误提示（不暴露技术细节）

❌ 错误: "帮我做一个登录页面"

✅ 改进: "创建登录页面 app/(auth)/login/page.tsx。
使用 shadcn/ui 的 Card + Form + Input + Button。
表单字段：邮箱（email 格式验证）和密码（最少 8 位）。
使用 React Hook Form + Zod。
提交调用 Server Action signIn()。
支持 GitHub OAuth 登录按钮。
页面居中显示，最大宽度 400px。"

❌ 错误: "帮我做一个完整的电商网站，包含商品列表、购物车、
订单管理、用户中心、支付集成、物流追踪..."

✅ 改进: "先创建商品列表页面。
路由: app/(shop)/products/page.tsx
功能: 商品卡片网格展示，支持按分类筛选和价格排序。
每个商品卡片显示：图片、名称、价格、加入购物车按钮。
使用 shadcn/ui 的 Card + Select + Button。
数据通过 Server Component 从 Prisma 获取。"

❌ 错误: "帮我做一个状态管理"

✅ 改进: "使用 Zustand 创建购物车状态管理 (stores/cart-store.ts)。
状态: items (CartItem[])、total (number)
Actions: addItem、removeItem、updateQuantity、clearCart
CartItem 类型: { id, name, price, quantity, image }
添加 devtools 中间件用于调试。
创建 useCartStore hook 和 selector: useCartItems、useCartTotal。"

❌ 错误: "帮我写一个和登录页面风格一样的注册页面"
（AI 不知道登录页面长什么样）

✅ 改进: "参考 @app/(auth)/login/page.tsx 的风格和布局，
创建注册页面 @app/(auth)/register/page.tsx。
额外字段：用户名（3-20 字符）、确认密码。
Zod schema 放在 @lib/validations/auth.ts（和登录共用文件）。
复用登录页面的 AuthCard 布局组件。"

你：为什么你用了 useEffect 来请求数据？我们的规范是用 TanStack Query。

Cursor：抱歉，我来修改。使用 useQuery 替代...

你：不要这样写：
const data = await fetch('/api/users').then(r => r.json())

要这样写：
const { data } = useQuery({
  queryKey: ['users'],
  queryFn: () => apiClient.getUsers()
})

请按这个模式重新生成。

第一步：先只生成 Zod schema 和类型定义，我确认后再继续。

你：在写代码之前，先告诉我你打算怎么实现这个功能。
列出你会创建哪些文件，每个文件的职责是什么。

"我要给这个项目添加国际化支持"

Windsurf Flow 执行过程：

Step 1/6: 分析项目结构，识别需要国际化的组件
→ 扫描到 23 个包含硬编码中文的组件

Step 2/6: 安装 next-intl 依赖
→ 执行 pnpm add next-intl

Step 3/6: 创建 i18n 配置文件
→ 创建 i18n.ts、middleware.ts 配置

Step 4/6: 创建中文和英文语言文件
→ 创建 messages/zh.json、messages/en.json
→ 从 23 个组件中提取所有中文文本

Step 5/6: 修改组件，替换硬编码文本为 t() 调用
→ 修改 23 个组件文件

Step 6/6: 创建语言切换组件
→ 创建 LanguageSwitcher 组件并添加到导航栏

完成！共修改 28 个文件。

# 启动 Claude Code
$ claude

# 直接描述需求
> 帮我看看 src/components/UserProfile.tsx 有什么性能问题

Claude: 我来读取这个文件...
[读取文件内容]
我发现了 3 个性能问题：
1. useEffect 中的依赖数组缺少 userId
2. 每次渲染都创建新的 style 对象
3. 子组件 AvatarUploader 没有 memo
我来修复这些问题...
[自动修改文件]
修复完成。要我运行测试确认吗？

> 是的，运行测试

Claude: [执行 pnpm test src/components/UserProfile.test.tsx]
所有 12 个测试用例通过。

> 顺便帮我把这个组件的测试覆盖率提高到 90% 以上

Claude: 当前覆盖率是 67%。我来分析缺少覆盖的分支...
[读取测试文件和源文件]
需要添加以下测试用例：
- 头像上传失败的错误处理
- 网络断开时的重试逻辑
- 表单验证的边界情况
[自动创建新的测试用例]
[执行测试]
覆盖率已提升到 93%。