timsquad 2.1.0 → 3.4.0

package/templates/base/skills/backend/node/rules/env-config.md

@@ -0,0 +1,41 @@
+---
+title: Environment Config
+impact: HIGH
+tags: config, zod, env
+---
+
+## Environment Config (Zod Validation)
+
+앱 시작 시 환경변수를 Zod로 검증. 잘못된 설정이면 즉시 종료.
+
+```typescript
+// src/config/index.ts
+import { z } from 'zod';
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.coerce.number().default(3000),
+  HOST: z.string().default('0.0.0.0'),
+
+  DATABASE_URL: z.string().url(),
+
+  JWT_SECRET: z.string().min(32, 'JWT_SECRET must be at least 32 characters'),
+  JWT_REFRESH_SECRET: z.string().min(32),
+
+  REDIS_URL: z.string().url().optional(),
+  SENTRY_DSN: z.string().url().optional(),
+
+  ENABLE_SWAGGER: z.coerce.boolean().default(false),
+});
+
+const parseResult = envSchema.safeParse(process.env);
+
+if (!parseResult.success) {
+  console.error('Invalid environment variables:', parseResult.error.format());
+  process.exit(1);
+}
+
+export const config = parseResult.data;
+// config.PORT → number (타입 안전)
+// config.REDIS_URL → string | undefined
+```

package/templates/base/skills/backend/node/rules/error-handling.md

@@ -0,0 +1,83 @@
+---
+title: Error Handling
+impact: CRITICAL
+tags: error, handler, AppError
+---
+
+## Error Handling
+
+### Custom Error Hierarchy
+
+```typescript
+// src/shared/errors/base-error.ts
+export class AppError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly statusCode: number = 500,
+    public readonly details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'AppError';
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      ...(this.details && { details: this.details }),
+    };
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource: string, id?: string) {
+    super(`${resource.toUpperCase()}_NOT_FOUND`, id ? `${resource} with id ${id} not found` : `${resource} not found`, 404);
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super('VALIDATION_ERROR', message, 400, details);
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = 'Unauthorized') { super('UNAUTHORIZED', message, 401); }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(message = 'Forbidden') { super('FORBIDDEN', message, 403); }
+}
+```
+
+### Global Error Handler
+
+```typescript
+// src/interface/middleware/error-handler.ts
+export function errorHandler(err: Error, c: Context) {
+  console.error('[Error]', { name: err.name, message: err.message,
+    stack: process.env.NODE_ENV === 'development' ? err.stack : undefined });
+
+  if (err instanceof AppError) {
+    return c.json({ success: false, error: err.toJSON() }, err.statusCode as any);
+  }
+  if (err instanceof HTTPException) {
+    return c.json({ success: false, error: { code: 'HTTP_ERROR', message: err.message } }, err.status);
+  }
+  if (err instanceof ZodError) {
+    return c.json({ success: false, error: { code: 'VALIDATION_ERROR', message: 'Request validation failed',
+      details: err.errors.map(e => ({ path: e.path.join('.'), message: e.message })) } }, 400);
+  }
+  // Prisma P2002 (duplicate) → 409, P2025 (not found) → 404
+  if (err.name === 'PrismaClientKnownRequestError') {
+    const p = err as any;
+    if (p.code === 'P2002') return c.json({ success: false, error: { code: 'DUPLICATE_ENTRY', message: 'Resource already exists' } }, 409);
+    if (p.code === 'P2025') return c.json({ success: false, error: { code: 'NOT_FOUND', message: 'Resource not found' } }, 404);
+  }
+
+  return c.json({ success: false, error: { code: 'INTERNAL_ERROR',
+    message: process.env.NODE_ENV === 'production' ? 'Internal server error' : err.message } }, 500);
+}
+```

package/templates/base/skills/backend/node/rules/hono-app-setup.md

