timsquad 2.1.0 → 3.4.0

package/templates/base/skills/methodology/tdd/rules/techniques.md

@@ -0,0 +1,185 @@
+---
+title: TDD Techniques
+impact: HIGH
+tags: tdd, testing, techniques
+---
+
+# TDD Techniques (Kent Beck)
+
+## Fake It ('Til You Make It)
+하드코딩으로 먼저 통과시킨 후, 점진적으로 일반화.
+구현 방법이 불확실할 때, 작은 단계로 진행하고 싶을 때 사용.
+
+```typescript
+// Step 1: 테스트 작성
+it('should add two numbers', () => {
+  expect(add(2, 3)).toBe(5);
+});
+
+// Step 2: Fake It - 하드코딩으로 통과
+function add(a: number, b: number): number {
+  return 5;  // ✅ 테스트 통과!
+}
+
+// Step 3: 테스트 추가로 일반화 강제
+it('should add different numbers', () => {
+  expect(add(1, 1)).toBe(2);
+});
+
+// Step 4: 이제 일반화 필요
+function add(a: number, b: number): number {
+  return a + b;
+}
+```
+
+## Triangulation
+2개 이상의 테스트로 일반화를 강제. 일반화 방향이 불명확할 때 사용.
+
+```typescript
+// Test 1: 기본 케이스
+it('should return 10% discount for $150', () => {
+  expect(calculateDiscount(150)).toBe(15);
+});
+
+// Test 2: 삼각측량 - 다른 값으로 일반화 강제
+it('should return 10% discount for $200', () => {
+  expect(calculateDiscount(200)).toBe(20);
+});
+
+// Test 3: 경계 조건 삼각측량
+it('should return 0 discount for $100 or less', () => {
+  expect(calculateDiscount(100)).toBe(0);
+});
+
+function calculateDiscount(total: number): number {
+  if (total <= 100) return 0;
+  return total * 0.1;
+}
+```
+
+## Obvious Implementation
+구현이 명확하면 바로 작성. 자신감이 떨어지면 Fake It으로 돌아가기.
+
+```typescript
+it('should return full name', () => {
+  const user = { firstName: 'John', lastName: 'Doe' };
+  expect(getFullName(user)).toBe('John Doe');
+});
+
+function getFullName(user: { firstName: string; lastName: string }): string {
+  return `${user.firstName} ${user.lastName}`;
+}
+```
+
+## One to Many
+먼저 단일 항목으로 구현, 그 다음 컬렉션으로 확장.
+
+```typescript
+// Step 1: 단일 항목
+it('should calculate total for one item', () => {
+  expect(calculateTotal([{ price: 100, quantity: 2 }])).toBe(200);
+});
+
+// Step 2: 여러 항목으로 확장
+it('should calculate total for multiple items', () => {
+  expect(calculateTotal([
+    { price: 100, quantity: 2 },
+    { price: 50, quantity: 1 },
+  ])).toBe(250);
+});
+
+function calculateTotal(items: Item[]): number {
+  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+}
+```
+
+## Assert First
+테스트 작성 시 assertion부터 시작, 역방향으로 구성.
+
+```typescript
+// Step 1: Assertion 먼저 → Step 2: 함수 호출 → Step 3: Given 구성
+it('should complete pending order', () => {
+  const order = createOrder({ id: '1', status: 'pending' });
+  const result = completeOrder(order);
+  expect(result).toEqual({ id: '1', status: 'completed' });
+});
+```
+
+## Starter Test
+가장 단순한 테스트로 시작하여 동작하는 코드 확보. 어디서 시작할지 모를 때 사용.
+
+```typescript
+// Good: 가장 단순한 케이스로 시작
+it('should create an order', () => {
+  const order = createOrder({ userId: '1' });
+  expect(order).toBeDefined();
+});
+
+// 점진적 확장
+it('should add item to order', () => { ... });
+it('should calculate subtotal', () => { ... });
+```
+
+## Test Data Builder
+테스트 데이터 생성을 빌더 패턴으로 추상화. 테스트마다 비슷한 객체 생성이 반복될 때 사용.
+
+```typescript
+class UserBuilder {
+  private user: Partial<User> = {
+    id: 'default-id',
+    email: 'test@example.com',
+    name: 'Test User',
+    role: 'user',
+  };
+
+  withRole(role: 'admin' | 'user') { this.user.role = role; return this; }
+  build(): User { return this.user as User; }
+}
+
+it('should allow admin to delete users', () => {
+  const admin = new UserBuilder().withRole('admin').build();
+  expect(deleteUser(admin, 'target-123')).toBe(true);
+});
+```
+
+## Tidying
+리팩토링 전 작은 정리. 변수 추출, 메서드 추출 등.
+
+```typescript
+// Before: 지저분한 코드
+function processOrder(order) {
+  if (order.items.reduce((s, i) => s + i.price * i.qty, 0) > 100 && order.user.level === 'gold') {
+    return order.items.reduce((s, i) => s + i.price * i.qty, 0) * 0.9;
+  }
+  return order.items.reduce((s, i) => s + i.price * i.qty, 0);
+}
+
+// After: 변수/함수 추출
+function calculateSubtotal(items: Item[]): number {
+  return items.reduce((sum, item) => sum + item.price * item.qty, 0);
+}
+
+function processOrder(order) {
+  const subtotal = calculateSubtotal(order.items);
+  const qualifiesForDiscount = subtotal > 100 && order.user.level === 'gold';
+  return qualifiesForDiscount ? subtotal * 0.9 : subtotal;
+}
+```
+
+## Learning Test
+외부 라이브러리/API 학습용 테스트. 새 라이브러리 사용 전 동작 확인.
+
+```typescript
+describe('Prisma Learning Tests', () => {
+  it('should create and find user', async () => {
+    const user = await prisma.user.create({ data: { email: 'test@test.com', name: 'Test' } });
+    const found = await prisma.user.findUnique({ where: { id: user.id } });
+    expect(found).toEqual(user);
+  });
+
+  it('should return null for non-existent user', async () => {
+    const found = await prisma.user.findUnique({ where: { id: 'non-existent' } });
+    expect(found).toBeNull();
+  });
+});
+```

