timsquad 3.3.0 → 3.5.0

package/templates/base/skills/mobile/flutter/ci-cd/rules/github-actions.md

@@ -0,0 +1,112 @@
+---
+title: GitHub Actions
+impact: HIGH
+impactDescription: "CI 없음 → 릴리스 품질 불안정, GitHub Actions → 코드 변경마다 자동 검증"
+tags: github-actions, ci, workflow, flutter-action, cache, artifact
+---
+
+## GitHub Actions
+
+**Impact: HIGH (CI 없음 → 릴리스 품질 불안정, GitHub Actions → 코드 변경마다 자동 검증)**
+
+Flutter 빌드 워크플로우, flutter-action, 테스트-빌드-업로드 파이프라인, 캐시.
+
+### 테스트 워크플로우
+
+**Incorrect (Flutter 수동 설치, 캐시 없음):**
+```yaml
+on: push
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - run: git clone https://github.com/flutter/flutter.git
+      - run: flutter test  # 매번 전체 다운로드 → 느림
+```
+
+**Correct (flutter-action + 캐시):**
+```yaml
+# .github/workflows/test.yml
+name: Test & Analyze
+on:
+  pull_request:
+    branches: [main, develop]
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: subosito/flutter-action@v2
+        with:
+          flutter-version: "3.27.0"
+          cache: true
+      - uses: actions/cache@v4
+        with:
+          path: ${{ env.PUB_CACHE }}
+          key: pub-${{ runner.os }}-${{ hashFiles('**/pubspec.lock') }}
+      - run: flutter pub get
+      - run: flutter analyze --no-fatal-infos
+      - run: flutter test --coverage
+```
+
+### 릴리스 워크플로우 (iOS + Android)
+
+```yaml
+# .github/workflows/ios-release.yml — 태그 푸시 트리거
+name: iOS Release
+on: { push: { tags: ["v*"] } }
+jobs:
+  ios-build:
+    runs-on: macos-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+      - uses: subosito/flutter-action@v2
+        with: { flutter-version: "3.27.0", cache: true }
+      - uses: ruby/setup-ruby@v1
+        with: { ruby-version: "3.2", bundler-cache: true, working-directory: ios }
+      - run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          flutter build ipa --release --build-name=$VERSION --build-number=$GITHUB_RUN_NUMBER
+          cd ios && bundle exec fastlane beta
+        env:
+          MATCH_GIT_URL: ${{ secrets.MATCH_GIT_URL }}
+          MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
+```
+
+```yaml
+# .github/workflows/android-release.yml
+name: Android Release
+on: { push: { tags: ["v*"] } }
+jobs:
+  android-build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with: { distribution: "temurin", java-version: "17" }
+      - uses: subosito/flutter-action@v2
+        with: { flutter-version: "3.27.0", cache: true }
+      - run: echo "${{ secrets.ANDROID_KEYSTORE_BASE64 }}" | base64 --decode > android/release.keystore
+      - run: flutter build appbundle --release --build-number=${{ github.run_number }}
+      - uses: r0adkll/upload-google-play@v1
+        with:
+          serviceAccountJsonPlainText: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT }}
+          packageName: com.yourapp.id
+          releaseFiles: build/app/outputs/bundle/release/app-release.aab
+          track: internal
+```
+
+### 규칙
+
+- `subosito/flutter-action@v2` — Flutter SDK 설치 + `cache: true`
+- pub 캐시 — `actions/cache@v4` + `pubspec.lock` 해시 키
+- `concurrency` — 동일 PR 중복 빌드 취소
+- `timeout-minutes` — 테스트 15분, iOS 45분, Android 30분
+- 태그 `v*` 트리거 — 릴리스 빌드, PR → 테스트만
+- 시크릿 — `${{ secrets.* }}` 로 주입, 하드코딩 금지

package/templates/base/skills/mobile/flutter/ci-cd/rules/store-deployment.md

