Molayo

© 2026 Molayo

Dev.to헤드라인2026. 05. 28. 16:02

Remix를 위한 CLAUDE.md: AI가 Loader/Action 패턴을 망가뜨리지 않게 하는 13가지 규칙

요약

Remix 프레임워크 사용 시 Claude Code나 Cursor 같은 AI 도구가 프레임워크 고유의 패턴을 위반하지 않도록 CLAUDE.md를 활용하는 방법을 제안합니다. Loader, Action, 파일 시스템 라우팅 등 Remix의 핵심 멘탈 모델을 AI에게 학습시키는 13가지 규칙을 다룹니다.

핵심 포인트

  • CLAUDE.md를 통해 AI에게 Remix의 멘탈 모델을 사전 제공
  • Loader를 통한 서버 사이드 데이터 페칭 강제
  • Action을 활용한 데이터 뮤테이션 및 점진적 향상 유지
  • 파일 시스템 기반 라우팅 규칙 준수 유도
  • 에러 경계 및 세션 관리의 서버 중심 패턴 적용

만약 Remix 프로젝트에서 Claude Code나 Cursor를 사용해 보았다면, AI가 다른 React 프레임워크에 속하는 패턴들—Express 스타일의 미들웨어(middleware), 모든 것에 React Query 사용, Loader가 있어야 할 자리에 클라이언트 사이드 페칭(client-side fetching)을 사용하는 방식—로 흘러가는 것을 본 적이 있을 것입니다.

Remix는 특정한 멘탈 모델(mental model)을 가지고 있습니다: Loader와 Action이 데이터 레이어(data layer)를 소유하고, 파일 시스템(file system)이 라우터(router) 역할을 하며, 점진적 향상(progressive enhancement)이 일급 기능(first-class feature)으로 제공됩니다. 이를 알지 못하는 AI 도구들은 개별적으로는 작동하지만 프레임워크와 끊임없이 충돌하는 코드를 생성합니다.

저장소 루트(repo root)에 CLAUDE.md 파일을 두는 것이 해결책입니다. 이는 코드가 생성되기 전, 모든 AI 세션에 Remix의 멘탈 모델을 미리 제공합니다.

가장 흔한 실패 사례들을 다루는 13가지 규칙은 다음과 같습니다.

규칙 1: Loader가 모든 서버 사이드 데이터 페칭을 소유함

모든 라우트(route)의 데이터 페칭은 해당 loader 함수 내에서 이루어져야 합니다.
Loader가 데이터를 제공할 수 있는 상황에서, useEffect나 클라이언트 사이드 라이브러리를 사용하여 컴포넌트 내에서 데이터를 페칭하지 마십시오.
...

AI는 SPA(Single Page Application)에서 학습한 React Query나 useEffect 패턴을 기본값으로 사용합니다. Remix의 Loader는 더 단순하며 클라이언트 사이드 워터폴(client-side waterfall) 현상을 완전히 제거합니다.

규칙 2: Action이 모든 뮤테이션(mutations)을 소유함

모든 폼 제출(form submissions)과 데이터 뮤테이션은 action 함수를 통해 이루어져야 합니다.
서버 데이터를 수정하는 뮤테이션을 위해 React 상태(state) + fetch 조합을 사용하지 마십시오.
Form 컴포넌트를 사용하거나, 페이지 이동이 없는 뮤테이션의 경우 useFetcher를 사용하십시오.

Action/Loader 패턴은 Remix의 핵심 프리미티브(primitive)입니다. 이를 우회하는 AI는 Remix의 점진적 향상(progressive enhancement)과 낙관적 UI(optimistic UI)의 이점을 잃어버리는 하이브리드 앱을 만들어냅니다.

규칙 3: 파일 시스템 라우팅이 유일한 라우터임

라우트는 app/routes/ 디렉토리의 파일 구조에 의해 정의됩니다.
useNavigate를 통한 프로그래밍 방식의 네비게이션을 제외하고는, 수동으로 라우터 설정을 만들거나 React Router를 명령형(imperatively)으로 사용하지 마십시오.
...

규칙 4: 세션 관리는 서버에서 이루어짐

모든 세션 데이터는 createCookieSessionStorage 또는 createSessionStorage를 사용하여 서버 사이드에 저장됩니다. 민감한 데이터를 localStorage나 클라이언트에서 접근 가능한 쿠키(cookies)에 저장하지 마십시오.

규칙 5: Error boundaries는 라우트와 같은 위치에 배치한다

실패할 가능성이 있는 모든 라우트는 ErrorBoundary 컴포넌트를 내보냅니다 (exports).
모든 라우트 에러를 잡기 위해 단일 최상위 에러 경계 (top-level error boundary)를 사용하지 마십시오.
HTTP 에러 (4xx, 5xx)에는 CatchBoundary를 사용하고, ErrorBoundary는 ... 에 사용하십시오.