package/templates/base/skills/mobile/dart/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: dart
+description: Dart 언어 가이드라인. Sound null safety, 패턴 매칭, sealed class, 비동기 프로그래밍, Effective Dart 스타일.
+version: "1.0.0"
+tags: [dart, language, null-safety, async]
+user-invocable: false
+---
+
+# Dart Language Guidelines
+
+Dart 3+ 기반 언어 패턴과 컨벤션. Flutter/서버 공통 적용.
+
+## Philosophy
+
+- Null safety는 타협 없음 — `!` 대신 패턴으로 해결
+- 비동기는 구조화 — Future 체이닝보다 async/await
+- Sealed class로 불가능한 상태를 불가능하게
+- Effective Dart가 스타일 기준
+
+## Rules
+
+| Priority | Rule | Description |
+|----------|------|-------------|
+| CRITICAL | [null-safety](rules/null-safety.md) | Sound null safety 패턴, late/! 남용 방지 |
+| CRITICAL | [async-patterns](rules/async-patterns.md) | Future, Stream, Isolate, 에러 전파 |
+| HIGH | [type-system](rules/type-system.md) | Sealed class, 패턴 매칭, Records (Dart 3+) |
+| HIGH | [code-style](rules/code-style.md) | Effective Dart, 네이밍, 문서화, linter 규칙 |
+
+## Quick Rules
+
+### Null Safety
+- `String?` 사용 시 반드시 null 체크 후 접근
+- `!` (bang operator) 금지 — if/case/??로 해결
+- `late` 는 lifecycle이 보장될 때만 (initState 등)
+- collection은 `whereType<T>()`로 null 필터링
+
+### 비동기
+- async/await 우선, then() 체이닝 금지
+- 독립 작업은 `Future.wait([])` 로 병렬 실행
+- Stream 구독은 반드시 cancel (dispose)
+- 무거운 연산은 `Isolate.run()` 또는 `compute()`
+- Zone.current로 에러 포착하지 말 것 — try/catch 명시
+
+### 타입 시스템 (Dart 3+)
+- `sealed class` 로 상태/에러 모델링 → switch exhaustive 체크
+- Records `(int, String)` 로 경량 튜플
+- 패턴 매칭 `if (value case Pattern())` 적극 활용
+- `extension type` 으로 zero-cost wrapper (ID 타입 등)
+
+### 스타일
+- `dart_style` 포매터 + `analysis_options.yaml` strict
+- lowerCamelCase (변수/함수), UpperCamelCase (클래스/enum)
+- 공개 API에 `///` dartdoc 필수
+- `part`/`part of` 금지 — 파일 분리로 해결
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | Bang operator (!) 없음 |
+| CRITICAL | async/await 사용 (then 체이닝 없음) |
+| CRITICAL | Stream 구독 dispose 처리 |
+| CRITICAL | sealed class로 상태 모델링 |
+| HIGH | Future.wait으로 병렬 처리 |
+| HIGH | late 사용 최소화 (lifecycle 보장 시만) |
+| HIGH | Effective Dart 네이밍 준수 |
+| HIGH | 공개 API dartdoc 작성 |
+| MEDIUM | extension type으로 ID 타입 래핑 |
+| MEDIUM | analysis_options strict 모드 |