@@ -0,0 +1,106 @@
+---
+title: Store Deployment
+impact: HIGH
+impactDescription: "배포 실수 → 심사 거절/사용자 불만, 체계적 배포 → 안정적 출시"
+tags: app-store, play-store, testflight, deployment, rollout, metadata
+---
+
+## Store Deployment
+
+**Impact: HIGH (배포 실수 → 심사 거절/사용자 불만, 체계적 배포 → 안정적 출시)**
+
+TestFlight 업로드, Play Store 트랙 관리, 메타데이터, 단계적 출시 전략.
+
+### TestFlight (iOS) 배포
+
+**Incorrect (Xcode에서 수동 업로드):**
+```
+Xcode > Archive > Distribute App → 수동 반복, 재현 불가
+```
+
+**Correct (Fastlane + API Key):**
+```ruby
+lane :beta do
+  api_key = app_store_connect_api_key(
+    key_id: ENV["ASC_KEY_ID"],
+    issuer_id: ENV["ASC_ISSUER_ID"],
+    key_filepath: ENV["ASC_KEY_PATH"],
+  )
+  build_app(workspace: "Runner.xcworkspace", scheme: "Runner",
+            export_method: "app-store")
+  upload_to_testflight(
+    api_key: api_key,
+    skip_waiting_for_build_processing: true,
+    groups: ["Internal Testers"],
+    changelog: ENV["RELEASE_NOTES"] || "Bug fixes and improvements",
+  )
+end
+```
+
+### Play Store 트랙 전략
+
+**Incorrect (바로 production):**
+```ruby
+supply(track: "production", aab: "app-release.aab")
+# → 테스트 없이 전체 배포 → 크래시 위험
+```
+
+**Correct (단계적 트랙 승격):**
+```ruby
+lane :internal do
+  supply(track: "internal", aab: "app-release.aab",
+         json_key: ENV["GOOGLE_PLAY_JSON_KEY_PATH"])
+end
+
+lane :promote_production do |options|
+  supply(track: "internal", track_promote_to: "production",
+         rollout: options[:rollout] || "0.01",
+         json_key: ENV["GOOGLE_PLAY_JSON_KEY_PATH"])
+end
+
+lane :increase_rollout do |options|
+  supply(track: "production", rollout: options[:rollout],
+         json_key: ENV["GOOGLE_PLAY_JSON_KEY_PATH"])
+end
+```
+
+### 단계적 출시 전략
+
+```
+Day 0:  internal (팀) → 크래시율/기능 확인
+Day 1:  closed testing → 소규모 외부 테스터
+Day 3:  production 1% → 크래시 모니터링
+Day 5:  production 5% → ANR 비율 확인
+Day 7:  production 20% → 사용자 피드백
+Day 10: production 50%
+Day 14: production 100%
+
+중단 기준: 크래시율 > 1%, ANR > 0.5%, 평점 급락
+```
+
+### 메타데이터 관리
+
+```
+fastlane/metadata/
+├── android/en-US/     # title.txt, short_description.txt, full_description.txt
+├── android/ko/
+├── ios/en-US/         # name.txt, subtitle.txt, description.txt, keywords.txt
+├── ios/ko/
+└── screenshots/en-US/ # iPhone6.5/, iPhone5.5/, iPad12.9/
+```
+
+```ruby
+lane :update_metadata do
+  deliver(skip_binary_upload: true, skip_screenshots: false,
+          overwrite_screenshots: true, api_key_path: "fastlane/api_key.json")
+end
+```
+
+### 규칙
+
+- TestFlight 자동 업로드 — `upload_to_testflight` + API Key, 수동 금지
+- Play Store 트랙 순서 — internal → closed → open → production
+- 단계적 출시 — 1%부터 시작, 크래시율 모니터링 후 확대
+- 메타데이터 코드 관리 — `fastlane/metadata/` 텍스트 파일
+- 릴리스 노트 — CHANGELOG에서 추출, 수동 작성 금지
+- 크래시율 1% 초과 → 즉시 rollout 중단

package/templates/base/skills/mobile/flutter/ci-cd/rules/versioning.md

