メニュー
백엔드 API를 frontend/src에 연동하는 스킬. "API 연동해줘", "백엔드 연결해줘", "엔드포인트 붙여줘", "쿼리 훅 만들어줘", "mutation 추가해줘", "이 API 호출하게 해줘" 요청 시 트리거한다. 타입·schema·API 함수·훅·MSW 핸들러를 기존 패턴대로 작성한다.
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | fe-api |
| description | 백엔드 API를 frontend/src에 연동하는 스킬. "API 연동해줘", "백엔드 연결해줘", "엔드포인트 붙여줘", "쿼리 훅 만들어줘", "mutation 추가해줘", "이 API 호출하게 해줘" 요청 시 트리거한다. 타입·schema·API 함수·훅·MSW 핸들러를 기존 패턴대로 작성한다. |
백엔드 엔드포인트를 타입·schema·API 함수·훅·mock으로 연결한다.
이 스킬은 frontend/ 범위에서만 동작한다. backend/ 파일은 수정하지 않는다.
규칙 기준:
AGENTS.md"API 규칙", "상태와 데이터", "타입과 schema", "MSW"
shared/lib, entity model). 반복 전에 미리 추상화하지 않는다.엔드포인트·요청/응답 형태는 항상 backend/ 폴더의 최신 코드를 읽어 확인한다 (읽기 전용, 수정 금지). 추측하거나 오래된 문서에 의존하지 않는다.
| 확인 대상 | 위치 |
|---|---|
| 경로·메서드·응답 | backend/src/modules/{module}/*.controller.ts |
| 요청 body 필드 | backend/src/modules/{module}/dto/*.dto.ts |
| 응답 모델·필드 | backend/prisma/schema.prisma, 관련 service 반환 타입 |
| (보조) 정리된 명세 | backend/docs/backend/api-docs/ |
/bands, /auth/login/email). base URL을 붙이지 않는다.status: 'success' | 'error' + error: string | null + message: string + (성공 시) data 형태다. schema로 parse한 뒤 status === 'error'이면 throw하고 data를 반환한다 (src/entities/notification/api/notification-api.ts 패턴).any가 아니라 unknown으로 받아 zod로 parse하거나 타입을 좁힌다.entities/{domain}/model/에 타입과 schema를 둔다. schema가 있으면 z.infer 기반 타입을 유지한다.
// entities/band/model/schema.ts — status 기반 응답 계약
export const bandListResponseSchema = z.object({
status: z.enum(['success', 'error']),
error: z.string().nullable(),
message: z.string(),
data: z.object({ items: z.array(bandSchema) }),
});
에러 분기가 필요하면 status로 좁히는 discriminated union을 쓴다 (entities/notification/model/schema.ts 패턴).
{domain}/api/{domain}-api.ts에 작성한다. @/shared/api의 apiGet/apiPost/apiPatch/apiDelete를 우선 쓰고, schema 검증이 필요하면 apiClient를 직접 쓴다.
// entities/band/api/band-api.ts — apiClient + schema 검증 패턴
import { apiClient } from '@/shared/api';
import { bandListResponseSchema } from '../model/schema';
export const getBands = async (): Promise<Band[]> => {
const response = await apiClient.get('/bands');
const parsed = bandListResponseSchema.parse(response.data);
if (parsed.status === 'error') throw new Error(parsed.message);
return parsed.data.items;
};
// 단순 호출은 helper 사용
import { apiPost } from '@/shared/api';
export const createSchedule = (data: CreateScheduleRequest) =>
apiPost<ScheduleItem>('/schedule', data);
| 종류 | 패턴 | 위치 |
|---|---|---|
| 조회 | useQuery + query key 객체 (bandKeys) | entities/ |
| 변경(행위) | useMutation + onSuccess에서 invalidateQueries | features/ |
query key는 도메인 파일에 모아 재사용한다.
// entities/band/api/useBands.ts
export const bandKeys = {
all: ['bands'] as const,
lists: () => [...bandKeys.all, 'list'] as const,
};
export const useBands = () =>
useQuery({ queryKey: bandKeys.lists(), queryFn: getBands });
// features/band-create/model/useBandCreate.ts — mutation 후 invalidate
const mutation = useMutation({
mutationFn: createBand,
onSuccess: async () => {
await queryClient.invalidateQueries({ queryKey: bandKeys.lists() });
},
});
데이터를 불러오는 모든 화면은 없음 / 넘침 / 오류 세 상태를 의도적으로 설계한다. 정보의 중요도에 따라 처리 수준을 다르게 한다.
| 상태 | 핵심 정보 (없으면 화면 자체가 무의미) | 보조 정보 (일부만 빠져도 됨) |
|---|---|---|
| 없음(empty) | 빈 상태 안내 + 액션 유도 | "없음" 텍스트/플레이스홀더로 자리만 표시 |
| 넘침(overflow) | 페이지네이션·무한 스크롤 | 상위 N개만 노출 + 더보기(별도 목록 페이지로 라우팅) |
| 오류(error) | 에러 화면/재시도, 필요 시 404 라우팅 | 그 블록만 "불러오지 못했어요" 표시, 나머지는 유지 |
size/limit 파라미터로 잘라 받고, 전체는 별도 목록 페이지에서 본다.AGENTS.md 접근성).useQuery의 isLoading/isError/빈 배열을 각각 분기하고, 빈 상태와 오류 상태를 혼동하지 않는다.dev는 MSW가 요청을 가로채므로 핸들러를 함께 추가한다.
mocks/{domain}/handlers.ts → mocks/handlers.ts에 합친다.mocks/config.ts의 API_URL을 따른다.API 함수는 fe-test 스킬의 axios-mock-adapter 패턴으로 테스트를 작성한다 (성공 + 필수 필드 누락).
backend/ 최신 코드(controller·dto)에서 확인했는가?unknown으로 받아 zod parse했는가?mocks/handlers.ts에 합쳤는가?현재 PR의 리뷰 코멘트를 분석해 타당한 것만 반영하는 스킬. "리뷰 반영해줘", "PR 리뷰 처리해줘", "코드래빗 리뷰 봐줘", "리뷰 코멘트 반영", "follow review", "apply review" 요청 시 트리거한다. 사람 리뷰는 존중하고 AI 리뷰는 선별해 반영하며, 수정 후 검증한다.
Figma 디자인을 가져와 frontend/src에 컴포넌트로 구현하는 스킬. "피그마 적용", "figma 디자인 구현해줘", "이 화면 만들어줘", "캡쳐한 디자인대로 만들어줘", figma.com URL 제공 시 트리거한다. 기존 디자인 토큰과 shared/ui 컴포넌트를 재사용해 구현한다.
frontend/.claude/skills/ 아래에 새 프론트엔드 스킬을 만드는 메타 스킬. "스킬 만들어줘", "skill 생성", "새 스킬 추가", "fe 스킬 만들어줘", "스킬 크리에이터" 요청 시 트리거한다. 기존 fe- 스킬과 형식·말투·범위를 일치시켜 SKILL.md를 생성한다.
frontend/src 코드에 테스트를 작성하는 스킬. "테스트 작성해줘", "test 짜줘", "테스트 추가해줘", "이거 테스트 커버해줘", "spec 작성" 요청 시 트리거한다. 대상에 맞는 도구를 골라 계약 중심 테스트를 작성한다.
frontend/src 변경을 시니어 개발자 시선으로 검증하는 QA 스킬. "QA 해줘", "검증해줘", "코드 리뷰", "리뷰해줘", "merge 전에 봐줘" 요청 시 트리거한다. 구현하지 않고 검증과 보고만 수행한다.
Notion에서 백엔드 모듈의 API 명세를 MCP로 가져와 docs/backend/api-docs/{module}.md에 저장하는 스킬. "Notion API 가져와줘", "api-docs 동기화", "API 명세 불러와줘", "[모듈] API 문서 받아와", "api-docs 업데이트", "Notion에서 [모듈] 명세 내려받아" 요청 시 트리거한다. be-orchestrate가 Phase 1에서 내부적으로 사용하며 독립적으로도 트리거 가능하다.