timsquad 2.1.0 → 3.4.0

package/templates/base/skills/methodology/bdd/rules/gherkin-patterns.md

@@ -0,0 +1,113 @@
+---
+title: BDD Gherkin & Implementation Patterns
+impact: HIGH
+tags: bdd, gherkin, testing
+---
+
+# BDD Gherkin & Implementation Patterns
+
+## Feature File 예시
+
+```gherkin
+Feature: 사용자 로그인
+  사용자가 이메일과 비밀번호로 로그인할 수 있다
+
+  Background:
+    Given 회원가입된 사용자가 존재한다
+      | email           | password  |
+      | user@test.com   | password1 |
+
+  Scenario: 올바른 자격 증명으로 로그인 성공
+    Given 로그인 페이지에 접속한다
+    When 이메일 "user@test.com"을 입력한다
+    And 비밀번호 "password1"을 입력한다
+    And 로그인 버튼을 클릭한다
+    Then 대시보드 페이지로 이동한다
+    And "로그인 성공" 메시지가 표시된다
+
+  Scenario: 잘못된 비밀번호로 로그인 실패
+    Given 로그인 페이지에 접속한다
+    When 이메일 "user@test.com"을 입력한다
+    And 비밀번호 "wrongpassword"를 입력한다
+    And 로그인 버튼을 클릭한다
+    Then 로그인 페이지에 머무른다
+    And "이메일 또는 비밀번호가 올바르지 않습니다" 에러가 표시된다
+
+  Scenario Outline: 다양한 잘못된 입력
+    When 이메일 "<email>"을 입력한다
+    And 비밀번호 "<password>"를 입력한다
+    And 로그인 버튼을 클릭한다
+    Then "<error>" 에러가 표시된다
+
+    Examples:
+      | email          | password | error                    |
+      |                | pass     | 이메일을 입력해주세요      |
+      | invalid-email  | pass     | 올바른 이메일 형식이 아닙니다 |
+```
+
+## Step Definitions (Playwright + Cucumber)
+
+```typescript
+import { Given, When, Then } from '@cucumber/cucumber';
+import { expect } from '@playwright/test';
+
+Given('로그인 페이지에 접속한다', async function() {
+  await this.page.goto('/login');
+});
+
+When('이메일 {string}을 입력한다', async function(email: string) {
+  await this.page.fill('[data-testid="email-input"]', email);
+});
+
+When('로그인 버튼을 클릭한다', async function() {
+  await this.page.click('[data-testid="login-button"]');
+});
+
+Then('대시보드 페이지로 이동한다', async function() {
+  await expect(this.page).toHaveURL('/dashboard');
+});
+
+Then('{string} 메시지가 표시된다', async function(message: string) {
+  await expect(this.page.locator('[data-testid="toast"]')).toContainText(message);
+});
+```
+
+## API BDD (Vitest + SuperTest)
+
+```typescript
+describe('Feature: 사용자 등록 API', () => {
+  describe('Scenario: 유효한 정보로 회원가입', () => {
+    it('Given 유효한 사용자 정보가 있다', () => {
+      ctx.userData = { email: 'new@test.com', password: 'SecurePass123!', name: '홍길동' };
+    });
+    it('When POST /api/users 요청을 보낸다', async () => {
+      ctx.response = await request(app).post('/api/users').send(ctx.userData);
+    });
+    it('Then 201 상태 코드를 반환한다', () => {
+      expect(ctx.response.status).toBe(201);
+    });
+    it('And 생성된 사용자 ID를 반환한다', () => {
+      expect(ctx.response.body.data.id).toBeDefined();
+    });
+  });
+});
+```
+
+## 디렉토리 구조
+
+```
+features/                  # Gherkin feature 파일
+├── auth/login.feature
+├── order/checkout.feature
+step-definitions/          # 스텝 구현
+├── auth.steps.ts
+├── common.steps.ts
+support/                   # 헬퍼, 훅
+├── world.ts               # 테스트 컨텍스트
+├── hooks.ts               # Before, After 훅
+```
+
+## 도구
+- `cucumber-js`: JS/TS Cucumber 구현
+- `playwright`: E2E 테스트 러너
+- `jest-cucumber`: Jest와 Cucumber 통합

