sam-react-prod/claudedocs/guides/[GUIDE] collaboration-with-claude.md

Claude와 효율적인 협업 가이드

데이터 페칭 요청 시 체크리스트

□ API 엔드포인트 + 메서드
□ 응답 JSON 구조 (성공/실패)
□ 인증 방식 (HttpOnly 쿠키면 프록시 필요)
□ UI 시나리오 (로딩/성공/실패)

이 4가지만 있으면 바로 구현 가능!

---

CSS vs 데이터 페칭 협업 차이

CSS	데이터 페칭
시각적 비교로 충분	보이지 않는 로직이라 설명 필요
"이거 안 맞아" → 바로 이해	"안 돼" → 어디서? 왜? 필요
스크린샷이 곧 스펙	API 응답이 곧 스펙

---

상황별 질문 템플릿

1. 데이터 페칭 요청

## 기능: [기능명]

### API
- 엔드포인트:
- 메서드: GET/POST/PUT/DELETE
- 인증: HttpOnly 쿠키 / Bearer

### 응답 구조
```json
{ ... }

UI 동작

• 로딩 중:
• 성공 시:
• 실패 시:

### 2. 에러 발생 시

```markdown
## 에러: [에러 메시지]

### Network 탭 정보
- Request URL:
- Request Headers:
- Response:

### 콘솔 에러 (있다면)

3. 기능 요청 시

## 기능: [기능명]

### 기대 동작
1. [트리거] 클릭/입력/등
2. [API 호출] (있다면)
3. [성공 시] →
4. [실패 시] →

4. CSS 수정 요청 시

## 수정 대상: [컴포넌트/파일명]

### 현재
[현재 상태 설명 또는 스크린샷]

### 원하는
[기대 상태 설명 또는 React 원본 참조]

---

기억할 점

• CSS: 지금처럼 하면 완벽 ✅
• 데이터 페칭: API 응답 구조 + 시나리오만 추가하면 OK
• 에러: 전체 에러 스택/Network 탭 정보 공유하면 빠른 해결

---

공통 UI 컴포넌트 사용 규칙

로딩 스피너

필수: 로딩 상태 표시 시 반드시 공통 스피너 컴포넌트 사용

import {
  ContentLoadingSpinner,
  PageLoadingSpinner,
  TableLoadingSpinner,
  ButtonSpinner
} from '@/components/ui/loading-spinner';

컴포넌트	용도	예시
ContentLoadingSpinner	상세/수정 페이지 컨텐츠 영역	if (isLoading) return <ContentLoadingSpinner />;
PageLoadingSpinner	페이지 전환, 전체 페이지	loading.tsx, 초기 로딩
TableLoadingSpinner	테이블/리스트 영역	데이터 테이블 로딩
ButtonSpinner	버튼 내부 (저장 중 등)	{isSaving && <ButtonSpinner />}

금지 패턴:

// ❌ 텍스트만 사용 금지
<div className="text-muted-foreground">로딩 중...</div>

// ❌ 직접 스피너 구현 금지
<div className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-500" />

---

2025-11-27 작성 / 2026-01-12 스피너 규칙 추가