@kood/claude-code 0.5.0 → 0.5.3

package/templates/.claude/instructions/tech-stack/design-standards.md

@@ -0,0 +1,282 @@
+# Design Standards
+
+**목적**: UI/UX 및 접근성 표준
+
+## 접근성 (Accessibility)
+
+### WCAG 2.2 AA 준수
+
+**필수 기준:**
+
+| 기준 | 요구사항 | 예시 |
+|------|----------|------|
+| **색상 대비** | 4.5:1 이상 | 텍스트-배경 대비 |
+| **키보드 네비게이션** | 모든 기능 접근 가능 | Tab, Enter, Space |
+| **ARIA 속성** | 적절한 레이블 | aria-label, aria-describedby |
+| **포커스 표시** | 시각적 표시 필수 | outline, ring |
+
+### ARIA 속성
+
+```tsx
+// ✅ 올바른 ARIA 사용
+<button
+  aria-label="사용자 삭제"
+  aria-describedby="delete-description"
+  onClick={handleDelete}
+>
+  <TrashIcon />
+</button>
+<span id="delete-description" className="sr-only">
+  이 작업은 되돌릴 수 없습니다
+</span>
+
+// ❌ 잘못된 예
+<button onClick={handleDelete}>
+  <TrashIcon />  {/* 스크린 리더가 읽을 수 없음 */}
+</button>
+```
+
+### 키보드 네비게이션
+
+```tsx
+// ✅ 키보드 지원
+function Modal({ isOpen, onClose }) {
+  useEffect(() => {
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+
+    if (isOpen) {
+      document.addEventListener('keydown', handleEscape)
+      return () => document.removeEventListener('keydown', handleEscape)
+    }
+  }, [isOpen, onClose])
+
+  return (
+    <div role="dialog" aria-modal="true">
+      {/* 모달 내용 */}
+    </div>
+  )
+}
+```
+
+### 스크린 리더
+
+```tsx
+// ✅ 스크린 리더 전용 텍스트
+<span className="sr-only">Loading...</span>
+
+// Tailwind CSS
+<span className="absolute inset-0 -z-10">
+  시각적으로 숨김
+</span>
+```
+
+## 색상 시스템
+
+### 60-30-10 규칙
+
+| 비율 | 용도 | 예시 |
+|------|------|------|
+| **60%** | 배경 | bg-gray-50 |
+| **30%** | 보조 | bg-gray-200 |
+| **10%** | 강조 | bg-blue-500 |
+
+### Tailwind CSS v4 @theme
+
+```css
+@theme {
+  /* 색상 팔레트 */
+  --color-primary-50: #eff6ff;
+  --color-primary-500: #3b82f6;
+  --color-primary-900: #1e3a8a;
+
+  /* 간격 */
+  --spacing-4: 1rem;
+  --spacing-8: 2rem;
+
+  /* 폰트 */
+  --font-sans: 'Inter', sans-serif;
+}
+```
+
+### 색상 대비 검증
+
+```typescript
+// 대비율 계산 도구 사용
+// https://webaim.org/resources/contrastchecker/
+
+// 예시:
+// 텍스트: #333333 (어두운 회색)
+// 배경: #FFFFFF (흰색)
+// 대비율: 12.63:1 ✅ (4.5:1 이상)
+```
+
+## 레이아웃
+
+### 간격 시스템 (8px Grid)
+
+```tsx
+// ✅ 8의 배수 사용
+<div className="p-4">   {/* 16px */}
+  <div className="mb-8"> {/* 32px */}
+    <h1 className="text-2xl">Title</h1>
+  </div>
+</div>
+
+// ❌ 임의의 값
+<div className="p-[13px]">  {/* 비권장 */}
+</div>
+```
+
+### 반응형 디자인
+
+```tsx
+// ✅ Mobile-first
+<div className="
+  w-full            {/* 모바일 */}
+  md:w-1/2          {/* 태블릿 */}
+  lg:w-1/3          {/* 데스크톱 */}
+">
+  Content
+</div>
+```
+
+### Safe Area (iOS/Android)
+
+```tsx
+// tailwindcss-safe-area 플러그인 사용
+<div className="
+  pb-4
+  pb-[calc(1rem+env(safe-area-inset-bottom))]
+">
+  하단 버튼
+</div>
+```
+
+## 타이포그래피
+
+### 폰트 시스템 (2-3개)
+
+```css
+@theme {
+  --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+}
+```
+
+### 크기 및 행간
+
+```tsx
+// ✅ 적절한 행간
+<p className="text-base leading-relaxed">  {/* 1.625 */}
+  긴 텍스트는 행간을 넓게
+</p>
+
+<h1 className="text-4xl leading-tight">  {/* 1.25 */}
+  제목은 행간을 좁게
+</h1>
+```
+
+## 인터랙션
+
+### 호버/포커스 상태
+
+```tsx
+// ✅ 명확한 상태 표시
+<button className="
+  bg-blue-500
+  hover:bg-blue-600
+  focus:ring-4 focus:ring-blue-300
+  transition-colors
+">
+  버튼
+</button>
+```
+
+### 로딩 상태
+
+```tsx
+// ✅ 로딩 인디케이터
+{isLoading ? (
+  <div className="flex items-center gap-2">
+    <Spinner className="w-4 h-4" />
+    <span>Loading...</span>
+  </div>
+) : (
+  <button>Submit</button>
+)}
+```
+
+### 에러 상태
+
+```tsx
+// ✅ 명확한 에러 메시지
+{error && (
+  <div
+    role="alert"
+    className="bg-red-50 border border-red-200 p-4 rounded"
+  >
+    <p className="text-red-800">{error.message}</p>
+  </div>
+)}
+```
+
+## 성능
+
+### 이미지 최적화
+
+```tsx
+// ✅ Next.js Image 또는 적절한 최적화
+<img
+  src="/image.jpg"
+  alt="설명"
+  loading="lazy"
+  width={800}
+  height={600}
+/>
+```
+
+### 코드 스플리팅
+
+```typescript
+// ✅ 동적 import
+const HeavyComponent = lazy(() => import('./HeavyComponent'))
+
+<Suspense fallback={<Spinner />}>
+  <HeavyComponent />
+</Suspense>
+```
+
+## 체크리스트
+
+### 접근성
+
+- [ ] 색상 대비 4.5:1 이상
+- [ ] 모든 interactive 요소 키보드 접근 가능
+- [ ] ARIA 속성 적절히 사용
+- [ ] 포커스 표시 명확
+- [ ] 스크린 리더 지원
+
+### 디자인
+
+- [ ] 60-30-10 색상 규칙
+- [ ] 8px 그리드 간격
+- [ ] 2-3개 폰트 사용
+- [ ] 반응형 디자인 (mobile-first)
+- [ ] Safe Area 고려
+
+### 인터랙션
+
+- [ ] 호버/포커스 상태 명확
+- [ ] 로딩 상태 표시
+- [ ] 에러 메시지 명확
+- [ ] 전환 애니메이션 자연스러움
+
+### 성능
+
+- [ ] 이미지 lazy loading
+- [ ] 코드 스플리팅
+- [ ] 불필요한 리렌더 방지
+
+**디자인 표준 준수 → 접근성 + 사용성 향상**