@@ -0,0 +1,107 @@
+---
+title: Versioning
+impact: MEDIUM
+impactDescription: "버전 관리 부재 → 빌드 추적 불가, 체계적 버전 → 출시 이력 완전 추적"
+tags: versioning, semver, build-number, changelog, git-tag, pubspec
+---
+
+## Versioning
+
+**Impact: MEDIUM (버전 관리 부재 → 빌드 추적 불가, 체계적 버전 → 출시 이력 완전 추적)**
+
+pubspec.yaml 시맨틱 버저닝, 빌드 넘버 자동 증가, CHANGELOG 생성, git 태그 연동.
+
+### pubspec.yaml 버전 형식
+
+**Incorrect (빌드 넘버 누락):**
+```yaml
+version: 1.0.0  # → 스토어 업로드 시 구분 불가, 수동 관리 실수
+```
+
+**Correct (시맨틱 버전 + 빌드 넘버):**
+```yaml
+version: 1.2.3+45
+# major(1) — 호환 불가 변경
+# minor(2) — 새 기능 (하위 호환)
+# patch(3) — 버그 수정
+# build(45) — CI 빌드 넘버 (스토어 구분용, 항상 증가)
+```
+
+### 빌드 넘버 자동 증가
+
+```bash
+# 전략 1: CI 빌드 넘버 (권장)
+flutter build appbundle --build-number=${{ github.run_number }}  # GitHub Actions
+flutter build ipa --build-number=$PROJECT_BUILD_NUMBER           # Codemagic
+
+# 전략 2: 타임스탬프 (YYYYMMDDNN)
+BUILD_NUMBER=$(date +%Y%m%d)$(printf "%02d" $BUILD_COUNT)
+
+# 전략 3: Git 커밋 카운트
+BUILD_NUMBER=$(git rev-list --count HEAD)
+```
+
+### CI에서 버전 오버라이드
+
+```bash
+TAG=${GITHUB_REF#refs/tags/v}  # v1.2.3 → 1.2.3
+flutter build ipa --release \
+  --build-name=$TAG \
+  --build-number=${{ github.run_number }}
+```
+
+### 런타임 버전 접근
+
+```dart
+import 'package:package_info_plus/package_info_plus.dart';
+
+class AppVersion {
+  static Future<String> getFullVersion() async {
+    final info = await PackageInfo.fromPlatform();
+    return '${info.version}+${info.buildNumber}';  // "1.2.3+45"
+  }
+}
+```
+
+### CHANGELOG 자동 생성
+
+```yaml
+# .github/workflows/changelog.yml (태그 푸시 시)
+- uses: orhun/git-cliff-action@v3
+  with:
+    config: cliff.toml
+    args: --verbose
+  env:
+    OUTPUT: CHANGELOG.md
+- uses: softprops/action-gh-release@v2
+  with:
+    body_path: CHANGELOG.md
+```
+
+### Git 태그 전략
+
+```bash
+git tag -a v1.2.3 -m "Release v1.2.3"
+git push origin v1.2.3
+
+# 태그 규칙:
+# v1.2.3        → production
+# v1.2.3-rc1    → release candidate
+# v1.2.3-beta.1 → beta (TestFlight/Internal)
+```
+
+### 플랫폼별 주의
+
+```
+iOS:  CFBundleVersion = build-number, 동일 버전 재업로드 불가
+Android: versionCode = 정수, 감소 불가 (한번 올리면 되돌릴 수 없음)
+```
+
+### 규칙
+
+- `version: major.minor.patch+buildNumber` 형식 유지
+- 빌드 넘버는 CI에서 자동 증가 — 수동 관리 금지
+- `--build-name` + `--build-number` CI 오버라이드
+- git 태그 `v*` — 릴리스와 1:1 매핑
+- CHANGELOG 자동 생성 — conventional commits 기반
+- 빌드 넘버 절대 감소 불가 — 스토어 거부