package/templates/base/skills/mobile/dart/rules/async-patterns.md

@@ -0,0 +1,112 @@
+---
+title: Async Patterns
+impact: CRITICAL
+tags: async, future, stream, isolate
+---
+
+## Async Patterns
+
+Dart의 비동기 프로그래밍 핵심 패턴. async/await, Stream, Isolate.
+
+### async/await 우선
+
+**Incorrect:**
+```dart
+Future<User> fetchUser(String id) {
+  return api.get('/users/$id')
+    .then((response) => User.fromJson(response.data))
+    .catchError((e) => throw FetchException(e.toString()));
+}
+```
+
+**Correct:**
+```dart
+Future<User> fetchUser(String id) async {
+  try {
+    final response = await api.get('/users/$id');
+    return User.fromJson(response.data);
+  } on DioException catch (e) {
+    throw FetchException(e.message ?? 'Unknown error');
+  }
+}
+```
+
+### 병렬 실행
+
+**Incorrect:**
+```dart
+final user = await fetchUser(id);      // 1초
+final posts = await fetchPosts(id);    // 1초
+final friends = await fetchFriends(id); // 1초  → 총 3초
+```
+
+**Correct:**
+```dart
+final (user, posts, friends) = await (
+  fetchUser(id),
+  fetchPosts(id),
+  fetchFriends(id),
+).wait;  // 총 ~1초 (Dart 3 record destructuring)
+```
+
+### Stream 관리
+
+**Incorrect:**
+```dart
+class _ChatState extends State<ChatScreen> {
+  @override
+  void initState() {
+    super.initState();
+    chatStream.listen((msg) => setState(() => messages.add(msg)));
+    // 구독 해제 안 됨 → 메모리 누수
+  }
+}
+```
+
+**Correct:**
+```dart
+class _ChatState extends State<ChatScreen> {
+  StreamSubscription<Message>? _subscription;
+
+  @override
+  void initState() {
+    super.initState();
+    _subscription = chatStream.listen(
+      (msg) => setState(() => messages.add(msg)),
+      onError: (e) => _handleError(e),
+    );
+  }
+
+  @override
+  void dispose() {
+    _subscription?.cancel();
+    super.dispose();
+  }
+}
+```
+
+### Isolate (무거운 연산)
+
+**Incorrect:**
+```dart
+// 메인 스레드에서 JSON 파싱 → UI 프레임 드롭
+final data = jsonDecode(hugeJsonString) as Map<String, dynamic>;
+final items = (data['items'] as List).map(Item.fromJson).toList();
+```
+
+**Correct:**
+```dart
+// Isolate에서 실행 → UI 프레임 유지
+final items = await Isolate.run(() {
+  final data = jsonDecode(hugeJsonString) as Map<String, dynamic>;
+  return (data['items'] as List).map(Item.fromJson).toList();
+});
+```
+
+### 규칙
+
+- `then()` 체이닝 금지 → async/await
+- 독립 Future는 `.wait` (Dart 3) 또는 `Future.wait([])`로 병렬
+- Stream 구독은 반드시 `cancel()` (dispose에서)
+- 100ms+ 연산은 `Isolate.run()` 검토
+- `completer` 직접 사용 금지 (async/await로 대체 가능)

package/templates/base/skills/mobile/dart/rules/code-style.md