package/templates/.claude/instructions/tech-stack/index.md

@@ -0,0 +1,70 @@
+# Tech Stack
+
+기술 스택 사용 패턴
+
+## 파일 목록
+
+| 파일 | 설명 |
+|------|------|
+| [tanstack-patterns.md](./tanstack-patterns.md) | TanStack Start/Router/Query 패턴 |
+| [prisma-patterns.md](./prisma-patterns.md) | Prisma 7.x 사용 패턴 |
+| [design-standards.md](./design-standards.md) | UI/UX 및 접근성 표준 |
+
+## 사용법
+
+```markdown
+@.claude/instructions/tech-stack/tanstack-patterns.md
+@.claude/instructions/tech-stack/prisma-patterns.md
+@.claude/instructions/tech-stack/design-standards.md
+```
+
+## 빠른 참고
+
+### TanStack Patterns
+
+서버 함수, 라우팅, 쿼리 상태 관리 패턴
+
+**주요 내용:**
+- Server Function 작성 (GET/POST/PUT)
+- inputValidator + middleware 체인
+- Route loader 패턴
+- TanStack Query (useQuery, useMutation)
+- Optimistic Updates
+
+### Prisma Patterns
+
+데이터베이스 스키마 및 쿼리 작성 패턴
+
+**주요 내용:**
+- Prisma 7.x 버전 (prisma-client, output)
+- Single/Multi-File 스키마 구조
+- CRUD Operations
+- Relations (1:N, N:N)
+- N+1 Problem 방지
+- Index 최적화
+
+### Design Standards
+
+UI/UX 및 접근성 표준
+
+**주요 내용:**
+- WCAG 2.2 AA 준수 (색상 대비 4.5:1+)
+- ARIA 속성 및 키보드 네비게이션
+- 60-30-10 색상 규칙
+- 8px 간격 시스템
+- Safe Area (iOS/Android)
+- 반응형 디자인 (mobile-first)
+
+## 체크리스트
+
+### 문서 선택
+
+- TanStack 작업 → [tanstack-patterns.md](./tanstack-patterns.md)
+- 데이터베이스 작업 → [prisma-patterns.md](./prisma-patterns.md)
+- UI/UX 작업 → [design-standards.md](./design-standards.md)
+
+### 작업 전
+
+- [ ] 해당 패턴 문서 읽기
+- [ ] 체크리스트 항목 확인
+- [ ] 코드 예시 참고

