timsquad 2.1.0 → 3.4.0

package/templates/base/skills/controller/references/README.md

@@ -0,0 +1,35 @@
+---
+title: Controller References
+category: reference
+---
+
+# Controller References
+
+이 디렉토리에는 `tsq compile`로 생성된 에이전트용 spec 파일이 위치합니다.
+
+## 사용법
+
+```bash
+tsq compile        # SSOT → spec 컴파일
+tsq compile status # stale 상태 확인
+```
+
+## 파일 구조
+
+컴파일 후 생성되는 파일 예시:
+
+```
+references/
+├── 2-1-로그인.spec.md        ← service-spec.md#2.1 로그인
+├── 2-2-토큰-갱신.spec.md     ← service-spec.md#2.2 토큰 갱신
+├── error-codes.spec.md       ← error-codes.md (전체)
+└── users.spec.md             ← data-design.md#Users
+```
+
+각 파일에는 source marker가 포함되어 원본 추적이 가능합니다:
+
+```html
+<!-- source: ssot/service-spec.md#POST-auth-login -->
+<!-- ssot-hash: a3f2b1c0 -->
+<!-- compiled: 2026-02-18T10:30:00Z -->
+```

package/templates/base/skills/controller/rules/README.md

@@ -0,0 +1,18 @@
+---
+title: Controller Rules
+category: guide
+---
+
+# Controller Rules
+
+이 디렉토리에는 `tsq compile`로 생성된 제약 규칙 파일이 위치합니다.
+
+## 파일 구조
+
+```
+rules/
+├── completion-criteria.md     ← requirements.md에서 컴파일
+└── security-constraints.md    ← security-spec.md에서 컴파일 (Level 3)
+```
+
+이 파일들은 controller가 서브에이전트에게 "무엇을 지켜야 하는지" 주입할 때 사용됩니다.