package/templates/base/skills/methodology/ddd/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: ddd
+description: Domain-Driven Design 전략적 설계 가이드라인
+version: "1.0.0"
+tags: [ddd, methodology, architecture]
+user-invocable: false
+compatible-with: [tdd, bdd]
+---
+
+# DDD (Domain-Driven Design) — Strategic
+
+## 철학
+- 도메인 전문가와 개발자의 협업
+- 유비쿼터스 언어 (Ubiquitous Language)
+- 모델 주도 설계 (Model-Driven Design)
+- 경계 컨텍스트로 복잡성 분리
+
+## 전략적 vs 전술적
+
+| 레벨 | 내용 | 위치 |
+|------|------|------|
+| 전략적 | Bounded Context, Ubiquitous Language, Context Map, Subdomain | 이 스킬 |
+| 전술적 | Aggregate, Entity, Value Object, Repository, Domain Event | architectures/ |
+
+## 핵심 개념
+
+### Ubiquitous Language
+도메인 전문가와 개발자가 공유하는 공통 언어.
+코드, 문서, 대화 모두에서 동일한 용어 사용.
+
+```typescript
+// Bad: 개발자 용어
+class DataProcessor { processRecord(record: Record) { ... } }
+
+// Good: 유비쿼터스 언어
+class OrderFulfillment { shipOrder(order: Order) { ... } }
+```
+
+### Bounded Context
+특정 도메인 모델이 적용되는 명시적 경계.
+같은 "Product"도 Catalog(정보), Inventory(재고), Pricing(가격)에서 다른 의미.
+
+### Subdomain
+- **Core**: 비즈니스 핵심 차별화 → 최고 인력, 자체 개발
+- **Supporting**: Core 지원, 차별화 아님 → 적당한 품질
+- **Generic**: 모든 비즈니스에 공통 → 구매/오픈소스
+
+### Context Map
+Bounded Context 간 관계: Partnership, Shared Kernel, Customer-Supplier, Conformist, ACL, Open Host Service
+
+## Rules
+
+### 필수
+- 용어 사전 (Glossary) 작성 및 유지
+- 코드에서 유비쿼터스 언어 사용
+- Bounded Context 경계 명확히 정의
+- 컨텍스트 간 통신은 명시적 인터페이스로
+- 외부 시스템 연동 시 ACL 사용
+
+### 금지
+- Bounded Context 간 도메인 모델 직접 공유
+- 하나의 Aggregate가 여러 Context에 걸침
+- 기술 용어를 도메인 모델에 사용
+
+## Checklist
+- [ ] 용어 사전 존재 및 최신화
+- [ ] Bounded Context 경계 정의됨
+- [ ] 코드가 유비쿼터스 언어 사용
+- [ ] Context Map 문서화
+- [ ] 외부 연동에 ACL 적용
+- [ ] Subdomain 분류 (Core/Supporting/Generic)
+
+## 참조
+- `rules/strategic-patterns.md` — Context Map, ACL 예시, Event Storming, 디렉토리 구조

package/templates/base/skills/methodology/ddd/rules/strategic-patterns.md

