Cursor、Windsurf、Copilot TanStack 配置横向对比

**太长不看（TL;DR）：**每款 AI 编码工具都有不同的配置文件和技能加载机制。本文将针对 TanStack Start 横向对比这些工具：Cursor 的 .cursorrules 和 .cursor/skills、Windsurf 的 .windsurfrules、GitHub Copilot 的 .github/copilot-instructions.md，以及 Claude Code 的 CLAUDE.md 结合 TanStack Intent Skills。相同的项目，四套配置，以及直观的基准测试结果。

为什么不同编辑器的 AI 工具配置各不相同

每款 AI 编码工具均由不同的团队开发，对于开发者该如何配置 AI 行为，他们有着完全不同的心智模型。结果就是：同一个 TanStack Start 项目需要四种不同的配置文件，才能在所有编辑器中获得等效的行为表现。

好消息是：配置内容大体相同。这四个文件都在告诉 AI 应当遵循哪些规范、采用哪些模式，以及避免哪些错误。坏消息在于：文件路径和语法各不相同。

对于 TanStack Start 项目而言，这四款工具的目标始终一致：让 AI 生成专门针对 TanStack 的代码，而不是通用的 React 代码。TanStack Router 规范、Server Function 模式以及配合 D1 的 Drizzle 语法，都与大多数 AI 模型在训练数据中所习惯见到的内容截然不同。

我在所有四款编辑器中维护 TanStack Ship，因为真实用户会使用这其中的任何一款。本文中的每一段配置代码均取自真实通过测试的运行环境——绝非营销演示截图。

配置文件概览

针对 TanStack Start 的 Cursor 配置

Cursor 从两个数据源读取配置：项目级的 .cursorrules 文件以及定义在 .cursor/skills/ 中的特定主题技能（Skills）。

.cursorrules

# TanStack Start Project Rules

You are working on a TanStack Start project deployed to Cloudflare Workers.

## Stack
- TanStack Start + TanStack Router (file-based routing)
- TanStack Query + Server Functions for data
- Drizzle ORM + Cloudflare D1 for persistence
- Better Auth for authentication
- Stripe for payments
- Cloudflare R2 for storage

## Conventions
- File-based routes under `src/routes/`
- Use `createFileRoute()` for route definitions
- Server Functions in `src/server/<module>/`, not in route files
- Drizzle schemas split per route, not monolithic
- Query keys via `src/lib/query-keys.ts` factory

## Anti-patterns
- DO NOT use `react-router-dom` (use TanStack Router)
- DO NOT use `fetch` for data (use TanStack Query + Server Functions)
- DO NOT use Prisma (use Drizzle with D1)
- DO NOT co-locate Server Functions in route files

.cursor/skills/tanstack-router-routes.md

Cursor Skills 是一系列定义了任务专属提示词的 markdown 文件。对于 TanStack Router 而言：

# TanStack Router Route Generation

When asked to create a new route, follow this pattern:

```typescript
// src/routes/users.$userId.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/users/$userId')({
  loader: async ({ params, context }) => {
    return await context.queryClient.ensureQueryData({
      queryKey: ['user', params.userId],
      queryFn: () => fetchUser(params.userId),
    })
  },
  component: UserPage,
})

function UserPage() {
  const user = Route.useLoaderData()
  return <div>{user.name}</div>
}

Always use createFileRoute(). Never use react-router's Routes component. Never use BrowserRouter. File-based routing is the only correct pattern here.

该技能文件专门指导 Cursor 了解 TanStack Router 路由的结构方式——而非通用的 React 路由。

## 针对 TanStack Start 的 Windsurf 配置

Windsurf 使用 `.windsurfrules` 来设定项目级规则，并使用 `.windsurf/workflows/` 来存放可复用的任务模板。

### `.windsurfrules`

```markdown
# TanStack Start Project

Stack: TanStack Start + Cloudflare Workers + D1 + Drizzle + Better Auth + Stripe.