package/templates/base/skills/database/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: database
+description: |
+  데이터베이스 설계 및 운영 방법론.
+  정규화/비정규화 결정, 쿼리 최적화 프로세스, 마이그레이션 안전 규칙.
+  Use when: DB 설계, 스키마 변경, 쿼리 최적화, 마이그레이션
+version: "1.0.0"
+tags: [database, sql, migration]
+user-invocable: false
+---
+
+# Database Methodology
+
+## 정규화 기준
+
+| 정규형 | 적용 기준 | 예외 허용 조건 |
+|:-----:|---------|--------------|
+| 1NF | 필수 | 없음 |
+| 2NF | 필수 | 없음 |
+| 3NF | 기본 적용 | 읽기 성능 요구 시 |
+| BCNF | 권장 | 복잡도 증가 시 |
+
+## 비정규화 조건
+
+비정규화 결정 시 반드시 ADR 작성:
+
+```markdown
+## ADR-XXX: [테이블명] 비정규화 결정
+
+### Context
+- 읽기 빈도: X회/초, 쓰기 빈도: Y회/초, 조인 비용: Z ms
+
+### Decision
+[비정규화 결정 내용]
+
+### Consequences
+- 장점: 읽기 성능 N% 향상
+- 단점: 데이터 중복, 갱신 이상 위험
+- 대응: [트리거/애플리케이션 로직]
+```
+
+## 쿼리 최적화 프로세스
+
+### 1. 분석
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) SELECT ...;
+```
+
+### 2. 체크리스트
+
+| 항목 | 확인 내용 |
+|-----|----------|
+| Seq Scan | 대용량 테이블에 순차 스캔? |
+| Index 사용 | 적절한 인덱스 사용 중? |
+| Join 순서 | 작은 테이블 먼저 조인? |
+| N+1 | 루프 내 쿼리 실행? |
+| 불필요 컬럼 | SELECT * 사용? |
+
+### 3. 최적화 기법
+
+| 문제 | 해결책 |
+|-----|-------|
+| 느린 조인 | 인덱스 추가, 조인 순서 변경 |
+| N+1 | Eager Loading, JOIN |
+| 대용량 스캔 | 파티셔닝, 커버링 인덱스 |
+| 동시성 | 적절한 격리 수준 |
+
+## 마이그레이션 규칙
+
+### 파일 명명
+
+```
+{timestamp}_{description}.sql
+예: 20260203100000_create_users_table.sql
+```
+
+### 안전한 마이그레이션
+
+| 작업 | 안전 | 위험 | 대안 |
+|-----|:----:|:----:|------|
+| 컬럼 추가 (NULL) | O | | |
+| 컬럼 추가 (NOT NULL) | | ! | DEFAULT 값 + NULL 허용 후 변경 |
+| 컬럼 삭제 | | ! | 코드 먼저 수정 -> 삭제 |
+| 컬럼명 변경 | | X | 새 컬럼 추가 -> 데이터 이동 -> 삭제 |
+| 인덱스 추가 | O | | CONCURRENTLY 사용 |
+| 테이블 삭제 | | X | 백업 확인 필수 |
+
+### 롤백 전략
+
+모든 마이그레이션에 롤백 스크립트 필수:
+
+```sql
+-- Up
+ALTER TABLE users ADD COLUMN phone VARCHAR(20);
+-- Down
+ALTER TABLE users DROP COLUMN phone;
+```

package/templates/base/skills/database/prisma/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: prisma
+description: Prisma ORM 개발 가이드라인
+version: "1.0.0"
+tags: [prisma, orm, database]
+user-invocable: false
+---
+
+# Prisma ORM Guidelines
+
+## 철학
+- Schema as SSOT — 스키마가 진실의 원천
+- Type Safety — 자동 생성 타입 활용
+- Migration First — 스키마 변경은 마이그레이션으로
+
+## 마이그레이션 워크플로우
+
+| 명령어 | 용도 |
+|--------|------|
+| `npx prisma migrate dev --name {name}` | 개발 환경 마이그레이션 |
+| `npx prisma migrate deploy` | 프로덕션 적용 |
+| `npx prisma migrate reset` | DB 초기화 + 재적용 |
+| `npx prisma db push` | 빠른 프로토타이핑 (마이그레이션 없이) |
+| `npx prisma generate` | 클라이언트 재생성 |
+
+**순서**: schema.prisma 수정 → migrate dev → SQL 검토 → 커밋
+
+## Rules
+
+### 스키마
+- 모든 모델에 `id`, `createdAt`, `updatedAt`
+- 명시적 인덱스 정의 (`@@index`)
+- `@@map`으로 테이블명 명시
+- 관계는 명확히 정의
+
+### 쿼리
+- `select`로 필요한 필드만 조회 (성능)
+- 페이지네이션 적용 (`take`, `skip`)
+- 복잡한 작업은 트랜잭션 사용
+- **금지**: N+1 쿼리, 무한 결과 조회
+
+### 마이그레이션
+- `migrate dev`로 개발, `migrate deploy`로 배포
+- 마이그레이션 파일 커밋 필수
+- **금지**: 프로덕션에서 `db push`
+
+## Checklist
+- [ ] 싱글톤 인스턴스 사용
+- [ ] 마이그레이션으로 스키마 관리
+- [ ] 트랜잭션으로 데이터 정합성
+- [ ] select로 필요한 필드만 조회
+- [ ] 인덱스 적절히 설정
+- [ ] Repository 패턴 적용
+
+## 참조
+- `rules/schema-design.md` — 모델 정의, 공통 필드, 소프트 삭제 패턴
+- `rules/queries.md` — 싱글톤, CRUD, Relations, 트랜잭션, Repository 패턴

package/templates/base/skills/database/prisma/rules/queries.md

@@ -0,0 +1,133 @@
+---
+title: Prisma Query Patterns
+impact: HIGH
+tags: prisma, database, queries
+---
+
+# Prisma Query Patterns
+
+## 싱글톤 인스턴스
+
+```typescript
+// lib/prisma.ts
+import { PrismaClient } from '@prisma/client';
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined;
+};
+
+export const prisma = globalForPrisma.prisma ?? new PrismaClient({
+  log: process.env.NODE_ENV === 'development'
+    ? ['query', 'error', 'warn']
+    : ['error'],
+});
+
+if (process.env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = prisma;
+}
+```
+
+## Extensions (소프트 삭제 자동 필터)
+
+```typescript
+export const prisma = prismaBase.$extends({
+  query: {
+    $allModels: {
+      async findMany({ model, operation, args, query }) {
+        args.where = { ...args.where, deletedAt: null };
+        return query(args);
+      },
+    },
+  },
+});
+```
+
+## 기본 CRUD
+
+```typescript
+// Create
+const user = await prisma.user.create({
+  data: { email: 'test@example.com', name: 'Test', password: hashedPassword },
+});
+
+// Read
+const user = await prisma.user.findUnique({ where: { id: userId } });
+const users = await prisma.user.findMany({
+  where: { role: 'USER' },
+  orderBy: { createdAt: 'desc' },
+  take: 10, skip: 0,
+});
+
+// Update
+const updated = await prisma.user.update({
+  where: { id: userId },
+  data: { name: 'New Name' },
+});
+
+// Delete
+await prisma.user.delete({ where: { id: userId } });
+
+// Upsert
+const user = await prisma.user.upsert({
+  where: { email: 'test@example.com' },
+  update: { name: 'Updated Name' },
+  create: { email: 'test@example.com', name: 'New User', password },
+});
+```
+
+## Relations 로딩
+
+```typescript
+// include: 관계 데이터 포함
+const userWithPosts = await prisma.user.findUnique({
+  where: { id: userId },
+  include: { posts: true, profile: true },
+});
+
+// select: 특정 필드만 선택 (성능 최적화)
+const userWithPosts = await prisma.user.findUnique({
+  where: { id: userId },
+  select: {
+    id: true, name: true,
+    posts: { select: { id: true, title: true }, where: { published: true }, take: 5 },
+  },
+});
+```
+
+## 트랜잭션
+
+```typescript
+const result = await prisma.$transaction(async (tx) => {
+  const user = await tx.user.create({ data: { email, name, password } });
+  await tx.profile.create({ data: { userId: user.id, bio: '' } });
+  await tx.notification.create({ data: { userId: user.id, message: 'Welcome!' } });
+  return user;
+});
+// 실패 시 모두 롤백
+```
+
+## Repository 패턴
+
+```typescript
+export interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  findByEmail(email: string): Promise<User | null>;
+  save(user: User): Promise<User>;
+  delete(id: string): Promise<void>;
+}
+
+export class PrismaUserRepository implements UserRepository {
+  async findById(id: string) {
+    return prisma.user.findUnique({ where: { id } });
+  }
+  async findByEmail(email: string) {
+    return prisma.user.findUnique({ where: { email } });
+  }
+  async save(data: Omit<User, 'id' | 'createdAt' | 'updatedAt'>) {
+    return prisma.user.create({ data });
+  }
+  async delete(id: string) {
+    await prisma.user.delete({ where: { id } });
+  }
+}
+```

package/templates/base/skills/database/prisma/rules/schema-design.md

@@ -0,0 +1,80 @@
+---
+title: Prisma Schema Design Patterns
+impact: HIGH
+tags: prisma, database, schema
+---
+
+# Prisma Schema Design Patterns
+
+## 기본 모델 정의
+
+```prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  name      String
+  password  String
+  role      Role     @default(USER)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  posts     Post[]
+  profile   Profile?
+
+  @@index([email])
+  @@map("users")
+}
+
+model Post {
+  id        String   @id @default(cuid())
+  title     String
+  content   String?
+  published Boolean  @default(false)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  author    User     @relation(fields: [authorId], references: [id])
+  authorId  String
+
+  @@index([authorId])
+  @@map("posts")
+}
+
+enum Role {
+  USER
+  ADMIN
+}
+```
+
+## 공통 필드 패턴
+모든 모델에 공통으로 들어가는 필드 (Prisma는 상속 미지원, 컨벤션으로 관리):
+- `id String @id @default(cuid())`
+- `createdAt DateTime @default(now())`
+- `updatedAt DateTime @updatedAt`
+
+## 소프트 삭제
+
+```prisma
+model User {
+  id        String    @id @default(cuid())
+  deletedAt DateTime? // null이면 활성, 값 있으면 삭제됨
+  @@index([deletedAt])
+}
+```
+
+```typescript
+const activeUsers = await prisma.user.findMany({
+  where: { deletedAt: null },
+});
+```

package/templates/base/skills/frontend/nextjs/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: nextjs
+description: Next.js App Router 개발 가이드라인
+version: "1.0.0"
+tags: [nextjs, react, frontend]
+user-invocable: false
+---
+
+# Next.js 15+ App Router
+
+## 철학
+- Server First — 기본은 서버 컴포넌트
+- Progressive Enhancement — 필요할 때만 클라이언트
+- Colocation — 관련 파일은 가까이
+
+## Server vs Client 판단
+
+| 조건 | 컴포넌트 |
+|------|---------|
+| 데이터 페칭, DB 접근, 민감 정보 | Server (기본) |
+| 인터랙션, 이벤트, useState/useEffect | Client (`'use client'`) |
+| 브라우저 API 필요 | Client |
+| 그 외 | Server |
+
+## Rules
+
+### 컴포넌트
+- 기본은 Server Component
+- 인터랙션 필요할 때만 `'use client'`
+- Client Component는 작게 유지 (leaf에 배치)
+- **금지**: Server Component에서 useState/useEffect, 불필요한 `'use client'`
+
+### 데이터
+- Server Component에서 데이터 페칭
+- mutation은 Server Actions 사용
+- 적절한 캐싱 전략 설정
+- **금지**: Client Component에서 직접 DB 접근
+
+### 라우팅
+- 파일 기반 라우팅 규칙 준수
+- Route Group으로 레이아웃 관리
+- `loading.tsx`, `error.tsx` 제공
+
+## 성능 최적화
+- `next/image`: sizes 속성
+- `next/font`: 폰트 최적화
+- `next/link`: 프리페칭
+- 동적 import: 무거운 컴포넌트 지연 로딩
+
+## Checklist
+- [ ] Server Component 기본 사용
+- [ ] 'use client' 최소화
+- [ ] Server Actions로 mutation
+- [ ] 적절한 캐싱 전략
+- [ ] loading.tsx, error.tsx 구현
+- [ ] Metadata 설정
+
+## 참조
+- `rules/app-router.md` — 디렉토리 구조, Server/Client 예시, Data Fetching, Metadata, Loading/Error 패턴

package/templates/base/skills/frontend/nextjs/rules/app-router.md

@@ -0,0 +1,138 @@
+---
+title: Next.js App Router Patterns
+impact: HIGH
+tags: nextjs, frontend, app-router
+---
+
+# Next.js App Router Patterns
+
+## 디렉토리 구조
+
+```
+app/
+├── layout.tsx           # 루트 레이아웃 (필수)
+├── page.tsx             # 홈페이지 (/)
+├── loading.tsx          # 로딩 UI
+├── error.tsx            # 에러 UI
+├── not-found.tsx        # 404 UI
+│
+├── (auth)/              # Route Group (URL에 미포함)
+│   ├── login/page.tsx   # /login
+│   └── register/page.tsx # /register
+│
+├── dashboard/
+│   ├── layout.tsx       # 대시보드 레이아웃
+│   ├── page.tsx         # /dashboard
+│   └── settings/page.tsx # /dashboard/settings
+│
+├── users/
+│   ├── page.tsx         # /users (목록)
+│   └── [id]/
+│       ├── page.tsx     # /users/:id
+│       └── edit/page.tsx # /users/:id/edit
+│
+└── api/users/route.ts   # /api/users
+```
+
+## Server vs Client Component
+
+### 판단 기준
+```
+데이터 페칭 필요? → Server Component
+인터랙션/이벤트 필요? → Client Component ('use client')
+브라우저 API 필요? → Client Component
+그 외 → Server Component (기본)
+```
+
+### Server Component (기본)
+```typescript
+// app/users/page.tsx
+import { db } from '@/lib/db';
+
+export default async function UsersPage() {
+  const users = await db.user.findMany();
+  return (
+    <ul>
+      {users.map(user => <li key={user.id}>{user.name}</li>)}
+    </ul>
+  );
+}
+```
+
+### Client Component
+```typescript
+// components/counter.tsx
+'use client';
+import { useState } from 'react';
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>;
+}
+```
+
+## Data Fetching
+
+### Server Component에서 직접 fetch
+```typescript
+async function getPosts() {
+  const res = await fetch('https://api.example.com/posts', {
+    next: { revalidate: 60 },
+  });
+  return res.json();
+}
+```
+
+### Server Actions
+```typescript
+// app/actions/user.ts
+'use server';
+import { revalidatePath } from 'next/cache';
+
+export async function createUser(formData: FormData) {
+  const name = formData.get('name') as string;
+  await db.user.create({ data: { name, email: formData.get('email') as string } });
+  revalidatePath('/users');
+}
+```
+
+### 캐싱 전략
+| 옵션 | 설명 |
+|------|------|
+| `force-cache` | 기본값, 캐시 사용 |
+| `no-store` | 캐시 안 함, 항상 새로 요청 |
+| `revalidate: N` | N초마다 재검증 |
+| `revalidatePath()` | 특정 경로 재검증 |
+| `revalidateTag()` | 태그로 재검증 |
+
+## Metadata
+
+```typescript
+// 정적
+export const metadata: Metadata = { title: 'About Us' };
+
+// 동적
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { id } = await params;
+  const user = await getUser(id);
+  return { title: user.name };
+}
+```
+
+## Loading & Error
+
+```typescript
+// loading.tsx
+export default function Loading() { return <DashboardSkeleton />; }
+
+// error.tsx
+'use client';
+export default function Error({ error, reset }: { error: Error; reset: () => void }) {
+  return (
+    <div>
+      <h2>Something went wrong!</h2>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```

package/templates/base/skills/frontend/react/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: react
+description: React 컴포넌트 개발 가이드라인. 단일 책임, UI/로직 분리, 명시적 데이터 흐름, 서버/클라이언트 상태 분리.
+version: "1.0.0"
+tags: [react, components, frontend]
+user-invocable: false
+---
+
+# React Development Guidelines
+
+프로젝트 전체에서 일관된 React 컴포넌트 개발을 위한 컨벤션.
+
+## Philosophy
+
+- 컴포넌트는 단일 책임
+- UI와 로직 분리 (커스텀 훅)
+- Props로 명시적 데이터 흐름
+- 서버 상태와 클라이언트 상태 분리
+
+## Resources
+
+25개 규칙 (TimSquad 3 + Vercel 22). 카테고리 인덱스: [_sections.md](rules/_sections.md)
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | rule | [async-parallel](rules/async-parallel.md) | Promise.all 병렬 실행 (2-10x) |
+| CRITICAL | rule | [bundle-barrel-imports](rules/bundle-barrel-imports.md) | barrel import 피하기 |
+| HIGH | rule | [component-conventions](rules/component-conventions.md) | 컴포넌트 구조, export, 크기 제한 |
+| HIGH | rule | [state-location](rules/state-location.md) | 상태 관리 선택 기준 |
+| HIGH | rule | [server-parallel-fetching](rules/server-parallel-fetching.md) | 서버 병렬 fetch |
+| HIGH | rule | [rerender-memo](rules/rerender-memo.md) | React.memo 최적화 |
+| MEDIUM | rule | [anti-patterns](rules/anti-patterns.md) | Props Drilling, useEffect 남용 |
+
+## Quick Rules
+
+### 컴포넌트
+- 함수형 컴포넌트 + Props interface
+- named export (`export function`, default export 금지)
+- 200줄 이하
+- forwardRef로 ref 전달 지원
+
+### 훅
+- 커스텀 훅으로 로직 분리 (`use` 접두사)
+- 의존성 배열 정확히 관리
+- 함수형 setState로 stale closure 방지
+- 조건문/반복문 안에서 훅 호출 금지
+- useEffect 남용 금지 (파생 상태는 useMemo)
+
+### 상태 관리
+- 서버 상태: React Query (TanStack Query)
+- 전역 UI 상태: Zustand
+- 로컬 상태: useState
+- 복잡한 로직: useReducer
+- 비싼 초기값: lazy init (`useState(() => ...)`)
+- Props drilling 3단계 이상 → Context 또는 Zustand
+
+### 성능 (vercel-react-best-practices 참조)
+- 리스트에 고유 key (index 금지)
+- Promise.all로 병렬 fetch
+- barrel import 피하기 (직접 import)
+- dynamic import로 무거운 컴포넌트 분리
+- content-visibility로 대량 리스트 최적화
+- toSorted()로 배열 불변성
+
+### 폼
+- React Hook Form + Zod (zodResolver)
+- onBlur 유효성 검사, submit 시 첫 에러 필드 포커스
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | 함수형 컴포넌트 + Props 타입 정의 |
+| CRITICAL | 커스텀 훅으로 로직 분리 |
+| CRITICAL | 서버 상태는 React Query |
+| CRITICAL | Error Boundary로 에러 격리 |
+| CRITICAL | Waterfall 제거 (Promise.all) |
+| CRITICAL | Barrel import 피하기 |
+| HIGH | 의존성 배열 정확히 관리 |
+| HIGH | 리스트에 고유 key (index 금지) |
+| HIGH | 폼은 React Hook Form + Zod |
+| HIGH | 함수형 setState 사용 |
+| HIGH | Dynamic import 분리 |
+| MEDIUM | 대량 리스트 가상화 / content-visibility |
+| MEDIUM | 불필요한 useEffect 제거 |
+| MEDIUM | RSC 경계에서 필요한 데이터만 전달 |