@@ -0,0 +1,98 @@
+---
+title: Hono App Setup
+impact: CRITICAL
+tags: hono, setup, routes, zod
+---
+
+## Hono App Setup
+
+### App Configuration
+
+```typescript
+// src/app.ts
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { logger } from 'hono/logger';
+import { secureHeaders } from 'hono/secure-headers';
+import { timing } from 'hono/timing';
+import { userRoutes } from './interface/routes/user.routes';
+import { errorHandler } from './interface/middleware/error-handler';
+
+const app = new Hono();
+
+// 글로벌 미들웨어
+app.use('*', logger());
+app.use('*', timing());
+app.use('*', secureHeaders());
+app.use('*', cors({
+  origin: ['http://localhost:3000', 'https://example.com'],
+  allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
+  allowHeaders: ['Content-Type', 'Authorization'],
+  credentials: true,
+}));
+
+// 헬스 체크
+app.get('/health', (c) => c.json({ status: 'ok', timestamp: new Date().toISOString() }));
+
+// 라우트 마운트
+app.route('/api/v1/users', userRoutes);
+
+// 에러 핸들러
+app.onError(errorHandler);
+
+// 404
+app.notFound((c) => {
+  return c.json({ success: false, error: { code: 'NOT_FOUND', message: 'Route not found' } }, 404);
+});
+
+export default app;
+```
+
+### Typed Routes with zValidator
+
+```typescript
+// src/interface/routes/user.routes.ts
+import { Hono } from 'hono';
+import { zValidator } from '@hono/zod-validator';
+
+type Variables = { userId: string };
+const userRoutes = new Hono<{ Variables: Variables }>();
+
+userRoutes.use('*', authMiddleware);
+
+// 일관된 응답 형식: { success, data, error, pagination }
+userRoutes.get('/', async (c) => {
+  const page = Number(c.req.query('page') || '1');
+  const limit = Number(c.req.query('limit') || '10');
+  const result = await UserService.findAll({ page, limit });
+
+  return c.json({
+    success: true,
+    data: result.users,
+    pagination: { page, limit, total: result.total, totalPages: Math.ceil(result.total / limit) },
+  });
+});
+
+userRoutes.post('/', zValidator('json', createUserSchema), async (c) => {
+  const data = c.req.valid('json');
+  const user = await UserService.create(data);
+  return c.json({ success: true, data: user }, 201);
+});
+```
+
+### Zod Validation Schemas
+
+```typescript
+// src/interface/validators/user.validator.ts
+import { z } from 'zod';
+
+export const createUserSchema = z.object({
+  email: z.string().email('올바른 이메일 형식이 아닙니다'),
+  name: z.string().min(2).max(50),
+  password: z.string().min(8).regex(/[A-Z]/, '대문자 필요').regex(/[0-9]/, '숫자 필요'),
+  role: z.enum(['USER', 'ADMIN']).default('USER'),
+});
+
+export const updateUserSchema = createUserSchema.partial().omit({ password: true });
+export type CreateUserDto = z.infer<typeof createUserSchema>;
+```

package/templates/base/skills/backend/node/rules/jwt-auth.md

