새 라이브러리에서 AI 도구 사용하기

Source: Dev.to

해당 텍스트를 번역하려면 원문 내용을 제공해 주시겠어요? 현재는 링크만 제공되어 있어 번역할 본문이 없습니다. 본문을 복사해서 알려주시면 한국어로 번역해 드리겠습니다.

Source:

Introduction

이 문서는 Railway‑Oriented TypeScript 설정 가이드입니다. 아직 overview를 읽지 않으셨다면, 먼저 그곳을 확인하세요.

@railway-ts/pipelines와 @railway-ts/use-form은 새롭게 추가된 패키지입니다. 이 때문에 실용적인 문제가 발생합니다: Claude Code, Cursor, GitHub Copilot 같은 AI 코딩 도우미들은 Zod, react‑hook‑form, neverthrow의 수백만 예제로 학습되었습니다. 반면 @railway-ts에 대한 학습 데이터는 거의 없습니다.

그 결과는 예측 가능했습니다. Claude Code에게 @railway-ts/use-form이 설치된 상태에서 폼을 만들라고 요청하면, react‑hook‑form의 zodResolver, useForm 그리고 setError/clearErrors를 자동으로 삽입합니다—요청하지 않아도 자신 있게 그렇게 하는데, 이는 해당 패턴이 학습 데이터에 수천 번 등장했기 때문입니다. AI가 무작위 코드를 만들어 내는 것이 아니라 가장 확률이 높은 답을 패턴 매칭한 것입니다. 문제는 그 답이 여러분 프로젝트에 잘못된 답이라는 점입니다.

이것은 AI 도구에 대한 비판이 아닙니다. 그들이 작동하는 방식에 대한 구조적인 현실이며, 이를 이해하고 우회하는 것이 중요합니다.

패키지와 함께 제공되는 문서가 중요한 이유

두 라이브러리 모두 이제 npm 패키지 안에 문서를 포함하여 배포합니다:

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

현대 AI 코딩 도구—특히 Claude Code—는 node_modules를 읽고 그 안에 있는 타입과 문서를 기반으로 추론할 수 있습니다. 도구가 올바른 문서를 가리키면, 훈련 데이터에 대한 패턴 매칭을 멈추고 실제 라이브러리 API를 기반으로 추론을 시작합니다. 이렇게 생성된 코드는 “자신 있게 틀린” 상태에서 “타입을 읽고 올바른 사용법을 생성”하는 상태로 바뀝니다.

출력 품질 차이는 상당합니다. 번들된 문서는 새로운 라이브러리에서 AI‑지원 개발을 가능하게 하는 핵심 메커니즘입니다.

CLAUDE.md 설정하기

AI 도구를 리디렉션하는 가장 신뢰할 수 있는 방법은 프로젝트 루트에 CLAUDE.md(또는 동등한 컨텍스트 파일)를 두는 것입니다. 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으로 스키마 구축
• 서버‑측 오류 주입을 위해 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을 사용한 교차 필드 검증

수동으로 다시 확인할 가치가 있는 항목들

• 타입 추론 with InferSchemaType — 생성된 타입이 의도와 일치하는지 확인하세요.
• initialValues의 완전성 — 필드가 누락되면 TypeScript가 오류를 표시하지만, UI와 일치하는지 확인하세요.
• setServerErrors의 오류 경로 문자열 — 스키마 필드 이름과 일치하는지 확인하세요.

Quick Start

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
# keep zod — the form hook accepts Zod schemas via Standard Schema v1

Zod 스키마를 그대로 두고도 폼 훅을 사용할 수 있습니다. 마이그레이션 경로는 Part 3 를 참고하세요.

시리즈

• Part 1 — 글루 코드 세금
• Part 2 — Railway‑Oriented TypeScript (이 가이드)
• Part 3 — Zod + react‑hook‑form에서 마이그레이션

Part 1 — Form Hook Deep Dive

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

• useForm 훅 내부에 대한 워크스루:
  • Resolver 연결
  • 비동기 검증 처리
  • 서버 오류 변환
  • 타입 어설션
• 위와 같은 폼을 해당 요소들 없이 다시 작성한 버전.

Part 2 — Composable Async Pipelines

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

• @railway-ts/pipelines API 소개:
  • Result 타입
  • 커리드 연산자
  • 오류가 자동으로 단락되는 다단계 비동기 파이프라인을 위한 flowAsync
• 폼 훅에서 사용되는 동일한 Result 타입을 보여줍니다.

Part 3 — 스키마‑우선 React 폼

스키마‑우선 React 폼 – 하나의 스키마, 세 가지 오류 레이어, 제로 글루 (Part 3)

• 3‑계층 오류 우선순위 시스템에 대한 상세 설명
• 배열 필드 처리
• 풀스택 루프: 단일 스키마가 백엔드 파이프라인 검증과 프론트엔드 폼 상태를 포맷 변환 없이 모두 구동합니다.

보너스 — 데이터 처리 파이프라인

Building a type‑safe data‑processing pipeline in TypeScript (Bonus)

• ETL 컨텍스트에서 파이프라인 라이브러리를 사용합니다:
  • combine, combineAll, partition을 이용한 배치 처리
  • 재사용 가능한 서브‑파이프라인
  • 구조화된 오류 보고
• React도, UI도 없습니다 – 순수 데이터 처리.

GitHub Repositories

• @railway-ts/pipelines – Result, Option, 스키마 검증 및 조합 가능한 파이프라인을 제공합니다.
• @railway-ts/use-form – 네이티브 스키마 통합이 가능한 React 폼 훅입니다.