Backend API 엔드포인트 및 응답 형식 확인 없이 추측으로 코드 생성하는 문제

문제 상황

Claude Code가 Backend API 엔드포인트와 응답 형식을 확인하지 않고 추측으로 Frontend 코드를 생성합니다.

재현 방법

1. Backend에 다음과 같은 엔드포인트가 존재:

• GET /api/projects/{project_id}/datasheets
• response_model: DatasheetGetResponse (객체 형식: { success: bool, datasheets: [...] })

1. 사용자가 "datasheet 조회 함수 만들어줘"라고 요청

1. Claude가 Backend 코드 확인 없이 다음과 같이 잘못된 코드 생성:

``typescript
// 잘못된 엔드포인트
const response = await apiClient.get(/datasheets`, {
params: { project_id: projectId }
});

// 잘못된 응답 형식 가정 (배열 직접 반환이라고 추측)
const hasDatasheet = response.data && response.data.length > 0;
```

예상 동작

1. Backend 라우터 파일 확인

• 엔드포인트 경로 확인
• 라우터 prefix 확인

1. response_model 스키마 확인

• 스키마 정의 확인
• 응답 구조 파악 (객체/배열, 중첩 구조 등)

1. 확인한 정보 기반으로 정확한 코드 생성

실제 동작

Backend 코드를 확인하지 않고 다음과 같이 추측으로 코드 생성:

• 엔드포인트 추측 → 404 에러 발생
• 응답 형식 추측 → undefined 체크로 인해 로직 오작동
• 여러 번 수정 필요

영향

• 개발자가 직접 Backend 코드 확인 후 여러 번 수정 요청 필요
• 시간 낭비 및 불필요한 반복 작업 발생
• 코드 신뢰성 저하

제안 해결 방안

필수 작업 순서:

1. Backend 엔드포인트 확인

``bash
# 라우터 파일에서 엔드포인트 확인
rg "@router.get" app/routers/
# 라우터 prefix 확인
rg "router.*prefix" app/main.py
``

1. 응답 모델 확인

``bash
# response_model 찾기
rg "response_model.*ClassName"
# 스키마 정의 확인
cat app/schemas/...
``

1. 응답 구조 파악 후 코드 생성

• 스키마 필드 확인
• 중첩 구조 확인
• 배열/객체 구분

환경

• Claude Code 버전: claude-sonnet-4-5-20250929
• 발생 날짜: 2026-02-02
• Backend: FastAPI + SQLAlchemy
• Frontend: Next.js + TypeScript