@@ -0,0 +1,96 @@
+---
+title: Code Style (Effective Dart)
+impact: HIGH
+tags: style, naming, linting, documentation
+---
+
+## Code Style (Effective Dart)
+
+Effective Dart 기반 코딩 컨벤션. `dart_style` 포매터 + strict analysis_options.
+
+### analysis_options.yaml
+
+```yaml
+include: package:flutter_lints/flutter.yaml
+# 또는 non-Flutter: package:lints/recommended.yaml
+
+linter:
+  rules:
+    # 필수 추가 규칙
+    - prefer_const_constructors
+    - prefer_const_declarations
+    - avoid_dynamic_calls
+    - unawaited_futures
+    - cancel_subscriptions
+    - close_sinks
+    - prefer_final_locals
+    - avoid_print        # debugPrint 사용
+    - require_trailing_commas
+
+analyzer:
+  errors:
+    missing_return: error
+    unawaited_futures: warning
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+```
+
+### 네이밍
+
+| 종류 | 규칙 | 예시 |
+|------|------|------|
+| 클래스, enum, typedef | UpperCamelCase | `UserProfile`, `AuthState` |
+| 변수, 함수, 파라미터 | lowerCamelCase | `userName`, `fetchData()` |
+| 상수 | lowerCamelCase | `defaultTimeout` (UPPER_SNAKE 금지) |
+| 파일 | snake_case | `user_profile.dart` |
+| 라이브러리 접두사 | snake_case | `import 'x' as my_lib` |
+
+**Incorrect:**
+```dart
+const MAX_RETRY_COUNT = 3;  // UPPER_SNAKE
+class user_service { }       // snake_case 클래스
+String UserName = '';         // UpperCamel 변수
+```
+
+**Correct:**
+```dart
+const maxRetryCount = 3;
+class UserService { }
+String userName = '';
+```
+
+### Import 정리
+
+```dart
+// 1. dart: 표준 라이브러리
+import 'dart:async';
+import 'dart:convert';
+
+// 2. package: 외부 패키지
+import 'package:flutter/material.dart';
+import 'package:riverpod/riverpod.dart';
+
+// 3. 프로젝트 내부 (상대 경로 금지)
+import 'package:my_app/features/auth/domain/user.dart';
+```
+
+### 문서화
+
+```dart
+/// 사용자 프로필을 가져온다.
+///
+/// [userId]에 해당하는 사용자가 없으면 null 반환.
+/// 네트워크 에러 시 [FetchException] 발생.
+Future<UserProfile?> fetchProfile(String userId) async { ... }
+```
+
+### 규칙
+
+- `dart format .` 자동 포매팅 (커밋 전 필수)
+- 상대 import 금지 → `package:` import
+- `print()` 금지 → `debugPrint()` 또는 logger
+- `part`/`part of` 금지 → 파일 분리
+- trailing comma 필수 (위젯 트리 가독성)
+- `prefer_final_locals` 활성화

package/templates/base/skills/mobile/dart/rules/null-safety.md

@@ -0,0 +1,84 @@
+---
+title: Sound Null Safety
+impact: CRITICAL
+tags: null-safety, dart3, patterns
+---
+
+## Sound Null Safety
+
+Dart의 null safety는 컴파일 타임에 null 참조를 방지한다.
+`!`와 `late` 남용은 런타임 크래시를 초래하므로 패턴으로 해결.
+
+### Bang Operator (!) 금지
+
+**Incorrect:**
+```dart
+final user = users.firstWhere((u) => u.id == id);
+print(user!.name); // NoSuchElementException 위험
+```
+
+**Correct:**
+```dart
+final user = users.where((u) => u.id == id).firstOrNull;
+if (user case final found?) {
+  print(found.name);
+} else {
+  throw UserNotFoundException(id);
+}
+```
+
+### Nullable Collection 처리
+
+**Incorrect:**
+```dart
+final List<String?> items = getData();
+for (final item in items) {
+  print(item!.length); // null이면 크래시
+}
+```
+
+**Correct:**
+```dart
+final List<String?> items = getData();
+final validItems = items.whereType<String>(); // null 필터링 + 타입 내로잉
+for (final item in validItems) {
+  print(item.length); // String 보장
+}
+```
+
+### late 사용 기준
+
+**Incorrect:**
+```dart
+class MyWidget extends StatefulWidget { ... }
+class _MyWidgetState extends State<MyWidget> {
+  late final ApiService api; // dispose 전에 접근하면 크래시
+  late String userName;      // 초기화 보장 없음
+}
+```
+
+**Correct:**
+```dart
+class _MyWidgetState extends State<MyWidget> {
+  late final TextEditingController _controller; // initState에서 반드시 초기화
+
+  @override
+  void initState() {
+    super.initState();
+    _controller = TextEditingController();
+  }
+
+  @override
+  void dispose() {
+    _controller.dispose();
+    super.dispose();
+  }
+}
+```
+
+### 규칙
+
+- `late` 는 lifecycle 보장 컨텍스트에서만: `initState`, `setUp`, 생성자 body
+- `!` 대신 `case`, `??`, `?.` 사용
+- `firstWhere` → `firstOrNull` + null 체크
+- 함수 파라미터에서 `required` 키워드로 null 방지