@@ -0,0 +1,98 @@
+---
+title: DDD Strategic Patterns
+impact: HIGH
+tags: ddd, architecture, domain-modeling
+---
+
+# DDD Strategic Patterns
+
+## Bounded Context
+특정 도메인 모델이 적용되는 명시적 경계.
+같은 용어도 컨텍스트마다 다른 의미를 가질 수 있음.
+
+### "Product"의 다른 의미
+- **Catalog**: 상품 정보, 설명, 이미지
+- **Inventory**: 재고 수량, 위치, SKU
+- **Pricing**: 가격, 할인, 프로모션
+- **Shipping**: 무게, 크기, 배송 제한
+
+### 가이드라인
+- 하나의 Bounded Context = 하나의 팀
+- 하나의 Bounded Context = 하나의 코드베이스 (또는 모듈)
+- 컨텍스트 간 통신은 명시적 인터페이스로
+
+## Subdomain 유형
+
+| 유형 | 설명 | 전략 | 예시 |
+|------|------|------|------|
+| Core | 비즈니스 핵심 차별화 | 최고 인력, 자체 개발 | 쿠팡 로켓배송 |
+| Supporting | Core 지원, 차별화 아님 | 아웃소싱/적당한 품질 | 내부 관리 시스템 |
+| Generic | 모든 비즈니스에 공통 | 구매/오픈소스 | 결제, 인증, 이메일 |
+
+## Context Map Relationships
+
+| 관계 | 설명 | 다이어그램 |
+|------|------|-----------|
+| Partnership | 긴밀한 협력, 함께 성공/실패 | [A] ←Partnership→ [B] |
+| Shared Kernel | 공유 모델, 양쪽 합의 필요 (최소화) | [A] ←Shared Kernel→ [B] |
+| Customer-Supplier | 공급자가 고객 요구 수용 | [Supplier] → [Customer] |
+| Conformist | Downstream이 Upstream 모델 수용 | [Upstream] → [Downstream] |
+| ACL | 번역 레이어로 외부 모델로부터 보호 | [External] →ACL→ [Ours] |
+| Open Host Service | 잘 정의된 프로토콜로 서비스 제공 | [Context] →OHS→ [Consumers] |
+
+## Anti-Corruption Layer 예시 (Stripe 결제)
+
+```typescript
+// 외부 모델 (Stripe)
+interface StripePaymentIntent {
+  id: string;
+  amount: number;           // cents
+  status: 'succeeded' | 'pending' | 'failed';
+}
+
+// 우리 도메인 모델
+interface Payment {
+  id: PaymentId;
+  amount: Money;            // 우리의 Money Value Object
+  status: PaymentStatus;
+}
+
+// ACL
+class StripePaymentAdapter implements PaymentGateway {
+  async processPayment(payment: Payment): Promise<PaymentResult> {
+    const intent = await this.stripe.paymentIntents.create({
+      amount: payment.amount.toCents(),
+      currency: payment.amount.currency.toLowerCase(),
+    });
+    return this.toPaymentResult(intent);
+  }
+
+  private mapStatus(stripeStatus: string): PaymentStatus {
+    const mapping: Record<string, PaymentStatus> = {
+      'succeeded': PaymentStatus.COMPLETED,
+      'pending': PaymentStatus.PROCESSING,
+      'failed': PaymentStatus.FAILED,
+    };
+    return mapping[stripeStatus] ?? PaymentStatus.UNKNOWN;
+  }
+}
+```
+
+## Event Storming
+1. Domain Events 도출 (주황색)
+2. Commands 식별 (파란색)
+3. Aggregates 그룹핑 (노란색)
+4. Bounded Context 경계 그리기
+5. Context Map 작성
+
+## 디렉토리 구조 (모노레포)
+
+```
+packages/
+├── catalog/         # Catalog Context
+│   └── src/domain/ + application/ + infrastructure/
+├── order/           # Order Context
+├── inventory/       # Inventory Context
+└── shared/          # Shared Kernel (최소화)
+    └── src/value-objects/ + events/
+```

