auto-doc-sync

Imported from dnjsdn6248-stack/eum_frontend (.claude/skills/auto-doc-sync/SKILL.md). Install upstream with npx skills add dnjsdn6248-stack/eum_frontend --skill auto-doc-sync. Copyright stays with the author.

문서 자동 동기화 (Auto Doc Sync)

코드 변경 시 문서 갱신이 누락되는 일이 없도록 강제하는 가이드.

핵심 규칙 요약

Auto-Doc Sync: 어떤 변경이 docs 갱신을 트리거하는가

갱신이 필요한 코드 변경

갱신 불필요한 변경

• UI 레이아웃·스타일 변경
• 리팩토링 (동작 변경 없음)
• 에러 메시지 문구 수정
• 성능 최적화

Docs First: 작업 시작 전 필독 순서

1. CLAUDE.md 전체 확인 (특히 Rules)
   ↓
2. 관련 docs/*.md 읽기
   - 상품 관련    → docs/domain/product.md
   - 주문 관련    → docs/domain/order.md
   - 리뷰 관련    → docs/domain/review.md
   - 인증 관련    → docs/domain/auth.md
   - 카트 관련    → docs/domain/cart.md
   - 위시리스트   → docs/domain/wishlist.md
   - 유저 관련    → docs/domain/user.md
   - 뷰 레이아웃  → docs/view/{view}.md
   ↓
3. 수정할 코드 파일 Read 도구로 읽기
   ↓
4. 문서와 코드 사이 괴리 발견 시 → 먼저 사용자에게 확인

Change Report: 변경 보고 형식

작업 완료 후 반드시 아래 형식으로 보고:

### 수정된 코드
- `src/api/productApi.js` — getMainBestSellers transformResponse 구조 변경

### 수정된 문서
- `docs/domain/product.md` § 랜딩페이지 전용 Queries — 응답 구조 갱신

현재 docs 파일 목록

docs/
├── project-structure.md     전체 src/ 구조 개요
├── api-hooks.md             API 훅 전체 목록
└── domain/
    ├── auth.md              인증·소셜로그인
    ├── product.md           상품·카테고리·랜딩페이지 섹션
    ├── review.md            리뷰 CRUD
    ├── cart.md              장바구니
    ├── order.md             주문
    ├── wishlist.md          위시리스트
    ├── user.md              회원·포인트·쿠폰
    └── ui.md                공통 UI 컴포넌트

docs/view/ 폴더는 아직 없음 — 복합 뷰 추가 시 생성.

새 docs/*.md 작성 방법

필수 섹션:

1. 개요 — 도메인의 역할과 담당 범위
2. 비즈니스 정책 — 계산식, 제한 수치, 상태 전이 규칙 (코드 위치 명시)
3. API 엔드포인트 — 훅명 / 메서드 / 경로 / 응답 구조
4. 데이터 구조 — transformResponse 후 컴포넌트 전달 형태
5. 캐시 무효화 전략 — providesTags / invalidatesTags

문서 작성 품질 기준

좋은 비즈니스 정책 기술 ✅

## 배송비 정책
| 조건 | 배송비 |
|---|---|
| 주문 금액 **50,000원 이상** | **무료** |
| 주문 금액 50,000원 미만 | **3,000원** |
- 코드 위치: `src/shared/utils/formatters.js` → `calcShippingFee()`

나쁜 기술 ❌

## 배송비
배송비는 주문 금액에 따라 달라집니다.

코드 위치 없고, 수치 없음 → 나중에 코드와 괴리 발생.

API 응답 구조 명세 예시

#### `useGetHomeBestsellerQuery` 응답 구조 (`searchApi.js`)
```js
[
  {
    id, rank, name, img, price,
    score, salesCount, productUrl
  }
]
// GET /search/products/home-bestseller