AGENTS.md — AI 에이전트를 위한 npm 패키지 문서화 전략

## Summary
shimmer-trace는 React 로딩 상태를 위한 Shimmer 컴포넌트 라이브러리다.
데이터 페칭 중 스켈레톤 UI를 표시할 때 사용한다.
React 18+, TypeScript 5+ 지원.

## Exports
- `Shimmer` — 기본 래퍼 컴포넌트
- `ShimmerText` — 텍스트 전용 스켈레톤
- `ShimmerImage` — 이미지 전용 스켈레톤
- `useShimmer` — 로딩 상태 훅

## Types
 
interface ShimmerProps {
  loading: boolean          // 필수. true면 스켈레톤, false면 children 표시
  children: React.ReactNode // 필수. 로딩 완료 후 표시할 콘텐츠
  width?: string | number   // 선택. 기본값: '100%'
  height?: string | number  // 선택. 기본값: 'auto'
  rounded?: boolean         // 선택. true면 border-radius: 8px. 기본값: false
  duration?: number         // 선택. 애니메이션 주기(ms). 기본값: 1500
}

## Usage Patterns
 
// Pattern 1: 기본 래핑
import { Shimmer } from 'shimmer-trace'
 
function UserCard({ userId }: { userId: string }) {
  const { data: user, loading } = useFetchUser(userId)
  return (
    <Shimmer loading={loading}>
      <div className="card">
        <h2>{user?.name}</h2>
        <p>{user?.email}</p>
      </div>
    </Shimmer>
  )
}
 
// Pattern 2: 고정 크기 스켈레톤
function AvatarSkeleton() {
  return <Shimmer loading={true} width={48} height={48} rounded />
}

## Decision Tree
 
Q: 이미지 로딩에 쓸 건가?
  → ShimmerImage 사용
 
Q: 텍스트 줄 여러 개를 보여줄 건가?
  → ShimmerText + lines prop 사용
 
Q: 커스텀 레이아웃 전체를 감쌀 건가?
  → Shimmer 기본 컴포넌트 사용
 
Q: 프로그래밍 방식으로 제어해야 하나?
  → useShimmer 훅 사용

## Common Mistakes
 
❌ loading prop 없이 사용
<Shimmer><UserCard /></Shimmer>
 
✅ loading prop 반드시 전달
<Shimmer loading={isLoading}><UserCard /></Shimmer>
 
❌ 중첩 Shimmer
<Shimmer loading={outer}>
  <Shimmer loading={inner}><Content /></Shimmer>
</Shimmer>
 
✅ 가장 바깥 Shimmer 하나만 사용
<Shimmer loading={outer || inner}><Content /></Shimmer>

{
  "name": "shimmer-trace",
  "version": "1.2.0",
  "files": [
    "dist",
    "AGENTS.md"
  ]
}