package/templates/base/skills/methodology/debugging/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: debugging
+description: |
+  체계적 디버깅 방법론.
+  근본 원인 추적, defense-in-depth, 가설-실험 루프, 로그 기반 진단.
+  Use when: "버그 수정, 디버깅, 에러 추적, 원인 분석, 트러블슈팅"
+version: "1.0.0"
+tags: [debugging, troubleshooting, methodology]
+user-invocable: false
+---
+
+# Systematic Debugging
+
+체계적 디버깅을 통해 근본 원인(root cause)을 빠르게 찾고 재발을 방지하는 방법론.
+
+## Philosophy
+
+- 증상이 아닌 근본 원인을 찾는다
+- 가설을 세우고 실험으로 검증한다 (추측으로 코드를 수정하지 않는다)
+- Defense in depth — 같은 유형의 버그가 재발하지 않도록 방어 계층을 추가한다
+
+## Resources
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| HIGH | ref | [root-cause-tracing](references/root-cause-tracing.md) | 5 Whys + 가설-실험 루프 상세 가이드 |
+
+## Quick Rules
+
+### Debugging Loop
+1. **Reproduce** — 버그를 100% 재현하는 최소 조건 확보
+2. **Hypothesize** — 원인 가설을 1~3개 세우고 가능성 순으로 정렬
+3. **Test** — 각 가설을 실험으로 검증 (로그 추가, breakpoint, 입력 변경)
+4. **Fix** — 근본 원인 수정 (증상 대응 X)
+5. **Verify** — 원래 재현 조건에서 버그 사라짐 확인
+6. **Prevent** — 회귀 테스트 추가, 방어 로직 보강
+
+### Root Cause Categories
+| 카테고리 | 예시 |
+|---------|------|
+| State | 예기치 않은 상태 변이, race condition |
+| Data | 잘못된 입력, null/undefined, 타입 불일치 |
+| Logic | 잘못된 조건, off-by-one, 순서 오류 |
+| Environment | 설정 차이, 의존성 버전, OS 차이 |
+| Integration | API 응답 변경, 타이밍, 네트워크 |
+
+### Anti-Patterns
+- **Shotgun debugging**: 여러 곳을 동시에 수정 → 원인 특정 불가
+- **Print-and-pray**: console.log만 추가하고 가설 없이 실행 반복
+- **Blame game**: "내 코드 문제 아닌데" → 증거 없이 외부 원인 지목
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | 재현 조건이 명확한가 |
+| CRITICAL | 가설을 세운 후 수정했는가 (추측 수정 X) |
+| HIGH | 근본 원인을 찾았는가 (증상 대응만 하지 않았는가) |
+| HIGH | 회귀 테스트를 추가했는가 |
+| MEDIUM | 같은 유형의 버그를 방지하는 방어 로직이 있는가 |

package/templates/base/skills/methodology/debugging/references/root-cause-tracing.md

@@ -0,0 +1,84 @@
+---
+title: Root Cause Tracing Guide
+category: guide
+source: internal
+---
+
+# Root Cause Tracing
+
+버그의 근본 원인을 체계적으로 추적하는 상세 가이드.
+
+## 5 Whys Technique
+
+증상에서 시작해 "왜?"를 반복하여 근본 원인에 도달:
+
+```
+증상: 사용자가 주문 시 500 에러 발생
+Why 1: 주문 API에서 NullPointerException
+Why 2: user.address가 null
+Why 3: 소셜 로그인 사용자는 주소 미입력
+Why 4: 주소 입력 폼이 소셜 로그인 플로우에 없음
+Why 5: 소셜 로그인 기능 추가 시 주소 수집 요구사항 누락
+→ 근본 원인: 요구사항 누락 (L2 피드백 대상)
+```
+
+## Hypothesis-Experiment Loop
+
+### Step 1: Gather Evidence
+```
+- 에러 메시지 정확히 기록
+- 스택 트레이스 분석
+- 최근 변경사항 (git log, git diff) 확인
+- 환경 차이 (dev vs prod) 확인
+```
+
+### Step 2: Form Hypotheses
+```
+가설 목록 (가능성 순):
+1. [HIGH] user.address null check 누락 — 소셜 로그인 플로우 확인
+2. [MEDIUM] DB migration 중 address 컬럼 누락 — 스키마 확인
+3. [LOW] 캐시에 오래된 사용자 데이터 — 캐시 무효화 확인
+```
+
+### Step 3: Test Each Hypothesis
+```
+가설 1 테스트:
+- 소셜 로그인으로 가입한 테스트 유저 생성
+- 주소 없이 주문 API 호출
+- 결과: NullPointerException 재현됨 → 가설 1 확인
+```
+
+### Step 4: Fix Root Cause
+```
+수정:
+1. 주문 API에 address null 검증 추가 (즉시 방어)
+2. 소셜 로그인 플로우에 주소 입력 단계 추가 (근본 원인)
+3. 기존 소셜 로그인 사용자에게 주소 입력 유도 (데이터 보완)
+```
+
+### Step 5: Prevent Recurrence
+```
+방지:
+1. 회귀 테스트: "주소 없는 사용자의 주문 시 적절한 에러 반환"
+2. 필수 필드 검증 체크리스트에 "address" 추가
+3. 새 로그인 방법 추가 시 "기존 필수 데이터 수집" 체크 항목 추가
+```
+
+## Common Pitfalls
+
+- 첫 번째 "왜?"에서 멈춤 → 최소 3번은 반복
+- 가설 없이 코드 수정 → 다른 곳이 깨질 위험
+- 증상만 수정 (null check만 추가하고 근본 원인 방치)
+- 재현 없이 수정 → 수정이 맞는지 검증 불가
+
+## Defense in Depth
+
+같은 유형의 버그가 다시 발생하지 않도록 여러 계층에서 방어:
+
+| 계층 | 방어 | 예시 |
+|------|------|------|
+| 입력 | Zod 스키마 검증 | `z.object({ address: z.string().min(1) })` |
+| 타입 | NonNullable, Required | `NonNullable<User['address']>` |
+| 런타임 | 조기 에러 반환 | `if (!user.address) throw new BadRequestError(...)` |
+| 테스트 | 회귀 테스트 | `it('should reject order without address')` |
+| 모니터링 | 에러 알림 | Sentry, error rate alert |

