本文由 Huifer 撰写，他是 TanStack Ship 的独立开发者与维护者。 在 2026 年 1 月至 6 月期间，我在 8 个 TanStack Start 项目中使用了 Claude Code。本文所分享的模式都经历了严格的代码审查并最终交付上线到生产环境，绝非那些仅仅在推文里博人眼球的玩具代码。
验证来源：TanStack Ship GitHub · TanStack Start Docs 最后更新：2026-07-22 · 更新日志
太长不看（TL;DR）： 如果提供正确的上下文，Claude Code 将彻底改变 TanStack Start 的开发体验。精心编写的 CLAUDE.md 文件是你所能做出的最高投资回报率（ROI）的举措。本文包含一个经生产验证的 CLAUDE.md 模板以及 10 个真正行之有效的提示词。
为什么 CLAUDE.md 对 TanStack 项目至关重要
当你在全新的 TanStack Start 项目中启动 Claude Code 时，AI 对你的技术栈一无所知。它只看得到 TypeScript、React 和一些通用的模式。如果没有明确的上下文，它生成的代码往往会与你的约定相冲突，而不是遵循它们。这些代码表面上看起来毫无瑕疵，却无法与 TanStack Start 的特定模式兼容。
CLAUDE.md 文件能够告诉 Claude Code 它所需了解的一切：你的路由约定、服务器函数模式、身份验证流程以及部署目标。这是产生需要花费 30 分钟清理的代码，还是直接交付上线的代码之间的核心区别。
自 2026 年 1 月以来，我已经借助 Claude Code 交付上线了 8 个 TanStack Start 项目。那些有效的提示词都具有一致的结构。而失败的提示词也有着可预测的模式。本指南将分享真正行之有效的经验，并帮助你避开那些曾耗费我数小时进行清理的失败陷阱。
设置流程
在编写提示词之前，请先正确设置 Claude Code。这个过程只需五分钟，日后却能为你节省数小时。
通过 npm 在系统全局安装 Claude Code。导航至你的项目目录，并在终端中启动 Claude Code。在项目根目录下创建一个 CLAUDE.md 文件。当你启动 Claude Code 时，CLAUDE.md 文件会自动加载；因此无论何时你开启新对话，Claude 都会读取此文件，并将其作为你所有请求的上下文。
这种自动加载机制非常强大。这让你无需重复赘述，每次对话都会在相同的上下文中展开。当你需要为特定任务采用不同行为时，你也可以使用项目特定的指令来覆写个别对话中的 CLAUDE.md 设定。
一份高效 CLAUDE.md 的结构剖析
适用于 TanStack Start 的 CLAUDE.md 包含四个核心部分。每部分都有着特定作用，它们共同为 Claude Code 提供了生成符合你既定约定的代码所需上下文。
项目概览
从基础信息开始——框架版本、部署目标以及关键依赖。这部分内容告诉 Claude Code 正在处理什么样的应用程序，以及运用了哪些技术。指定版本时必须精确，因为不同版本间的行为存在差异，知晓准确版本有助于 Claude 生成相互兼容的代码。
# TanStack Ship Project
This is a TanStack Start application deployed on Cloudflare Workers.
- Framework: TanStack Start 1.x
- Router: TanStack Router with type-safe routes
- Database: D1 (SQLite) with Drizzle ORM
- Auth: Better Auth with edge-compatible sessions
- Payments: Stripe subscriptions
- Deployment: Cloudflare Workers (edge)
## Package Versions
- @tanstack/react-router: ^1.x
- @tanstack/start: ^1.x
- drizzle-orm: ^0.30.x
- better-auth: ^1.x
关键约定
请务必记录那些有别于标准 React 的模式。这是绝大多数开发者节省时间的关键点，因为 Claude 依此能够学习你的定制模式，从而避免生成与你的架构极不适应的通用代码。
TanStack Start 使用服务器函数处理数据变更（mutations），它们仅在服务端运行，不可访问客户端状态。身份验证逻辑应当放置在 beforeLoad 钩子函数里，而不是随意的组件中，以确保认证逻辑名副其实地留在服务端。路由参数通过路由器保持类型安全，而非运用通用的 useParams 钩子进行解析。深入理解这些模式，才能真正编写出能够提供实质协助的 CLAUDE.md 文件。
## Routing
Routes live in `src/routes/`. Each route file exports:
- `route` — the route configuration
- `component` — the page component
- `loader` — server-side data fetching
- `beforeLoad` — authentication guards
Never use `useParams()` for typed route params.
Use `route.useParams()` instead.
## Server Functions
Mutations use `createServerFn()`:
- Server functions run on the server only
- Import from `@tanstack/start/server`
- Return typed responses
- Handle errors with Result types
## Authentication
All protected routes use `beforeLoad`:
```typescript
beforeLoad: ({ context, location }) => {
if (!context.session) {
return redirect('/login');
}
}
### 文件命名约定
TanStack Start 有着严格的命名规范，这也是 Claude 需要了解的。违背这些约定会导致通常难以排错的隐形故障，往往代码表面看起来正确却无法运行。路由文件必须使用路由前缀。索引路由须要运用 index 关键字。布局路由同样要用 layout 关键字。API 路由应当置于 api 子目录。弄懂这些规范，能帮助你编写出防患于未然的 CLAUDE.md 文件。
### 应当避免的反模式
本节旨在防止 Claude Code 犯下最典型的一些错误。若缺少它，Claude 很容易生成看似正确但无法在 TanStack Start 架构中成功运行的模式。这恰好也是我在审查经过 Claude 生成的代码时，目睹最频繁的反模式。
```markdown
## Don't Do These
1. Don't use `fetch()` directly in components—use loaders
2. Don't create client-side-only mutations—use server functions
3. Don't use React Router directly—use TanStack Router APIs
4. Don't hardcode URLs—use `to` from route components
5. Don't put auth logic in components—use beforeLoad guards
6. Don't use environment variables directly—use `runtimeConfig`
10 个切实有效的提示词
这些提示词已经在多个项目的生产环境中成功交付上线了。你可以将它们复制到 Claude Code 的对话中，并针对你的项目细节做出微调。针对能生成直接正常运作的代码或是需要进行多少人工清理，我们对每一个提示词都进行了深度的提炼与验证。
1. 路由生成
当需要处理新路由时，请明确告知你需要它具体实现什么功能及其所需的数据。你需要提供 URL 路径、认证要求以及一切形式的数据拉取或数据变更。你的描述越具体，Claude 就越能够恰如其分地生成符合你心意的代码。
提示词： "创建一个位于 /dashboard/settings 的新路由，包含：
- 受身份验证保护（未验证时重定向到 /login）
- 能够从 D1 拉取用户偏好的 loader
- 包含姓名、邮箱以及时区字段的设置表单组件
- 用于更新用户偏好的服务器函数
- 使用 CLAUDE.md 中的 TanStack Start 约定"
Claude 生成好路由后，请第一时间核实 beforeLoad 是否规范处理了身份验证、loader 是否返回了具有明确类型的数据，以及服务器函数是否准确调用了 createServerFn。这是尽早在代码审查中发现高频失误的最佳节点。
2. Drizzle Schema
向系统追加数据库表再直截了当不过了，只要你给 Claude 提供你所需要的精确 Schema 结构，包含各项字段名称、类型以及全部限制条件。务必明确指出外键和索引，毕竟 Drizzle 要求显式定义它们，而不是自行推断关联关系。
提示词： "向现有的 Drizzle schema 中添加一个 subscriptions 表，字段包含 id（cuid2 主键）、userId（指向 users 表的外键）、stripeCustomerId、枚举值为 'free' | 'pro' | 'enterprise' 的 plan、值为 'active' | 'canceled' | 'past_due' 的 status、以 Unix 整数时间戳表示的 currentPeriodEnd，以及以 now 为默认值的 Unix 时间戳 createdAt。请为 userId 和 status 添加适当的索引，并添加与 users 表的关联关系。"
3. Stripe Webhook 处理器
由于牵扯到实际资金，Stripe webhooks 向来必须经过最谨慎的处理。尽管 Claude 可为你生成代码结构，但你仍旧有待亲自复核事件处置逻辑本身的严谨合规度。Webhook 处理器势必要兼具幂等性、极速且安全的属性。
提示词： "在 /src/routes/api/stripe-webhooks.ts 中创建一个 Stripe webhook 处理程序，使用 STRIPE_WEBHOOK_SECRET 环境变量验证 Stripe 签名，处理订阅生命周期事件（created、updated、deleted），同步更新数据库，使用事件 ID 正确处理幂等性，立即返回 200 以防止 Stripe 超时，记录所有附带时间戳的事件，并使用适当的错误处理机制为意外错误返回 500。"
4. R2 文件上传
受限于边缘运行时的种种约束，向 Cloudflare Workers 提交文件上传要求必须施以符合 R2 逻辑的操作把控。只需赋予其相应的限制参数，Claude 便会自然为你生成具备了合规验证体系与内置安全保障机制的专属服务器函数。
提示词： "创建一个文件上传服务器函数，支持最大 10MB 的文件，使用配置好的 R2_BUCKET 绑定存储到 Cloudflare R2，验证文件类型仅允许图片（jpg、png、webp）和文档（pdf），生成保留原始扩展名的唯一文件名，返回 R2 的公共 URL，通过合适的状态码和信息体面地处理错误，并对文件名进行清理以防止安全问题。"
5. Paraglide 信息处理
面对有着丰富特性的大型多语言程序，逐个去增加国际化词条可谓是枯燥乏味。而在有了 Claude 代劳后，它将遵循你早已定下的层层结构基准帮你将指定键条项并入所有的语言文件体系之内，免去了亲自繁复手操的麻烦。
提示词： "为名为 'billing' 的新功能添加翻译键，用于处理订阅状态信息。包含以下键：billing.subscription.active 文本为 'Your subscription is active'；billing.subscription.canceled 文本为 'Your subscription has been canceled'；billing.subscription.past_due 文本为 'Payment failed. Please update your payment method'；billing.invoice.paid 文本为 'Payment received. Thank you!'。请遵循 messages/ 目录中现有的文件结构，将这些内容同时添加到英语和德语的翻译件中。"
常见失败模式
如果在上下文充足的情况下，Claude Code 有 70% 的成功率。剩下的 30% 则以可预测的方式失败。了解这些失败模式将为你节省数小时的调试时间，并帮助你编写出更好的提示词以规避这些问题。
身份验证检查执行错误
Claude 有时会生成客户端身份验证检查，因为大多数 React 教程都是这是这样教的。TanStack Start 要求在 beforeLoad 中进行服务端验证，因为客户端检查可以被绕过，从而产生安全漏洞。请始终核实身份验证是在 beforeLoad 中进行的，而不是在 useEffect 或别的组件逻辑中。
// Wrong (client-side only)
useEffect(() => {
if (!user) router.navigate('/login');
}, [user]);
// Right (server-side)
beforeLoad: ({ context }) => {
if (!context.user) return redirect('/login');
}
文件位置错乱
Claude 偶尔会将文件放置在错误的目录，因为它无法确切了解你的实际项目结构。生成文件后，请务必亲自验证其位置。API 路由应当放在 src/routes/api/，组件放在 src/components/，工具函数放在 src/lib/，数据库 schemas 放在 src/db/。错误的位置会导致导入报错，并使路由中断失败。
类型导入丢失
添加新路由时，Claude 有时会忘记导入你项目中的特定类型。请务必检查它生成的代码是否包含了 Route 类型以及你的项目所使用的任何自定义类型。缺失导入会引发令人迷惑的 TypeScript 错误，因为这些代码在语法的表面层次看起来是毫无缺漏正确的。
TanStack Intent Skills 对比 CLAUDE.md
TanStack Intent 提供了扩展 CLAUDE.md 的多种 skill 技能。这些 skill 提供了 TanStack 分发包的类型定义、摘自官方文档的示例代码模式、供参考引用的文档链接，以及 Claude 生成代码时会用到的工具说明。这些 skill 由 TanStack 团队长期维护，能时刻与各种包版本的更新保持同步。
当你利用 npm 安装 TanStack 依赖包时，这些 skill 会自动加载。它们能够起到辅助与弥补 CLAUDE.md 不足的作用，但无法替代后者。你的 CLAUDE.md 文件应当专注于本身自己项目特有的约定框架规范，而各种 skill 则专门处理针对特定功能依赖包的独有模式。这种职责划分能彻底让你的 CLAUDE.md 易于长期维护并且纯粹只为你的项目所聚焦服务。
立即开始应用
花 30 分钟去写出一份优质的 CLAUDE.md 是一笔极为划算的投资。因为你之后构建每个功能所换来的都是同样这被省下的 30 分钟。放眼整整一年的开发周期，这就是成百上千个小时的挽回所得。
它的关键要素就在于务必从简单开始。不要想着试着一并写出大而全的无所不包的文档。只需去撰写涵盖项目概况与关键约定即可。然后，伴随实际遇到的陷阱把他们作为反模式的准则加入以供防范。渐渐地，你的 CLAUDE.md 也会蜕变为一本详尽成熟的指南针，并将极大推高团队中全部开发同僚产出的真实效能上限水平。
即刻从 TanStack Ship 中将 CLAUDE.md 这份出色的模板复制下作己用，对其进行专门的自定义项目适配后，在今天便体会项目版本发布上线的加速飞奔吧。
要是你还是刚入门去使用这门 Claude Code 工具的新手使用者的话我会更加建议从“路由生成”（route generation）这类的提示词来入手。不仅是因为容易被核实比对，而且立竿见影你就能感受到当获得了真正良好的语境指导后这特性的建设进度能蹿升到多快。一旦彻底轻车熟路，随时可以依据你在推进遭遇的哪些短板或是让 Claude 陷入吃力的卡壳点继续做出对应的补足扩展并追加添加相关提示词指引。
我们的目标并不是让 Claude 编写所有的代码。而是让 Claude 生成只需极少清理工作就能迅速使用的代码。在良好上下文的辅佐浸润下，这就日益成为了一件普及常态的小事而绝非仅仅是偶发出现的惊喜。
我发现，生产力的大幅攀升实质上来源于 Claude 对那些样板文件和老旧重复模式的超高正确率响应。各类服务器函数部署交互、全线路由的定义规则，加上数据库 schema 的关联组织结构等全都隶属于 Claude 可以驾轻就熟、能够轻松学习并具备可预测反馈呈现的经典高发模式群组。你依靠在每趟建立这般属性新功能构筑中抢出的这等零星时间最终将全部反馈出巨大的成百倍复利累积效应。
除了生产力能获得跃进式的提升之外，一份高质量极度负责的 CLAUDE.md 文件还能让整体的代码审查进程跑得更为顺畅丝滑。当 Claude 回馈来的这些代码从根子上一直安分守己恪尽职守不折不扣遵循着格式准则出炉时，负责查验的人就不必浪费大量的青春全给在外观细小的拼错或者没对齐格式样式的挑刺排查，从而转而去把精力彻底收拢锁定到真正的那些更为深底层的程序运转实操逻辑问题层面。如此的反馈最终促成将毫无疑问带来更高质的代码代码质量与面向全体团队的高校迭代提速周期闭环。