규칙 6: Meta 및 links는 라우트 모듈에서 내보낸다

페이지 메타데이터 (title, description, og tags)는 컴포넌트에서 명령형으로 설정하는 것이 아니라, 라우트 모듈의 meta 함수를 통해 내보냅니다.
스타일시트와 프리로드 (preloads)는 links export를 사용합니다.

규칙 7: 환경 변수는 기본적으로 서버 전용이다

모든 환경 변수는 클라이언트 노출을 위해 명시적으로 접두사 (prefix)를 붙이지 않는 한 서버 전용입니다. 클라이언트 측 코드에서 process.env에 절대 접근하지 마십시오.
필요한 설정을 클라이언트에 전달할 때는 loader를 사용하여 loader data로 전달하십시오.

규칙 8: 낙관적 UI (Optimistic UI)는 useFetcher를 사용한다

낙관적 업데이트 (Optimistic updates)는 상태와 formData를 포함한 useFetcher를 사용합니다.
서버 뮤테이션 (mutation)과 별개로 로컬 React 상태를 관리하여 낙관적 UI를 구현하지 마십시오. 이는 동기화 버그를 유발합니다.

규칙 9: TypeScript 타입은 loader에서 컴포넌트로 흐른다

useLoaderData를 위한 타입 소스로 typeof loader를 사용하십시오.
loader 반환 형태에 대해 중복된 타입 인터페이스를 정의하지 마십시오.
모든 라우트 타입은 라우트 모듈에서 내보낸 타입으로부터 파생됩니다.

규칙 10: 실행 시간이 긴 비핵심 데이터만 defer 한다

defer()와 Await는 다음 조건에 해당하는 데이터에 대해서만 사용하십시오:
1. 초기 렌더링에 핵심적이지 않은 데이터
2. 실제로 느린 데이터 (>500ms)
...

규칙 11: 리소스 라우트 (Resource routes)는 HTML이 아닌 응답을 반환한다

JSON, 파일 또는 웹훅 (webhooks)을 반환하는 라우트는 loader 또는 action만 내보내며, 기본 컴포넌트는 포함하지 않습니다. UI 라우트와 구분하기 위해 점 접두사 (예: _api.webhook.ts)를 사용하여 이름을 지정하십시오.

규칙 12: 점진적 향상 (Progressive enhancement)이 기본 원칙이다

Form은 JavaScript가 활성화되지 않은 상태에서도 작동해야 합니다.
모든 탐색형 뮤테이션 (navigating mutations)에는 fetch 대신 Form 컴포넌트를 사용하십시오.
useFetcher와 useNavigation.state를 통해 JS로 기능을 향상시키십시오 (Enhance).
...

규칙 13: Remix 프로젝트에서 CLAUDE.md의 스태킹 순서

Remix 코드를 생성할 때는 다음 순서로 확인하십시오:

  1. 이 데이터를 소유해야 하는 loader가 있는가? 있다면 그것을 사용하십시오.
  2. 이 mutation (변이)을 소유해야 하는 action이 있는가? 있다면 그것을 사용하십시오.
    ...

전체 CLAUDE.md 블록

이 내용을 Remix 프로젝트의 CLAUDE.md에 붙여넣으십시오:

# Remix 프로젝트 규칙

## 아키텍처 (Architecture)
...

이것이 다른 프레임워크보다 Remix에서 더 중요한 이유

Remix의 컨벤션 (Conventions)은 구조를 지탱하는 핵심 요소입니다. loader/action 패턴은 단순한 스타일 가이드가 아니라, 다음과 같은 기능들을 가능하게 합니다:

  • mutation (변이) 후 자동 재검증 (Automatic revalidation)
  • 즉각적인 점진적 향상 (Progressive enhancement)
  • 클라이언트 워터폴 (Client waterfalls) 없는 병렬 데이터 로딩
  • 라우트 레벨에서의 에러 복구 (Error recovery)

AI가 이러한 컨벤션을 깨뜨리면 단순히 나쁜 코드를 생성하는 데 그치지 않습니다. 겉보기에는 올바르게 보이지만, Remix를 사용할 가치가 있게 만드는 모든 기능들을 조용히 무력화하는 코드를 생성하게 됩니다.

CLAUDE.md 파일은 모든 세션과 모든 팀원이 프레임워크의 멘탈 모델 (Mental model) 안에 머물 수 있도록 유지해 줍니다.

이 13가지 규칙은 프레임워크별 CLAUDE.md 시리즈의 일부입니다. 모든 스택에 대해 프로덕션에서 테스트된 50가지 규칙이 담긴 Cursor Rules Pack 에퀴벌런트는 oliviacraftlat.gumroad.com/l/wyaeil에서 확인할 수 있습니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0