Query Factory 패턴을 Claude Code 스킬로 만들기

TanStack Query를 쓰다 보면 어느 시점부터 쿼리 키가 여러 파일에 흩어지고, 옵션의 경우에도 하드코딩으로 박혀있는 것을 보게 됩니다. Query Factory 패턴을 익히면 이 문제가 해결되는데, 이러한 패턴들을 도입시에는 관리 포인트라는게 발생하게 됩니다. 우리는 매번 패턴을 적용하기 위해 코드를 반복으로 사용하게 되는데, 이걸 Claude Code 스킬로 만들어두고 나서 그 고민이 사라졌습니다.

목차

• Query Factory 패턴이란
• 스킬로 만들기
• 스킬이 적용되면 달라지는 것
• 마무리

Query Factory 패턴이란

쿼리 키와 queryFn, 옵션을 도메인별로 하나의 객체에 모아두는 패턴입니다.

export const characterQueries = {
  all:   () => ["characters"] as const,
  lists: () => [...characterQueries.all(), "list"] as const,

  list: (filter?: Filter) =>
    queryOptions({
      queryKey: [...characterQueries.lists(), filter] as const,
      queryFn:  () => fetchCharacters(filter),
      staleTime: 1000 * 60,
    }),

  detail: (id: string) =>
    queryOptions({
      queryKey: [...characterQueries.all(), "detail", id] as const,
      queryFn:  () => fetchCharacter(id),
      staleTime: 1000 * 60 * 10,
    }),
};

이렇게 해두면 useQuery(characterQueries.list())와 서버 컴포넌트의 prefetchQuery(characterQueries.list())가 항상 같은 키를 바라봅니다. SSR prefetch가 제대로 전달되는 전제 조건이고, invalidateQueries로 무효화 범위를 계층별로 조절할 수도 있습니다. 좋은 패턴인데, 매번 손으로 짜는 게 문제입니다.

스킬로 만들기

Claude Code 스킬은 마크다운 파일 하나입니다. .claude/skills/api-integration/SKILL.md에 이 패턴의 규칙을 적어두면, 관련 작업이 들어올 때마다 Claude가 스킬을 읽고 그 구조를 따라 코드를 생성합니다.

핵심은 트리거 조건과 규칙을 명시하는 것입니다.

---
name: api-integration
description: >
  TanStack Query + Query Factory 패턴 스킬.
  "쿼리 만들어줘", "API 연동해줘", "useQuery 작성" 등의 요청에 사용한다.
---

## Query Factory 패턴

쿼리는 반드시 도메인별 파일로 분리하고 아래 구조를 따른다.

- `src/lib/query-options/[domain].ts`에 작성한다
- `queryOptions()` 헬퍼를 사용한다
- 키는 `all → lists → list(filter)`, `all → detail(id)` 계층으로 만든다
- `staleTime`은 팩토리 안에서 정의한다. 호출부에서 직접 쓰지 않는다

이걸 스킬 파일에 한 번만 적어두면, 이후에 "캐릭터 목록 쿼리 만들어줘"라고 했을 때 매번 같은 구조가 나옵니다.

스킬이 적용되면 달라지는 것

스킬 없이 "쿼리 만들어줘"라고 하면 어떤 날은 useQuery 코드만 뚝 나오고, 어떤 날은 키를 문자열로 직접 쓰고, 또 어떤 날은 staleTime을 컴포넌트에 넣기도 합니다. 컨텍스트에 따라 결과가 달라집니다.

스킬이 있으면 다릅니다. 요청만 해도 src/lib/query-options/ 아래 도메인 파일이 생기고, 계층적 키 구조와 queryOptions가 포함된 코드가 나옵니다. 리뷰할 때 "이건 왜 이렇게 됐어요?"가 없어집니다. 팀에서 같이 쓰면 사람마다 구조가 달라지는 일도 없습니다.

마무리

Query Factory 패턴 자체는 어렵지 않습니다. 한 번 익히면 됩니다. Claude Code 스킬로 만들어두는 건 그 다음 단계입니다. 익힌 패턴을 매번 기억해서 적용하는 대신, 스킬에 위임해두면 됩니다. 새 프로젝트를 시작해도, 새 도메인을 추가해도, "이번엔 어떻게 구조 잡지?" 고민 없이 같은 결과가 나옵니다. 좋은 패턴은 습관이 되어야 하는데, 스킬이 그 습관을 대신해줍니다.

관련해서 더 볼 것:

• TanStack Query 공식 문서 — queryOptions
• Claude Code 스킬 문서