@@ -0,0 +1,76 @@
+---
+title: JWT Authentication
+impact: HIGH
+tags: jwt, auth, rbac, cookie
+---
+
+## JWT Authentication
+
+### Middleware + RBAC
+
+```typescript
+// src/interface/middleware/auth.ts
+import { jwt } from 'hono/jwt';
+import { HTTPException } from 'hono/http-exception';
+
+interface JWTPayload {
+  sub: string; email: string; role: 'USER' | 'ADMIN'; iat: number; exp: number;
+}
+
+export const authMiddleware = jwt({ secret: config.JWT_SECRET });
+
+export function requireRole(...roles: Array<'USER' | 'ADMIN'>) {
+  return async (c: Context, next: Next) => {
+    const payload = c.get('jwtPayload') as JWTPayload;
+    if (!payload || !roles.includes(payload.role)) {
+      throw new HTTPException(403, { message: 'Insufficient permissions' });
+    }
+    c.set('userId', payload.sub);
+    await next();
+  };
+}
+```
+
+### Token Generation
+
+```typescript
+import { sign } from 'hono/jwt';
+
+export async function generateTokens(user: { id: string; email: string; role: string }) {
+  const now = Math.floor(Date.now() / 1000);
+  const accessToken = await sign(
+    { sub: user.id, email: user.email, role: user.role, iat: now, exp: now + 60 * 15 }, // 15min
+    config.JWT_SECRET
+  );
+  const refreshToken = await sign(
+    { sub: user.id, type: 'refresh', iat: now, exp: now + 60 * 60 * 24 * 7 }, // 7days
+    config.JWT_REFRESH_SECRET
+  );
+  return { accessToken, refreshToken };
+}
+```
+
+### Login/Refresh Flow
+
+```typescript
+// Refresh Token은 HttpOnly 쿠키로 관리
+authRoutes.post('/login', zValidator('json', loginSchema), async (c) => {
+  const { email, password } = c.req.valid('json');
+  const user = await UserService.verifyCredentials(email, password);
+  if (!user) throw new AppError('AUTH_001', 'Invalid credentials', 401);
+
+  const { accessToken, refreshToken } = await generateTokens(user);
+
+  setCookie(c, 'refreshToken', refreshToken, {
+    httpOnly: true, secure: process.env.NODE_ENV === 'production',
+    sameSite: 'Strict', maxAge: 60 * 60 * 24 * 7, path: '/api/v1/auth',
+  });
+
+  return c.json({ success: true, data: { accessToken, user: { id: user.id, email: user.email, name: user.name } } });
+});
+
+authRoutes.post('/logout', (c) => {
+  deleteCookie(c, 'refreshToken', { path: '/api/v1/auth' });
+  return c.json({ success: true, message: 'Logged out' });
+});
+```

package/templates/base/skills/backend/node/rules/middleware.md

@@ -0,0 +1,56 @@
+---
+title: Middleware Patterns
+impact: MEDIUM
+tags: middleware, rate-limit, logging
+---
+
+## Middleware Patterns
+
+### Rate Limiting
+
+```typescript
+// src/interface/middleware/rate-limit.ts
+import { rateLimiter } from 'hono-rate-limiter';
+
+// 일반 API (분당 100회)
+export const apiRateLimiter = rateLimiter({
+  windowMs: 60 * 1000,
+  limit: 100,
+  standardHeaders: 'draft-6',
+  keyGenerator: (c) => c.req.header('x-forwarded-for') || 'unknown',
+  message: { success: false, error: { code: 'RATE_LIMIT', message: 'Too many requests' } },
+});
+
+// 인증 (분당 5회)
+export const authRateLimiter = rateLimiter({
+  windowMs: 60 * 1000,
+  limit: 5,
+  keyGenerator: (c) => `auth:${c.req.header('x-forwarded-for') || 'unknown'}`,
+  message: { success: false, error: { code: 'AUTH_RATE_LIMIT', message: 'Too many login attempts' } },
+});
+```
+
+### Request Logging (Structured)
+
+```typescript
+// src/interface/middleware/logger.ts
+export async function requestLogger(c: Context, next: Next) {
+  const start = Date.now();
+  const requestId = crypto.randomUUID();
+
+  c.set('requestId', requestId);
+  c.header('X-Request-ID', requestId);
+
+  console.log(JSON.stringify({
+    type: 'request', requestId,
+    method: c.req.method, path: c.req.path, ip: c.req.header('x-forwarded-for') || 'unknown',
+  }));
+
+  await next();
+
+  console.log(JSON.stringify({
+    type: 'response', requestId,
+    method: c.req.method, path: c.req.path, status: c.res.status, duration: Date.now() - start,
+  }));
+}
+```

package/templates/base/skills/backend/node/rules/testing.md

