在新库上使用 AI 工具

I’m happy to translate the article for you, but I’ll need the full text of the post. Could you please paste the content you’d like translated (excluding the source link you’ve already provided)? Once I have the article text, I’ll translate it into Simplified Chinese while preserving the original formatting, markdown, and any code blocks.

Introduction

这是 Railway‑Oriented TypeScript 的设置指南。如果你还没有阅读概览，请先从那里开始。

@railway-ts/pipelines 和 @railway-ts/use-form 仍然是新项目。这会带来一个实际问题：AI 编码助手——Claude Code、Cursor、GitHub Copilot——在数百万个 Zod、react‑hook‑form 和 neverthrow 的示例上接受了训练。它们几乎没有 @railway-ts 的训练数据。

结果是可以预料的。让 Claude Code 在已安装 @railway-ts/use-form 的情况下构建表单时，它会自行写出 zodResolver、来自 react‑hook‑form 的 useForm，以及 setError/clearErrors——自信且未被要求，因为这种模式在它的训练数据中出现了成千上万次。它并不是在胡乱捏造代码；它是在进行最高概率的模式匹配。而这个答案对你的项目来说是 错误的。

这并不是对 AI 工具的批评。这是关于它们工作方式的结构性现实，值得我们去理解并规避。

为什么随包发布的文档很重要

两个库现在都把文档打包在 npm 包内部：

node_modules/@railway-ts/pipelines/docs/
node_modules/@railway-ts/use-form/docs/

现代 AI 编码工具——尤其是 Claude Code——可以读取你的 node_modules，并依据其中的类型和文档进行推理。当你把工具指向正确的文档时，它不再仅仅对训练数据进行模式匹配，而是从实际的库 API 推理。生成的代码从“自信错误”变为“读取类型并生成正确用法”。

输出质量的差异是显著的。捆绑的文档正是使在新库上进行 AI 辅助开发可行的机制。

设置 CLAUDE.md

在项目根目录放置一个 CLAUDE.md（或等效的上下文文件）是重定向 AI 工具最可靠的方式。Claude Code 会自动读取它。请在开始生成表单或流水线代码之前 先创建 它：

# AI Coding Instructions

This project uses @railway-ts/pipelines and @railway-ts/use-form.

Before generating any form or pipeline code, read the docs shipped with the packages:

- node_modules/@railway-ts/pipelines/docs/
- node_modules/@railway-ts/use-form/docs/

Rules:

- Do NOT use Zod or @hookform/resolvers patterns
- Do NOT use react-hook-form's useForm, setError, or clearErrors
- Schema validation uses @railway-ts/pipelines/schema, not z.object()
- Form state uses useForm from @railway-ts/use-form, not react-hook-form
- Async pipelines use flowAsync/pipeAsync from @railway-ts/pipelines/composition

其他 AI 工具的使用方式

验证设置是否有效

在创建 CLAUDE.md 后，先让你的 AI 工具 在不触碰任何真实代码的情况下 构建一个简单的表单：

使用 @railway-ts/use-form 构建一个包含电子邮件和密码字段的 React 登录表单。处理服务器端的验证错误。

输出 应当：

• 使用来自 @railway-ts/use-form 的 useForm
• 使用来自 @railway-ts/pipelines/schema 的 object / required / chain 构建 schema
• 调用 form.setServerErrors() 进行服务器端错误注入

如果仍然看到 zodResolver、@hookform/resolvers 或 setError/clearErrors，说明工具仍在根据其训练数据进行模式匹配——请再次确认 CLAUDE.md 位于项目根目录，并且文档已存在于 node_modules 中。

AI 在阅读文档时做对的事

当工具读取捆绑的文档时，它能够很好地处理以下内容：

• 使用 chain、object、required、optional 进行模式组合
• fieldValidators 用于异步字段级检查
• form.setServerErrors() 用于服务器端错误注入
• flowAsync / pipeAsync 用于组合多步骤异步管道
• 柯里化操作符：mapWith、flatMapWith、filterWith、tapWith 等
• 批处理辅助函数：combine、combineAll、partition
• 使用 refineAt 进行跨字段验证

值得手动再次确认的事项

• 使用 InferSchemaType 的类型推断 — 验证生成的类型是否符合你的预期。
• initialValues 的完整性 — TypeScript 会在缺少字段时报错，但仍需确认它与 UI 的对应关系。
• setServerErrors 中的错误路径字符串 — 确保它们与模式字段名称匹配。

快速开始

mkdir my-project && cd my-project
npm init -y
npm install react react-dom @types/react typescript
npm install @railway-ts/pipelines @railway-ts/use-form

创建 CLAUDE.md 如上所示，然后验证文档是否存在：

ls node_modules/@railway-ts/pipelines/docs/
ls node_modules/@railway-ts/use-form/docs/

迁移使用 Zod 的现有项目

npm install @railway-ts/use-form @railway-ts/pipelines
# 保留 zod — 表单钩子通过 Standard Schema v1 接受 Zod 模式

您可以在不更改 Zod 模式的情况下采用表单钩子。请参阅第 3 部分了解迁移路径。

系列

• 第 1 部 — 粘合代码税
• 第 2 部 — 面向铁路的 TypeScript（本指南）
• 第 3 部 — 从 Zod + react‑hook‑form 迁移

第 1 部分 — 表单 Hook 深入解析

Composable async pipelines in TypeScript – one result type, zero adapters (Part 1)

• 逐步讲解 useForm Hook 的内部实现：
  • Resolver 绑定
  • 异步验证处理
  • 服务器错误转换
  • 类型断言
• 随后展示相同的表单在不使用上述任何部分的情况下重写。

Part 2 — 可组合的异步管道

Composable async pipelines in TypeScript – one result type, zero adapters (Part 2)

• @railway-ts/pipelines API 介绍：
  • Result 类型
  • 柯里化运算符
  • flowAsync 用于多步骤异步管道，错误会自动短路
• 展示了表单钩子使用的完全相同的 Result 类型。

第 3 部分 — 基于模式的 React 表单

Schema‑first React forms – one schema, three error layers, zero glue (Part 3)

• 3 层错误优先级系统的详细说明
• 数组字段的处理
• 全栈循环：单一模式驱动后端管道验证和前端表单状态 无需任何格式转换。

奖励 — 数据处理管道

在 TypeScript 中构建类型安全的数据处理管道（奖励）

• 在 ETL 场景中使用管道库：
  • 使用 combine、combineAll 和 partition 进行批处理
  • 可复用的子管道
  • 结构化错误报告
• 无 React，无 UI —— 纯数据处理。

GitHub 仓库

• @railway-ts/pipelines – 提供 Result、Option、模式验证以及可组合的管道。
• @railway-ts/use-form – React 表单 Hook，支持原生模式集成。