package/templates/base/skills/mobile/flutter/i18n/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: i18n
+description: |
+  Flutter 국제화(i18n) 가이드라인.
+  flutter_localizations, intl, ARB 파일 관리,
+  RTL 레이아웃, 복수형/성별 처리, 런타임 로캘 전환.
+version: "1.0.0"
+tags: [flutter, i18n, l10n, localization, arb, intl, rtl]
+user-invocable: false
+---
+
+# Internationalization (i18n) & Localization
+
+Flutter 다국어 지원 통합 가이드.
+ARB 파일 기반 번역 관리, ICU MessageFormat, RTL 대응, 런타임 로캘 전환.
+
+## Philosophy
+
+- 텍스트는 코드에 없다 — 모든 사용자 노출 문자열은 ARB 파일에
+- 로캘은 상태 — Riverpod provider로 관리, SharedPreferences로 영속화
+- RTL은 기본 — Directionality 위젯 활용, 하드코딩된 padding/margin 금지
+- 번역은 프로세스 — 개발자 → 번역가 → 검수, CI에서 누락 키 자동 감지
+
+## Resources
+
+5개 규칙 + 1개 참조. i18n 파이프라인 전체를 커버.
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | rule | [localization-setup](rules/localization-setup.md) | flutter_localizations, intl, l10n.yaml, pubspec generate |
+| CRITICAL | rule | [arb-files](rules/arb-files.md) | ARB 파일 구조, @placeholder, 네이밍 컨벤션, gen-l10n |
+| HIGH | rule | [text-direction](rules/text-direction.md) | RTL 대응, EdgeInsetsDirectional, AlignmentDirectional |
+| HIGH | rule | [plural-gender](rules/plural-gender.md) | ICU MessageFormat, plural, select, ordinal |
+| MEDIUM | rule | [locale-switching](rules/locale-switching.md) | LocaleNotifier, SharedPreferences, 런타임 전환 |
+| — | ref | [i18n-architecture](references/i18n-architecture.md) | 디렉토리 구조, 번역 워크플로우, CI 검증 |
+
+## Quick Rules
+
+### 설정
+- `pubspec.yaml` 에 `generate: true` + `flutter_localizations`, `intl` 의존성
+- `l10n.yaml` 로 ARB 디렉토리, 출력 클래스, 기본 로캘 지정
+- `MaterialApp.localizationsDelegates` + `supportedLocales` 필수 설정
+
+### ARB 파일
+- `app_en.arb` 가 기본 (template ARB), `app_ko.arb` 등 로캘별 추가
+- 키 네이밍: `featureName_context` (예: `matchDetail_inviteButton`)
+- `@placeholder` 메타데이터로 동적 값 타입 명시
+- `flutter gen-l10n` 으로 자동 생성 (`AppLocalizations` 클래스)
+
+### RTL 대응
+- `EdgeInsetsDirectional.only(start: 16)` (left/right 대신 start/end)
+- `AlignmentDirectional.centerStart` (centerLeft 대신)
+- 아이콘 미러링: `Directionality` 감지 후 조건부 Transform
+
+### 복수형/성별
+- ICU `{count, plural, =0{no items} =1{1 item} other{{count} items}}`
+- `{gender, select, male{his} female{her} other{their}}`
+- ARB 파일에 직접 ICU 구문 작성, intl이 자동 파싱
+
+### 로캘 전환
+- `LocaleNotifier` (Riverpod StateNotifier) → 현재 로캘 관리
+- `SharedPreferences` 로 선택 로캘 영속화
+- 앱 재시작 없이 `MaterialApp.locale` 변경으로 즉시 반영
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | `pubspec.yaml` 에 `generate: true` 설정 |
+| CRITICAL | `l10n.yaml` 생성 (arb-dir, template-arb-file, output-localization-file) |
+| CRITICAL | `MaterialApp.localizationsDelegates` 3종 등록 |
+| CRITICAL | 모든 사용자 노출 문자열이 ARB 파일에 존재 |
+| HIGH | `@placeholder` 메타데이터 완전성 (타입, 예시, 설명) |
+| HIGH | RTL 레이아웃에서 Directional 위젯 사용 |
+| HIGH | 복수형/성별 표현이 ICU MessageFormat 사용 |
+| MEDIUM | SharedPreferences 로캘 영속화 |
+| MEDIUM | CI에서 누락 키 자동 감지 |
+| MEDIUM | 번역 워크플로우 문서화 (개발자 → 번역가 → 검수) |

package/templates/base/skills/mobile/flutter/i18n/references/i18n-architecture.md