@@ -0,0 +1,82 @@
+---
+title: Testing Patterns
+impact: MEDIUM
+tags: testing, vitest, hono
+---
+
+## Testing Patterns
+
+### Hono API Test (app.request)
+
+```typescript
+// src/interface/routes/user.routes.test.ts
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import app from '../../app';
+
+describe('User Routes', () => {
+  describe('GET /api/v1/users/:id', () => {
+    it('사용자를 조회한다', async () => {
+      const res = await app.request('/api/v1/users/user-123', {
+        method: 'GET',
+        headers: { Authorization: 'Bearer valid-token' },
+      });
+
+      expect(res.status).toBe(200);
+      const json = await res.json();
+      expect(json.success).toBe(true);
+      expect(json.data).toHaveProperty('id', 'user-123');
+    });
+
+    it('존재하지 않는 사용자는 404', async () => {
+      const res = await app.request('/api/v1/users/not-exist', {
+        method: 'GET',
+        headers: { Authorization: 'Bearer valid-token' },
+      });
+
+      expect(res.status).toBe(404);
+      expect((await res.json()).error.code).toBe('USER_NOT_FOUND');
+    });
+  });
+
+  describe('POST /api/v1/users', () => {
+    it('유효하지 않은 이메일은 400', async () => {
+      const res = await app.request('/api/v1/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: 'Bearer valid-token' },
+        body: JSON.stringify({ email: 'invalid', name: 'Test', password: 'Password123' }),
+      });
+
+      expect(res.status).toBe(400);
+      expect((await res.json()).error.code).toBe('VALIDATION_ERROR');
+    });
+  });
+});
+```
+
+### Service Unit Test (Mock Repository)
+
+```typescript
+// src/domain/user/service.test.ts
+const mockRepository: UserRepository = {
+  findById: vi.fn(), findByEmail: vi.fn(), create: vi.fn(), update: vi.fn(), delete: vi.fn(),
+};
+
+describe('UserService', () => {
+  let service: UserService;
+  beforeEach(() => { vi.clearAllMocks(); service = new UserService(mockRepository); });
+
+  it('존재하는 사용자를 반환', async () => {
+    const mockUser = { id: '1', email: 'test@example.com', name: 'Test' };
+    vi.mocked(mockRepository.findById).mockResolvedValue(mockUser);
+
+    const result = await service.findById('1');
+    expect(result).toEqual(mockUser);
+    expect(mockRepository.findById).toHaveBeenCalledWith('1');
+  });
+
+  it('존재하지 않으면 NotFoundError', async () => {
+    vi.mocked(mockRepository.findById).mockResolvedValue(null);
+    await expect(service.findById('x')).rejects.toThrow(NotFoundError);
+  });
+});
+```

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

@@ -0,0 +1,47 @@
+---
+name: coding
+description: 코드 작성 규칙 및 패턴 가이드라인
+version: "1.0.0"
+tags: [coding, conventions, naming]
+user-invocable: false
+---
+
+# Coding Guidelines
+
+## 네이밍 규칙
+
+| 대상 | 규칙 | 예시 |
+|------|------|------|
+| 클래스 | PascalCase | `UserService`, `OrderRepository` |
+| 함수/메서드 | camelCase | `getUserById`, `calculateTotal` |
+| 변수 | camelCase | `userName`, `totalAmount` |
+| 상수 | UPPER_SNAKE | `MAX_RETRY_COUNT`, `API_BASE_URL` |
+| 파일 | kebab-case | `user-service.ts`, `order-repository.ts` |
+
+## 함수 원칙
+- **단일 책임**: 함수는 한 가지 일만 수행
+- **명확한 이름**: 함수 이름만으로 동작 파악 가능
+- **적절한 크기**: 20줄 이내 권장
+
+## Rules
+
+### 필수
+- 함수가 단일 책임을 가지는가
+- 네이밍이 명확하고 일관적인가
+- 에러가 명시적으로 처리되는가
+
+### 금지
+- `any` 타입 사용
+- 매직 넘버/문자열 사용
+- `console.log` 사용 (logger 사용)
+
+## Checklist
+- [ ] 함수가 단일 책임
+- [ ] 네이밍이 명확하고 일관적
+- [ ] 에러가 명시적으로 처리됨
+- [ ] any 타입 없음
+- [ ] 매직 넘버/문자열 없음
+- [ ] console.log 없음
+
+## 참조
+- `rules/patterns.md` — Error Handling, Repository, DTO/Entity, 의존성 주입, Anti-Patterns