package/templates/base/skills/methodology/tdd/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: tdd
+description: Test-Driven Development 방법론 가이드라인
+version: "1.0.0"
+tags: [tdd, methodology, testing]
+user-invocable: false
+---
+
+# TDD (Test-Driven Development)
+
+## 철학
+- 테스트가 설계를 이끈다
+- 작은 단계로 진행한다
+- 리팩토링은 테스트가 보장한다
+- 불확실할 때는 더 작은 단계로
+
+## Red-Green-Refactor Cycle
+
+### 1. Red (1-2min) — 실패하는 테스트 작성
+- 테스트가 실패하는 것을 확인
+- 한 번에 하나의 기능만 테스트
+- 테스트 이름으로 의도 명확히 표현
+- **금지**: 구현 코드 먼저 작성
+
+### 2. Green (3-5min) — 테스트를 통과하는 최소 코드
+- 테스트 통과만을 목표
+- 가장 단순한 구현 선택
+- **금지**: 미래 요구사항 미리 구현, 완벽한 코드 추구
+
+### 3. Refactor (5-10min) — 코드 정리
+- 중복 제거, 네이밍 개선, 구조 개선
+- 테스트 실행하며 진행
+- **금지**: 기능 변경
+
+## Kent Beck Techniques (상세: `rules/techniques.md`)
+
+| 기법 | 사용 시점 |
+|------|----------|
+| Fake It | 구현 불확실 → 하드코딩 후 일반화 |
+| Triangulation | 일반화 방향 불명확 → 2+ 테스트 |
+| Obvious Implementation | 구현 명확 → 바로 작성 |
+| One to Many | 컬렉션 → 단일 먼저, 확장 |
+| Assert First | 구조 불명확 → assertion부터 역방향 |
+| Starter Test | 시작점 모름 → 가장 단순한 테스트 |
+| Test Data Builder | 객체 생성 반복 → 빌더 패턴 |
+| Learning Test | 새 라이브러리 → 학습 테스트 |
+
+## SSOT 통합 워크플로우
+1. `service-spec.md`에서 API 명세 확인
+2. 명세 기반 테스트 케이스 작성 (Starter Test)
+3. 테스트 실패 확인 (Red)
+4. 명세대로 구현 (Green)
+5. 리팩토링 (Refactor)
+6. 삼각측량으로 엣지 케이스 추가
+
+## Checklist
+- [ ] 테스트 먼저 작성했는가
+- [ ] 테스트가 실패하는 것을 확인했는가
+- [ ] 최소 코드로 통과했는가
+- [ ] 리팩토링 단계를 거쳤는가
+- [ ] 삼각측량으로 일반화했는가
+- [ ] 엣지 케이스를 테스트했는가
+
+## 참조
+- `rules/techniques.md` — 각 기법의 코드 예시
+- `rules/real-world-example.md` — 로그인 기능 TDD 전체 과정 + Anti-Patterns