## Conventions
1. Routes are file-based under `src/routes/`. Use `createFileRoute()`.
2. Server Functions use `createServerFn()` from `@tanstack/react-start`.
3. Data fetching: TanStack Query + Server Functions, never raw `fetch`.
4. Database: Drizzle ORM with Cloudflare D1 (SQLite syntax).
5. Auth: Better Auth with edge-runtime session validation.
6. Payments: Stripe with idempotency via `webhook_events` table.

## Anti-patterns to avoid
- BrowserRouter / Routes from react-router — use TanStack Router.
- Prisma — use Drizzle.
- Co-located Server Functions — put them in `src/server/<module>/`.
- String query keys — use the `queryKeys` factory.
- Stripe webhooks without idempotency check.

.windsurf/workflows/new-route.md

Windsurf 的工作流定义了多步骤的任务模式：

# New TanStack Router Route

When asked to create a new TanStack Router route:

1. Determine the route path from the request.
2. Create the file at `src/routes/<path>.tsx`.
3. Use `createFileRoute()` with the appropriate path.
4. Add a `loader` if the route needs data.
5. Add `beforeLoad` if the route needs auth.
6. Use `Route.useLoaderData()` to access loader data.
7. Match the existing route patterns in the codebase.

针对 TanStack Start 的 GitHub Copilot 配置

GitHub Copilot 会读取 .github/copilot-instructions.md 文件。在处理复杂的、特定于框架的任务时，这是四款工具中最弱的一个，但如果有良好的指导说明，它的表现会得到显著提升。

.github/copilot-instructions.md

# TanStack Start Project

This project uses TanStack Start deployed to Cloudflare Workers.

## Tech stack
- TanStack Start + TanStack Router
- TanStack Query + Server Functions
- Drizzle ORM + Cloudflare D1
- Better Auth
- Stripe + webhook idempotency via `webhook_events` table
- Cloudflare R2

## Patterns

### Routes
File-based routing under `src/routes/`. Use `createFileRoute()` from `@tanstack/react-router`.

### Server Functions
Use `createServerFn()` from `@tanstack/react-start`. Validate inputs with Zod.

### Data fetching
TanStack Query with Server Functions. Use `queryKeys` factory from `src/lib/query-keys.ts`.

### Database
Drizzle ORM with D1 SQLite syntax. Schemas split per route under `src/db/<route>/`.

## Avoid
- react-router patterns (this is TanStack Router)
- Prisma (use Drizzle)
- Co-located Server Functions (use `src/server/<module>/`)
- String query keys (use the factory)

GitHub Copilot 对指令的支持正在不断改进，但与 Cursor、Windsurf 和 Claude Code 相比，在生成 TanStack 专属代码方面，它仍然是四者中最弱的。

Claude Code + TanStack Intent Skills

Claude Code 使用 CLAUDE.md 提供项目级上下文，但其在 TanStack 方面的专有优势来源于 TanStack Intent Skills —— 这些是随 TanStack 包一起发布且存放在 node_modules/<package>/.claude/skills/ 目录下的专属技能。

从 v1.0+ 开始，大多数 TanStack 生态包（含 Router、Query、Start、Form）都内置了 Intent Skills。当你安装某个 TanStack 包时，Claude Code 会自动读取其捆绑的技能。这意味着即使你的 CLAUDE.md 中并未提及，Claude Code 也能掌握针对 TanStack 的特定开发规范。

正是由于这一机制，Claude Code 成为了生成 TanStack 专属代码的最强选项：

1. 你安装了 @tanstack/react-router → Claude Code 会自动读取该路由器的 Intent Skills。
2. 你添加了自定义的 CLAUDE.md → Claude Code 会将你的项目规范与框架自身包含的技能进行合并。
3. 最终输出的代码会完美结合框架级规范与项目自身的特定模式。

关于 TanStack 项目的 CLAUDE.md 结构，在配合 TanStack Start 使用 Claude Code 这一指南中已有深入讲解。其核心部分包括：项目概览、技术栈、开发规范、应遵循的模式，以及需避免的反模式。

横向基准测试对比

相同的提示词集，使用四款工具，并基于输出质量进行评分（1 = 错误/过于通用，5 = 正确且符合 TanStack 规范）：

所有评分均为作者依据 2026 年在 8 个 TanStack Start 项目上的实际运行测试给出的预估结果。

核心发现：