package/templates/base/skills/coding/rules/patterns.md

@@ -0,0 +1,81 @@
+---
+title: Coding Patterns & Anti-Patterns
+impact: HIGH
+tags: coding, patterns, error-handling
+---
+
+# Coding Patterns & Anti-Patterns
+
+## Error Handling
+
+```typescript
+// Good: 명시적 에러 처리
+async function getUser(id: string): Promise<User> {
+  const user = await userRepository.findById(id);
+  if (!user) throw new NotFoundError('USER_NOT_FOUND', `User ${id} not found`);
+  return user;
+}
+
+// Bad: 에러 무시
+async function getUser(id: string): Promise<User | null> {
+  try { return await userRepository.findById(id); }
+  catch { return null; } // 에러 원인 알 수 없음
+}
+```
+
+## Repository Pattern
+
+```typescript
+interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  findByEmail(email: string): Promise<User | null>;
+  save(user: User): Promise<User>;
+  delete(id: string): Promise<void>;
+}
+
+class PostgresUserRepository implements UserRepository {
+  async findById(id: string): Promise<User | null> { /* PostgreSQL 구현 */ }
+}
+```
+
+## DTO/Entity 분리
+
+```typescript
+// Entity (도메인)
+class User {
+  constructor(
+    public readonly id: string,
+    public email: string,
+    public passwordHash: string, // 민감 정보
+  ) {}
+}
+
+// DTO (외부 노출)
+interface UserResponseDto {
+  id: string;
+  email: string;
+  // passwordHash 제외
+}
+```
+
+## 의존성 주입
+
+```typescript
+// Good
+class UserService {
+  constructor(private userRepository: UserRepository) {}
+}
+
+// Bad
+class UserService {
+  private userRepository = new PostgresUserRepository(); // 하드코딩
+}
+```
+
+## Anti-Patterns
+
+| 이름 | Bad | Good |
+|------|-----|------|
+| any 타입 | `function process(data: any)` | `function process<T>(data: T)` |
+| 매직 넘버 | `if (status === 1)` | `if (status === Status.ACTIVE)` |
+| 콘솔 로그 | `console.log('user:', user)` | `logger.debug('User fetched', { userId })` |

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