package/templates/.claude/instructions/tech-stack/prisma-patterns.md

@@ -0,0 +1,352 @@
+# Prisma Patterns
+
+**목적**: Prisma 7.x 사용 패턴 및 주의사항
+
+## 버전 정보
+
+**Prisma 7.x 사용 중**
+
+- 패키지명: `prisma-client` (prisma가 아님)
+- output 경로 필수: `output = "./generated/client"`
+
+## 클라이언트 초기화
+
+```typescript
+// src/database/prisma.ts
+import { PrismaClient } from './generated/client'
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined
+}
+
+export const prisma = globalForPrisma.prisma ?? new PrismaClient()
+
+if (process.env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = prisma
+}
+```
+
+**필수:**
+- [ ] PrismaClient import 경로 확인 (`./generated/client`)
+- [ ] globalThis 패턴 사용 (개발 모드 hot reload 대응)
+
+## Schema 구조
+
+### Single File
+
+```prisma
+// prisma/schema.prisma
+
+generator client {
+  provider = "prisma-client-js"
+  output   = "./generated/client"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        Int      @id @default(autoincrement())
+  email     String   @unique
+  name      String
+  posts     Post[]
+  createdAt DateTime @default(now())
+}
+
+model Post {
+  id        Int      @id @default(autoincrement())
+  title     String
+  content   String
+  authorId  Int
+  author    User     @relation(fields: [authorId], references: [id])
+  createdAt DateTime @default(now())
+}
+```
+
+### Multi-File Structure
+
+**명시적 요청 시에만 사용**
+
+```
+prisma/schema/
+├── +base.prisma      # datasource, generator
+├── +enum.prisma      # 모든 enum
+├── user.prisma       # User 모델
+└── post.prisma       # Post 모델
+```
+
+```prisma
+// prisma/schema/+base.prisma
+generator client {
+  provider = "prisma-client-js"
+  output   = "../generated/client"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+```
+
+```prisma
+// prisma/schema/+enum.prisma
+/// 사용자 역할
+enum UserRole {
+  /// 관리자
+  ADMIN
+  /// 일반 사용자
+  USER
+}
+```
+
+```prisma
+// prisma/schema/user.prisma
+/// 사용자
+model User {
+  /// 고유 식별자
+  id        Int      @id @default(autoincrement())
+  /// 이메일 (고유)
+  email     String   @unique
+  /// 이름
+  name      String
+  /// 역할
+  role      UserRole @default(USER)
+  /// 생성 시각
+  createdAt DateTime @default(now())
+}
+```
+
+**Multi-File 규칙:**
+
+- [ ] 모든 모델/필드/enum에 한글 주석 필수
+- [ ] `+base.prisma`: datasource, generator
+- [ ] `+enum.prisma`: 모든 enum 정의
+- [ ] `[model].prisma`: 모델별 파일
+
+## CRUD Operations
+
+### Create
+
+```typescript
+const user = await prisma.user.create({
+  data: {
+    email: 'user@example.com',
+    name: 'User Name'
+  }
+})
+```
+
+### Read
+
+```typescript
+// 단일 조회
+const user = await prisma.user.findUnique({
+  where: { id: 1 }
+})
+
+// 목록 조회
+const users = await prisma.user.findMany({
+  where: { role: 'USER' },
+  include: { posts: true }
+})
+
+// 페이지네이션
+const users = await prisma.user.findMany({
+  skip: 20,
+  take: 10,
+  orderBy: { createdAt: 'desc' }
+})
+```
+
+### Update
+
+```typescript
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: { name: 'New Name' }
+})
+```
+
+### Delete
+
+```typescript
+const user = await prisma.user.delete({
+  where: { id: 1 }
+})
+```
+
+## Relations
+
+### 1:N (One-to-Many)
+
+```prisma
+model User {
+  id    Int    @id @default(autoincrement())
+  posts Post[]
+}
+
+model Post {
+  id       Int  @id @default(autoincrement())
+  authorId Int
+  author   User @relation(fields: [authorId], references: [id])
+}
+```
+
+```typescript
+// Include posts
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  include: { posts: true }
+})
+
+// Create with relation
+const post = await prisma.post.create({
+  data: {
+    title: 'Post Title',
+    author: {
+      connect: { id: 1 }
+    }
+  }
+})
+```
+
+### N:N (Many-to-Many)
+
+```prisma
+model Post {
+  id   Int    @id @default(autoincrement())
+  tags Tag[]
+}
+
+model Tag {
+  id    Int    @id @default(autoincrement())
+  posts Post[]
+}
+```
+
+```typescript
+// Create with tags
+const post = await prisma.post.create({
+  data: {
+    title: 'Post Title',
+    tags: {
+      connect: [{ id: 1 }, { id: 2 }]
+    }
+  }
+})
+```
+
+## Transactions
+
+```typescript
+const result = await prisma.$transaction(async (tx) => {
+  const user = await tx.user.create({
+    data: { email: 'user@example.com', name: 'User' }
+  })
+
+  const post = await tx.post.create({
+    data: {
+      title: 'Post Title',
+      authorId: user.id
+    }
+  })
+
+  return { user, post }
+})
+```
+
+## 자동 실행 금지
+
+**절대 자동 실행하지 않음:**
+
+```bash
+# ❌ 금지
+prisma db push
+prisma migrate dev
+prisma generate
+
+# ✅ 올바름: 사용자에게 안내
+echo "schema.prisma 수정 완료. 다음 명령어 실행 필요:"
+echo "  prisma db push"
+```
+
+**이유:**
+- DB 변경은 중요한 작업
+- 사용자가 직접 확인 후 실행
+- 의도하지 않은 데이터 손실 방지
+
+## Index 최적화
+
+```prisma
+model User {
+  id        Int      @id @default(autoincrement())
+  email     String   @unique
+  name      String
+  createdAt DateTime @default(now())
+
+  @@index([createdAt])
+  @@index([email, name])
+}
+```
+
+**Index 사용 기준:**
+
+- [ ] WHERE 조건에 자주 사용되는 필드
+- [ ] JOIN에 사용되는 외래 키
+- [ ] ORDER BY에 사용되는 필드
+
+## N+1 Problem 방지
+
+```typescript
+// ❌ N+1 Problem
+const users = await prisma.user.findMany()
+for (const user of users) {
+  const posts = await prisma.post.findMany({
+    where: { authorId: user.id }
+  })
+}
+
+// ✅ Include 사용
+const users = await prisma.user.findMany({
+  include: { posts: true }
+})
+
+// ✅ Select 최적화
+const users = await prisma.user.findMany({
+  select: {
+    id: true,
+    name: true,
+    posts: {
+      select: {
+        id: true,
+        title: true
+      }
+    }
+  }
+})
+```
+
+## 체크리스트
+
+### Schema 작성
+
+- [ ] `generator client` output 경로 확인
+- [ ] Multi-File 사용 시 한글 주석 필수
+- [ ] Index 적절히 설정
+- [ ] Relations 올바르게 정의
+
+### 쿼리 작성
+
+- [ ] N+1 Problem 회피 (include/select 사용)
+- [ ] 페이지네이션 적용 (skip/take)
+- [ ] 트랜잭션 필요 시 `$transaction` 사용
+
+### 자동 실행 금지
+
+- [ ] `prisma db push` 자동 실행 금지
+- [ ] `prisma migrate dev` 자동 실행 금지
+- [ ] `prisma generate` 자동 실행 금지
+
+**Prisma 패턴 준수 → 타입 안전 + 성능 최적화**