• Claude Code + TanStack Intent 得分始终最高，因为 Intent Skills 补全了通用指令无法企及的框架级上下文信息。
• Cursor 与 Windsurf 的表现几乎完全相同 —— 二者都从 Skills/rules 配置中获益，且在未提供明确指令的情况下，同样难以掌握 TanStack Router 的规范。
• GitHub Copilot 垫底 —— .github/copilot-instructions.md 文件固然有一定帮助，但仍然不及专项技能系统的深度。
• 只要有合适的配置文件到位，这四款工具均能得到显著提升。若无配置，每一款工具都会退化使用泛泛的 React/Next.js 默认模式。

在针对 webhook 处理器的提示词上，差距表现得最为明显：只有 Claude Code（配合 Intent Skills）在初次尝试时便生成了完备且带有 webhook_events 表检查的幂等处理器。Cursor 和 Windsurf 生成的处理器虽然能处理事件，但遗漏了幂等性保障。而 Copilot 仅仅生成了一个缺乏相关表的基础处理器。

TanStack Ship 预先配置好的编辑器捆绑包

TanStack Ship 启动模板随附了已为您预先配置好的全部四种配置文件：

• .cursorrules + .cursor/skills/
• .windsurfrules + .windsurf/workflows/
• .github/copilot-instructions.md
• CLAUDE.md（外加由各 TanStack 包自带的 Intent Skills）

当你克隆下载 TanStack Ship 并使用上述任一编辑器打开项目时，AI 工具就会自动读取对应的配置项，并生成符合该平台开发规范的代码。这正是为何 TanStack Ship 主页上会标注 "AI-Optimized"（AI 优化）——这些配置严格依据平台架构进行定制，而非放之四海皆准的空泛模板。

应该选择哪款工具

老实说，这取决于你的个人工作流和首选编程语言：

• 对于特定于 TanStack 的工作而言，Claude Code 是你的最强之选，因为 TanStack Intent Skills 会随安装包自带。如果你经常进行 TanStack 的开发，首选非 Claude Code 莫属。
• 在全新项目开发方面，Cursor 能提供最顺滑打磨的使用体验。其 Skills 系统日臻成熟，且对于独立开发者来说交互体验堪称同类最佳。
• Windsurf 与 Cursor 相似，仅在用户体验和工作流设定上略有不同。有一部分开发者格外青睐其任务自动化的解决思路。
• GitHub Copilot 对于已经在使用 GitHub 原生工作流的团队来说是极佳选择。虽然它在不断改进中，但在面对特定框架代码的生成时依然最为薄弱。

在我接触过的大多数独立开发者中，他们往往将 Claude Code 或 Cursor 视为主力工具。只需准备一份高质量的 CLAUDE.md（对于 Claude Code）或者卓越的 .cursorrules（针对 Cursor），这两者之间的技术差距就能大幅缩小。

总结

每一款 AI 工具都具备截然不同的配置机制，但底层的核心内容却是完全一致的：都是围绕项目规范、技术栈、模式及反模式展开。尽管文件路径大相径庭，但最终目的殊途同归。

特别是涉及到 TanStack Start 时，Claude Code 加 TanStack Intent 可以说是所向披靡的最强组合。然而只要有恰当的配置辅助，四款工具的表现都能可圈可点。TanStack Ship 启动模板对这四套机制均做了完善预设，让你能够在切换工具的同时完整保有项目的 AI 上下文环境。

不妨立即前往 TanStack Ship GitHub 仓库下载配置包，然后无缝应用到你的任何 TanStack Start 项目中去。

关于本文

• 本文由 Huifer 撰写，作为独立开发者兼 TanStack Ship 的维护者。我在全部四款编辑器中兼顾维护 TanStack Ship，理由正因为真实用户同样遍及这四款工具。本文中的每一个配置片段均脱胎于真正跑通的测试验证。
• 官方验证来源： TanStack Start 文档 · Cursor 文档 · Windsurf 文档 · TanStack Ship GitHub
• 最后更新： 2026-07-25 · 变更日志

开始使用 TanStack Ship —— 包含全部四款 AI 编辑器的预设配置。克隆这个免费的新手引导模板 →