@@ -0,0 +1,111 @@
+---
+name: controller
+description: |
+  Context DI 컨테이너. 서브에이전트 위임 시 compiled spec을 의존성으로 주입.
+  서브에이전트 호출, Task() 위임, 에이전트 실행 시 자동 트리거.
+  Use when: "구현해줘", "테스트해줘", "리뷰해줘", "설계해줘", 서브에이전트 위임
+version: "1.0.0"
+tags: [controller, di, context-injection]
+user-invocable: false
+---
+
+# Controller (Context DI Container)
+
+서브에이전트에게 작업을 위임할 때 필요한 컨텍스트를 자동으로 해석하고 주입하는 컨테이너.
+에이전트가 "스스로 찾아 읽기"가 아닌 "주입받아 바로 시작"하도록 보장.
+
+## Delegation Process
+
+서브에이전트 위임 시 반드시 이 순서를 따른다:
+
+1. **에이전트 파일 확인**: `.claude/agents/{agent}.md` 읽기
+2. **Prerequisites 파싱**: `<prerequisites>` 태그에서 필요 SSOT 목록 추출
+3. **Spec Resolve**: `controller/references/`에서 해당 compiled spec 로드
+4. **Phase 제약 로드**: `controller/rules/`에서 현재 phase 제약 확인
+5. **Stale 체크**: `.compile-manifest.json`의 hash와 현재 SSOT hash 비교
+6. **프롬프트 조합**: tsq-protocol + resolved specs + phase 제약 + 태스크 지시
+7. **Task() 호출**: 조합된 프롬프트로 서브에이전트 실행
+
+## Spec Resolution
+
+```
+에이전트 prerequisites         →  controller references/
+─────────────────────────────────────────────────────────
+service-spec.md               →  references/*.spec.md (endpoint별)
+data-design.md                →  references/*.spec.md (entity별)
+error-codes.md                →  references/error-codes.spec.md
+```
+
+필요한 spec 전체가 아닌 **태스크에 관련된 섹션만** 주입한다.
+예: "로그인 API 구현" → `references/2-1-로그인.spec.md`만 주입.
+
+## Stale Detection
+
+Spec 주입 전 `.compile-manifest.json`을 확인한다:
+
+- hash 일치 → 최신. 주입 진행.
+- hash 불일치 → 사용자에게 `tsq compile` 재실행을 제안.
+- manifest 없음 → 사용자에게 `tsq compile` 최초 실행을 안내.
+
+## Task Prompt Template
+
+```
+[MODE: {phase}] [TASK: {task_id}] [SPEC: {primary_spec}]
+
+[tsq-protocol 기본 규칙]
+
+[현재 Phase 제약]
+- 허용: {allowed_actions}
+- 금지: {forbidden_actions}
+
+[Compiled Spec]
+{injected_spec_content}
+
+[태스크 지시]
+task_id: {task_id}
+description: {description}
+```
+
+## Mode Declaration
+
+서브에이전트는 **매 응답 첫 줄**에 모드 선언을 출력해야 한다:
+
+```
+[MODE: IMPLEMENTATION] [TASK: P3-S001-T001] [SPEC: 2-1-로그인.spec.md]
+```
+
+<mode-declaration>
+  <rules>
+    <must>응답 시작 시 [MODE: {phase}] [TASK: {task_id}] [SPEC: {spec}] 선언</must>
+    <must>phase는 current-phase.json 기준 (planning/design/implementation/review)</must>
+    <must>SPEC은 주입받은 primary spec 파일명</must>
+  </rules>
+  <rationale>
+    컨텍스트 압축(compaction) 후에도 에이전트가 자신의 역할·제약·참조 spec을
+    매 응답마다 재확인한다. Rationalization Prevention의 자연스러운 확장.
+  </rationale>
+</mode-declaration>
+
+## Rationalization Prevention
+
+<rationalization-prevention>
+
+| 에이전트의 변명 | 현실 |
+|----------------|------|
+| "이 태스크는 간단해서 spec 없이 가능" | 간단함은 주관적. spec이 있으면 반드시 참조 |
+| "spec이 오래된 것 같아서 직접 판단" | spec 신선도는 controller가 판단. 주입받은 spec을 따를 것 |
+| "이미 비슷한 코드가 있으니 참고만 하면 됨" | 기존 코드가 spec과 일치하는지 알 수 없음. spec 기준 |
+| "테스트는 나중에 한번에 돌리는 게 효율적" | 각 태스크 완료 시 테스트 통과가 완료 조건 |
+| "사용자가 빨리 해달라고 했으니 절차 생략" | 절차는 품질 보장. 절차를 따르는 것이 결과적으로 빠름 |
+
+</rationalization-prevention>
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | 서브에이전트 위임 전 spec resolve 완료 |
+| CRITICAL | compiled spec의 stale 여부 확인 |
+| HIGH | phase 제약이 프롬프트에 포함됨 |
+| HIGH | tsq-protocol이 프롬프트에 포함됨 |
+| MEDIUM | 태스크에 관련된 섹션만 선별 주입 (전체 주입 지양) |