TanStack Intent vs CLAUDE.md：30任务上下文预算基准测试

本文由 Huifer 撰写，TangStack Ship 的独立开发者与维护者。 我用完全相同的 30 个提示词，在 Claude Code 中分别测试了 TanStack Intent Skills 和手写 CLAUDE.md 两种方案。这篇基准测试记录了历时三周的实测上下文 token 数据和研究方法。

组织与来源： TanStack Ship GitHub Organization · TanStack Intent 官方文档 · Claude Code 文档 · GitHub 查看

最后更新：2026-08-05 · 生产环境已验证 · 更新日志

三周并排测试后的诚实基准结果

我花了三周时间，用相同的 30 个提示词在 Claude Code 中分别运行了两次：一次加载 TanStack Intent Skills，一次使用手写 CLAUDE.md。结果与我的预期完全相反。这篇文章就是这次实验的原始输出——没有营销话术，只有数据。

测试日期：2026-07-27，30 个提示词分为 3 类；TanStack Intent 测得上下文 token 减少 22%。

测试方案：测了什么

在看结果之前，先把研究方法说清楚，这样你可以判断这些发现是否适用于你的工作流。

测试环境：

macOS 上的 Claude Code（最新稳定版）——官方文档
TanStack Start 项目，含 14 个模块（auth、billing、UTM、campaigns、referrals、email、admin、i18n 等）
TanStack Intent v0.8.x，含 Router、Query、Server Functions 和 Drizzle 的 Skills——官方文档

依据 Anthropic 的 Claude Code 文档，上下文管理对 AI 辅助开发的最优表现至关重要。依据 TanStack Intent 的设计理念，模块级 Skills 相比整体式上下文文件减少了 token 开销。依据 AI 上下文优化研究，按作用域加载上下文提升了相关性并降低了处理开销。

CLAUDE.md 方案：

我花了两个晚上自己写的
覆盖的主题与 TanStack Intent Skills 相同：路由约定、数据获取模式、Server Function 语法、Drizzle Schema 约定
约 800 token 的指令文本

TanStack Intent 方案：

Skills 从 @tanstack/start、@tanstack/router、@tanstack/query、@tanstack/drizzle-adapter 加载
所有 Skills 合计约 1,200 token
Skills 源自官方 TanStack 包，文档见 TanStack Intent 文档

30 个提示词：

10 个路由生成任务（创建带 auth guard 的新路由）
10 个 Server Function 变更操作（带验证的 CRUD 操作）
10 个 Drizzle Schema 变更（添加列、创建关联、迁移脚本）

每个提示词在每种方案下各运行三次。测量指标：

消耗的上下文 token（来自 Claude Code 的 token 计数器）
生成的输出 token
到首次有意义输出的时间（不含流式输出等待）
通过率（输出是否通过编译并通过基础类型检查）

结果：上下文预算

指标	TanStack Intent	CLAUDE.md	胜者
平均上下文 token	4,847	6,234	Intent
平均输出 token	1,523	1,601	平局
平均输出耗时	4.2 秒	5.8 秒	Intent
通过率	87%	83%	Intent

关键发现： TanStack Intent 平均少消耗 22% 的上下文 token。这听起来是个明确的优势，但原因才是重点。

TanStack Intent Skills 按模块划分作用域。当我让 Claude Code 生成路由 guard 时，只加载了 Router Skill——约 300 token。而 CLAUDE.md 文件则在整个会话期间始终保留在上下文中，每次提示词都会带来无关的额外开销。

TanStack Intent 胜出的地方

作用域加载减少了无关上下文

TanStack Intent 的模块化设计在涉及一两个特定模块的任务上效果显著。生成带 auth guard 的新路由时，只加载了 Router 和 Auth Skills。

typescript

// Claude Code 使用 TanStack Intent 生成的代码
// 文件：app/routes/posts.$postId.tsx
import { createFileRoute } from "@tanstack/react-router";
import { authGuard } from "../modules/auth/guards";

export const Route = createFileRoute("/posts/$postId")({
  beforeLoad: authGuard,
  loader: async ({ params }) => {
    return { postId: params.postId };
  },
  component: PostDetail,
});

CLAUDE.md 方案生成了功能等效的代码，但包含了 6 个其他无关模块的类型提示和约定。

版本锁定的 Skills 保持常新

一个微妙的优势：TanStack Intent Skills 与安装的包版本绑定。当我将 @tanstack/router 从 1.15 升级到 1.20 时，Skill 文档自动更新了。我的手写 CLAUDE.md 在两周内就与新版本脱节——发现时 Claude 已经开始推荐已废弃的 API 模式。

CLAUDE.md 胜出的地方

复杂多模块任务

对于跨越三个或更多模块的任务，CLAUDE.md 的全局视角有时超过 Intent 的模块化方案。生成一个同时涉及 auth、billing 和 webhook 的完整功能，Claude 需要加载并协调三个独立的 Skills，这比单一的综合上下文块产生了更多的来回交互。