package/templates/base/skills/methodology/tdd/rules/real-world-example.md

@@ -0,0 +1,88 @@
+---
+title: TDD Real-World Example
+impact: HIGH
+tags: tdd, testing, best-practices
+---
+
+# TDD Real-World Example: 로그인 기능
+
+## 1단계: Starter Test
+```typescript
+it('should create auth service', () => {
+  const authService = new AuthService(mockUserRepo);
+  expect(authService).toBeDefined();
+});
+```
+
+## 2단계: Happy Path
+```typescript
+it('should return token for valid credentials', async () => {
+  // Given
+  const mockUser = new UserBuilder()
+    .withEmail('user@test.com')
+    .withPassword(await hash('password123'))
+    .build();
+  mockUserRepo.findByEmail.mockResolvedValue(mockUser);
+
+  // When
+  const result = await authService.login('user@test.com', 'password123');
+
+  // Then
+  expect(result.token).toBeDefined();
+  expect(result.user.email).toBe('user@test.com');
+});
+```
+
+## 3단계: Error Cases (삼각측량)
+```typescript
+it('should throw for non-existent user', async () => {
+  mockUserRepo.findByEmail.mockResolvedValue(null);
+  await expect(authService.login('nobody@test.com', 'password'))
+    .rejects.toThrow('INVALID_CREDENTIALS');
+});
+
+it('should throw for wrong password', async () => {
+  const mockUser = new UserBuilder().withPassword(await hash('correct-password')).build();
+  mockUserRepo.findByEmail.mockResolvedValue(mockUser);
+  await expect(authService.login('user@test.com', 'wrong-password'))
+    .rejects.toThrow('INVALID_CREDENTIALS');
+});
+```
+
+## 4단계: Edge Cases
+```typescript
+it('should throw for locked account', async () => {
+  const lockedUser = new UserBuilder().withStatus('locked').build();
+  mockUserRepo.findByEmail.mockResolvedValue(lockedUser);
+  await expect(authService.login('locked@test.com', 'password'))
+    .rejects.toThrow('ACCOUNT_LOCKED');
+});
+```
+
+## 5단계: 구현 (테스트가 이끈 설계)
+```typescript
+class AuthService {
+  constructor(private userRepo: UserRepository) {}
+
+  async login(email: string, password: string): Promise<LoginResult> {
+    const user = await this.userRepo.findByEmail(email);
+    if (!user) throw new AuthError('INVALID_CREDENTIALS');
+    if (user.status === 'locked') throw new AuthError('ACCOUNT_LOCKED');
+
+    const isValid = await compare(password, user.password);
+    if (!isValid) throw new AuthError('INVALID_CREDENTIALS');
+
+    const token = this.generateToken(user);
+    return { token, user: this.toUserDto(user) };
+  }
+}
+```
+
+## Anti-Patterns
+
+| 이름 | 문제 | 해결 |
+|------|------|------|
+| Test After | 테스트가 설계에 영향 못 줌 | 테스트 먼저, 실패 확인 후 구현 |
+| Too Big Step | 실패 원인 파악 어려움 | Starter Test로 시작, 점진적 확장 |
+| Test the Implementation | 리팩토링 시 테스트 깨짐 | 동작(behavior)을 테스트, public API만 |
+| Skipping Refactor | 기술 부채 누적 | 매 사이클마다 Refactor 필수 |