package/templates/base/skills/mobile/dart/rules/type-system.md

@@ -0,0 +1,111 @@
+---
+title: Type System (Dart 3+)
+impact: HIGH
+tags: sealed-class, pattern-matching, records, extension-type
+---
+
+## Type System (Dart 3+)
+
+Dart 3의 sealed class, 패턴 매칭, records, extension type으로 타입 안전한 코드 작성.
+
+### Sealed Class (상태 모델링)
+
+**Incorrect:**
+```dart
+enum LoadState { loading, success, error }
+
+class ScreenState {
+  final LoadState state;
+  final List<Item>? data;   // success일 때만 유효
+  final String? error;       // error일 때만 유효
+  // 불가능한 조합이 가능: state=loading + data!=null
+}
+```
+
+**Correct:**
+```dart
+sealed class ScreenState {}
+class Loading extends ScreenState {}
+class Success extends ScreenState {
+  final List<Item> data;
+  Success(this.data);
+}
+class Failure extends ScreenState {
+  final String message;
+  Failure(this.message);
+}
+
+// exhaustive switch — 새 상태 추가 시 컴파일 에러
+Widget build(BuildContext context) => switch (state) {
+  Loading() => const CircularProgressIndicator(),
+  Success(:final data) => ItemList(items: data),
+  Failure(:final message) => ErrorView(message: message),
+};
+```
+
+### 패턴 매칭
+
+**Incorrect:**
+```dart
+if (response is Map<String, dynamic>) {
+  if (response.containsKey('data')) {
+    final data = response['data'];
+    if (data is List) {
+      // 중첩 if 지옥
+    }
+  }
+}
+```
+
+**Correct:**
+```dart
+if (response case {'data': List<Map<String, dynamic>> items}) {
+  final users = items.map(User.fromJson).toList();
+}
+```
+
+### Records (경량 튜플)
+
+**Incorrect:**
+```dart
+// 위치 좌표를 위한 불필요한 클래스
+class LatLng {
+  final double lat;
+  final double lng;
+  LatLng(this.lat, this.lng);
+}
+```
+
+**Correct:**
+```dart
+// Named record로 간결하게
+typedef LatLng = ({double lat, double lng});
+
+LatLng getLocation() => (lat: 1.3521, lng: 103.8198);
+
+final (:lat, :lng) = getLocation(); // 구조 분해
+```
+
+### Extension Type (Zero-Cost Wrapper)
+
+```dart
+extension type UserId(String value) {
+  factory UserId.fromInt(int id) => UserId('user_$id');
+}
+
+extension type PostId(String value) {}
+
+// 컴파일 타임에 타입 구분, 런타임 오버헤드 0
+void fetchUser(UserId id) { ... }
+void fetchPost(PostId id) { ... }
+
+fetchUser(PostId('abc')); // 컴파일 에러!
+```
+
+### 규칙
+
+- 상태/에러/결과는 `sealed class` + exhaustive switch
+- Map 접근은 패턴 매칭 `case` 사용
+- 2-3개 값 반환은 Record `(int, String)` 사용 (클래스 불필요)
+- ID 타입은 `extension type`으로 구분
+- `dynamic` 타입 금지 → `Object?` + 패턴 매칭