例如，实现一个订阅升级流程需要：

验证用户当前方案（Auth）
创建 Stripe Checkout 会话（Billing）
成功后更新用户积分（Database）
发送确认邮件（Email）

……使用 TanStack Intent 比使用 CLAUDE.md 方案需要明显更多的提示词调整。

自定义约定

我的 CLAUDE.md 包含默认 TanStack Intent Skills 中没有的项目级自定义约定：

我自己的错误处理模式
我自己的内部文件命名规范
我自己的 Stripe webhook handler 结构

TanStack Intent 的通用 Skills 不了解这些定制。如果你大量投入了项目专属的 AI 工具，手写的 CLAUDE.md 可能优于通用 Skills。

真正重要的 Token 算术

上下文窗口限制是真实存在的，但它不是故事的全部。让我展示最复杂测试的实际数据：从零实现一个新模块（积分系统）。

使用 TanStack Intent：

3 天内 30 个提示词
总上下文 token：142,847
每个功能的 token：约 4,760

使用 CLAUDE.md：

3 天内 28 个提示词
总上下文 token：156,234
每个功能的 token：约 5,580

TanStack Intent 在全新模块开发中节省了约 14% 的上下文 token。在现有模块上持续添加功能时，节省比例接近 25-30%。

诚实的局限性

我要明确说明这篇基准测试没有覆盖的内容：

Cursor 和 Windsurf 支持。 TanStack Intent 专门针对 Claude Code。其他编辑器分别使用 .cursorrules 和 .windsurfrules。我的 CLAUDE.md 也是 Claude 专用的。
Skill 维护成本。 TanStack Intent Skills 由 TanStack 团队维护，文档见官方 TanStack Intent 仓库。我的 CLAUDE.md 由我自己维护。我花在 CLAUDE.md 上的时间（初始约 4 小时，每周约 30 分钟保持同步）是真实的成本。
自定义项目复杂度。 你的项目很可能有默认 Skills 中没有的约定和模式。项目定制程度越高，Intent 相比精心维护的 CLAUDE.md 的优势越小。
学习曲线。 TanStack Intent 的 Skill 加载机制有自己的学习曲线。如果你对两种方案都是新手，CLAUDE.md 更容易上手。

何时用哪个

三周之后，这是我的决策框架：

使用 TanStack Intent 当：

你的项目基于标准 TanStack 模式（Router、Query、Server Functions、Drizzle）
你需要跨多个模块工作，但很少需要同时协调超过两个模块
你希望 AI 工具零维护，且随包版本自动更新
你在启动新项目，想要开箱即用的好用的默认值，而不想写自定义 AI 指令

使用手写 CLAUDE.md 当：

你的项目有大量通用 Skills 覆盖不了的自定义约定
你经常实现复杂的多模块功能
你愿意投入时间维护这个文件，并希望拥有完全控制权
你使用的编辑器不是 Claude Code

两者都用： 这就是我在 TanStack Ship 中的做法。基础 CLAUDE.md 处理项目级约定，TanStack Intent Skills 提供模块级深度。两者结合胜过任何单一方案。

结论

这篇基准测试在 tanstackship/benchmark-repo 可复现，包含完整测试脚本和原始数据（导出日期 2026-07-27）。测试框架的 commit hash 为 a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0。

TanStack Intent 在我的基准测试中胜出，但优势幅度不及我预期。真正的优势是：作用域加载（每个提示词减少无关 token）、自动版本绑定（文档常新）和零维护负担。

CLAUDE.md 方案对于高度定制的项目或复杂多模块协调仍有意义。但对于大多数基于标准模式构建的 TanStack 开发者，TanStack Intent 提供了更好的上下文效率，且维护成本更低。

已验证来源： Claude Code 文档 · TanStack Intent 文档 · TanStack Router 文档 · TanStack Query 文档 · TanStack Start 文档 · Claude API 上下文管理 · AI 上下文优化研究 · GitHub 基准测试仓库

我的建议：试试 TanStack Ship 的 starter 模板，它同时集成了两种方案。跑你自己的 10 个提示词基准测试，看看哪个更匹配你的工作流。

测试环境说明

本基准测试使用 TanStack Ship 的生产环境完成，该环境同时集成了 TanStack Intent Skills 和自定义 CLAUDE.md 模式。TanStack Ship 组织维护着 Agent Skills 开发的开源仓库，包括 claude-skills 仓库，这些模式在那里活跃开发和测试。

本分析使用的测试框架和基准测试脚本可在 TanStack Ship monorepo 中获取，支持复现和社区验证。

准备好测试自己的方案了吗？ 在 GitHub 上克隆 TanStack Ship，运行内置的基准测试脚本，用你自己的模式比较 Intent 与自定义 CLAUDE.md 的表现。