@@ -0,0 +1,225 @@
+---
+title: i18n Architecture & Translation Workflow
+category: reference
+source: internal
+tags: architecture, directory, workflow, ci, missing-keys, translation
+---
+
+# i18n Architecture & Translation Workflow
+
+i18n 서비스 아키텍처. 디렉토리 구조, 번역 워크플로우, CI 자동 검증, 누락 키 감지.
+
+## Key Concepts
+
+- **ARB 중심**: 모든 번역의 원본은 ARB 파일 (코드에 문자열 하드코딩 금지)
+- **코드 생성**: `flutter gen-l10n` → 타입 안전한 `AppLocalizations` 클래스 자동 생성
+- **CI 검증**: 빌드 파이프라인에서 누락 키, 미사용 키, 포맷 오류 자동 감지
+- **번역 프로세스**: 개발자 (키 추가) → 번역가 (번역) → 검수 (QA) → 머지
+
+## Directory Structure
+
+```
+lib/
+├── l10n/
+│   ├── app_en.arb                    # 기본 (template) — 모든 키 + 메타데이터
+│   ├── app_ko.arb                    # 한국어
+│   ├── app_ms.arb                    # 말레이어
+│   ├── app_id.arb                    # 인도네시아어
+│   └── app_zh.arb                    # 중국어 (간체)
+│
+├── core/
+│   └── l10n/
+│       ├── locale_notifier.dart      # LocaleNotifier (Riverpod)
+│       ├── app_locale.dart           # AppLocale enum (지원 로캘 목록)
+│       ├── l10n_extension.dart       # BuildContext.l10n extension
+│       └── locale_observer.dart      # 시스템 로캘 변경 감지
+│
+├── features/
+│   └── settings/
+│       └── presentation/
+│           └── screens/
+│               └── language_settings_screen.dart  # 언어 설정 UI
+│
+└── .dart_tool/
+    └── flutter_gen/
+        └── gen_l10n/                 # 자동 생성 (커밋 X)
+            ├── app_localizations.dart
+            ├── app_localizations_en.dart
+            ├── app_localizations_ko.dart
+            └── ...
+```
+
+## Translation Workflow
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    번역 워크플로우                          │
+├──────────┬────────────────┬──────────────┬───────────────┤
+│ 1. 개발자  │  2. 번역가       │  3. 검수       │  4. 머지      │
+├──────────┼────────────────┼──────────────┼───────────────┤
+│ app_en.arb│ app_ko.arb    │ 화면 확인     │ PR 승인       │
+│ 키 추가   │ app_ms.arb    │ 문맥 확인     │ CI 통과       │
+│ @메타데이터│ app_id.arb    │ 길이 확인     │ 머지          │
+│ 설명 작성  │ 번역 작성      │ RTL 확인     │ 배포          │
+├──────────┼────────────────┼──────────────┼───────────────┤
+│ PR 생성   │ 번역 PR 생성    │ 리뷰 코멘트  │ gen-l10n 실행  │
+└──────────┴────────────────┴──────────────┴───────────────┘
+```
+
+### 단계별 상세
+
+```
+1. 개발자 (키 추가)
+   - app_en.arb에 새 키 + @메타데이터 추가
+   - description에 화면 위치, 용도, 맥락 설명
+   - placeholder에 type, example 명시
+   - 스크린샷/화면 위치 정보 첨부 (번역가 맥락 전달)
+
+2. 번역가 (번역)
+   - 각 로캘 ARB 파일에 번역 추가
+   - ICU 복수형/성별 규칙 적용 (언어별)
+   - placeholder 위치 조정 (언어 어순에 맞게)
+
+3. 검수 (QA)
+   - 실제 화면에서 번역 확인 (텍스트 잘림, 줄바꿈)
+   - RTL 레이아웃 확인 (해당 시)
+   - 복수형/성별 변형 모두 확인
+   - 문화적 적절성 확인
+
+4. 머지
+   - CI 자동 검증 통과 확인
+   - flutter gen-l10n 빌드 성공 확인
+   - 머지 후 릴리스 포함
+```
+
+## CI Automated Verification
+
+### 누락 키 감지 스크립트
+
+```bash
+#!/bin/bash
+# scripts/check_l10n.sh — CI에서 실행
+
+set -e
+
+echo "=== i18n Key Verification ==="
+
+# 1. gen-l10n 빌드 테스트
+flutter gen-l10n
+echo "✓ gen-l10n succeeded"
+
+# 2. 누락 키 체크 (template ARB 기준)
+TEMPLATE="lib/l10n/app_en.arb"
+ERRORS=0
+
+for ARB in lib/l10n/app_*.arb; do
+  if [ "$ARB" = "$TEMPLATE" ]; then continue; fi
+
+  LOCALE=$(basename "$ARB" .arb | sed 's/app_//')
+
+  # template의 비-메타 키 추출
+  TEMPLATE_KEYS=$(grep -oP '^\s*"(?!@|@@)\K[^"]+' "$TEMPLATE" | sort)
+  LOCALE_KEYS=$(grep -oP '^\s*"(?!@|@@)\K[^"]+' "$ARB" | sort)
+
+  # 누락 키 찾기
+  MISSING=$(comm -23 <(echo "$TEMPLATE_KEYS") <(echo "$LOCALE_KEYS"))
+  if [ -n "$MISSING" ]; then
+    echo "✗ $LOCALE: Missing keys:"
+    echo "$MISSING" | sed 's/^/    /'
+    ERRORS=$((ERRORS + 1))
+  else
+    echo "✓ $LOCALE: All keys present"
+  fi
+done
+
+if [ $ERRORS -gt 0 ]; then
+  echo "FAIL: $ERRORS locale(s) have missing keys"
+  exit 1
+fi
+
+echo "=== All i18n checks passed ==="
+```
+
+### 미사용 키 감지
+
+```bash
+#!/bin/bash
+# scripts/check_unused_l10n.sh
+
+TEMPLATE="lib/l10n/app_en.arb"
+UNUSED=0
+
+# template의 키 목록 추출
+KEYS=$(grep -oP '^\s*"(?!@|@@)\K[^"]+' "$TEMPLATE")
+
+for KEY in $KEYS; do
+  # Dart 코드에서 사용 여부 확인 (.l10n.$KEY 또는 l10n.$KEY)
+  if ! grep -rq "\.$KEY" lib/ --include="*.dart" 2>/dev/null; then
+    echo "⚠ Potentially unused: $KEY"
+    UNUSED=$((UNUSED + 1))
+  fi
+done
+
+if [ $UNUSED -gt 0 ]; then
+  echo "WARNING: $UNUSED potentially unused key(s)"
+fi
+```
+
+## ARB Key Organization
+
+```json
+// 키 그룹화 전략 (featureName_ 접두사로 자연 정렬)
+{
+  "@@locale": "en",
+
+  // === Common (공통) ===
+  "common_cancelButton": "Cancel",
+  "common_confirmButton": "Confirm",
+  "common_deleteButton": "Delete",
+  "common_loadingMessage": "Loading...",
+  "common_retryButton": "Retry",
+
+  // === Error (에러) ===
+  "error_networkTimeout": "Network timeout. Please try again.",
+  "error_serverError": "Server error. Please try later.",
+  "error_unauthorized": "Please log in again.",
+
+  // === Match (매치) ===
+  "matchDetail_inviteButton": "Invite to Match",
+  "matchDetail_playerCount": "{count, plural, =0{No players} =1{1 player} other{{count} players}}",
+  "matchList_emptyState": "No matches available",
+  "matchList_title": "Available Matches",
+
+  // === Settings (설정) ===
+  "settings_languageTitle": "Language",
+  "settings_systemLanguage": "System Language"
+}
+```
+
+## Common Pitfalls
+
+1. **gen-l10n 미실행**: ARB 수정 후 코드 생성 안 하면 IDE 자동완성 미반영
+2. **@@locale 누락**: ARB 파일에 로캘 코드 없으면 파일명에서 유추 (명시 권장)
+3. **ICU 구문 오류**: 중괄호 불일치, other 누락 → gen-l10n 빌드 실패
+4. **텍스트 길이**: 독일어 등 긴 번역 → UI 레이아웃 깨짐 (Expanded/Flexible 사용)
+5. **날짜/숫자 포맷**: ARB placeholder format 미지정 → 로캘별 포맷 미적용
+6. **컨텍스트 없는 description**: 번역가가 맥락 모르면 오역 → 화면 위치/용도 필수
+7. **하드코딩된 문자열**: 로그, 에러 메시지도 ARB로 (사용자 노출 가능성)
+8. **synthetic-package 이해**: `.dart_tool/` 에 생성 → `.gitignore` 에 이미 포함 (커밋 X)
+
+## Examples
+
+### 최소 구현 체크리스트
+
+```
+[ ] pubspec.yaml: flutter_localizations + intl + generate: true
+[ ] l10n.yaml: arb-dir, template-arb-file, output-localization-file
+[ ] lib/l10n/app_en.arb: 기본 키 + @메타데이터
+[ ] lib/l10n/app_ko.arb (등): 번역 ARB
+[ ] MaterialApp: localizationsDelegates (4종) + supportedLocales
+[ ] core/l10n/: LocaleNotifier + AppLocale enum
+[ ] main.dart: SharedPreferences 초기화 + ProviderScope override
+[ ] 설정 화면: 언어 선택 UI
+[ ] CI: 누락 키 검증 스크립트
+[ ] 위젯 테스트: RTL 레이아웃 확인
+```