timsquad 2.1.0 → 3.4.0

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

@@ -0,0 +1,89 @@
+---
+name: flutter
+description: Flutter 개발 가이드라인. Feature-first 아키텍처, Riverpod 상태관리, 위젯 합성, 성능 최적화, 크로스플랫폼 적응형 UI.
+version: "1.0.0"
+tags: [flutter, mobile, cross-platform, riverpod]
+user-invocable: false
+---
+
+# Flutter Development Guidelines
+
+Flutter 3.x 기반 크로스플랫폼 앱 개발 가이드라인.
+Flutter 공식 아키텍처 가이드 + VGV + Riverpod 커뮤니티 베스트 프랙티스 종합.
+
+## Philosophy
+
+- 위젯은 합성 — 상속보다 조합, 작게 분리
+- 상태는 구조화 — Riverpod로 선언적 의존성
+- Feature-first — 기능 단위로 코드 구성
+- const 는 습관 — 불필요한 리빌드 원천 차단
+
+## Resources
+
+8개 규칙 + 2개 참조. 카테고리별 배치.
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | rule | [widget-conventions](rules/widget-conventions.md) | 위젯 합성, const, Key 사용, 크기 제한 |
+| CRITICAL | rule | [state-management](rules/state-management.md) | Riverpod Provider/Notifier 패턴 |
+| CRITICAL | rule | [architecture](rules/architecture.md) | Feature-first + MVVM + Data/Domain/UI 레이어 |
+| HIGH | rule | [navigation-routing](rules/navigation-routing.md) | go_router 선언적 라우팅, 딥링크 |
+| HIGH | rule | [performance](rules/performance.md) | 리빌드 최적화, ListView.builder, Impeller |
+| HIGH | rule | [testing](rules/testing.md) | Widget/Golden/Integration 테스트, mocktail |
+| MEDIUM | rule | [platform-adaptive](rules/platform-adaptive.md) | 적응형 UI, 반응형 레이아웃, 플랫폼 분기 |
+| MEDIUM | rule | [animations](rules/animations.md) | 암시적/명시적 애니메이션, Hero, 모션 가이드라인 |
+| — | ref | [project-structure](references/project-structure.md) | Feature-first + melos 모노레포 구조 |
+| — | ref | [freezed-patterns](references/freezed-patterns.md) | freezed + json_serializable 불변 모델 |
+
+## Quick Rules
+
+### 위젯
+- `const` 생성자 적극 사용 (리빌드 스킵)
+- 위젯 200줄 이하 — 초과 시 추출
+- build() 안에서 로직 금지 — ViewModel/Notifier로 분리
+- `GlobalKey` 남용 금지 — `ValueKey`/`ObjectKey` 사용
+
+### 상태 관리 (Riverpod)
+- UI 상태: `NotifierProvider` + `Notifier`
+- 서버 데이터: `FutureProvider` / `StreamProvider`
+- 파생 상태: `Provider` (computed)
+- `ref.watch` (build), `ref.listen` (side effect), `ref.read` (이벤트 핸들러)
+
+### 아키텍처
+- Feature-first 구조 (`lib/features/{name}/`)
+- 각 feature: `data/` + `domain/` + `presentation/`
+- Repository 패턴으로 데이터 소스 추상화
+- DTO ↔ Domain Model 변환 레이어
+
+### 네비게이션
+- go_router 선언적 라우팅
+- 딥링크/유니버설 링크 지원
+- 중첩 네비게이션 (ShellRoute)
+
+### 성능
+- `const` 위젯 우선
+- 리스트는 `ListView.builder` (lazy)
+- `RepaintBoundary`로 리빌드 범위 격리
+- 이미지: `cached_network_image` + 적절한 크기
+
+### 테스트
+- Widget test: `testWidgets` + `pumpWidget`
+- Unit test: Notifier/Repository 독립 테스트
+- Integration test: `patrol` (네이티브 상호작용)
+- Mock: `mocktail` (코드 생성 불필요)
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | const 생성자 사용 (lint: prefer_const_constructors) |
+| CRITICAL | Riverpod Provider 타입 올바르게 선택 |
+| CRITICAL | Feature-first 디렉토리 구조 |
+| CRITICAL | build() 안에 비즈니스 로직 없음 |
+| HIGH | ListView.builder 사용 (10+ 아이템) |
+| HIGH | Repository 패턴 (데이터 소스 추상화) |
+| HIGH | go_router 선언적 라우팅 |
+| HIGH | Widget test 작성 |
+| MEDIUM | RepaintBoundary 적용 (복잡한 서브트리) |
+| MEDIUM | 적응형 UI (Material + Cupertino) |
+| MEDIUM | 이미지 캐싱 + 적절한 리사이징 |

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

@@ -0,0 +1,82 @@
+---
+name: ci-cd
+description: |
+  Flutter CI/CD 파이프라인 가이드라인.
+  코드 서명, Fastlane, Codemagic, GitHub Actions,
+  스토어 배포, 버전 관리 자동화.
+version: "1.0.0"
+tags: [flutter, ci-cd, fastlane, codemagic, github-actions, code-signing, deployment]
+user-invocable: false
+---
+
+# CI/CD Pipeline
+
+Flutter 앱의 빌드, 테스트, 서명, 배포 자동화 가이드.
+iOS/Android 코드 서명, Fastlane/Codemagic/GitHub Actions 파이프라인, 스토어 배포, 버전 관리.
+
+## Philosophy
+
+- 배포는 자동 — 수동 빌드/업로드 금지, CI가 전부 처리
+- 서명은 분리 — 코드 서명 키를 CI 환경에 안전하게 주입, 레포에 절대 포함 금지
+- 버전은 규칙 — 시맨틱 버저닝 + 빌드 넘버 자동 증가
+- 환경은 격리 — dev/staging/prod 설정 분리, 환경별 독립 파이프라인
+
+## Resources
+
+6개 규칙 + 1개 참조. CI/CD 파이프라인 전체를 커버.
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | rule | [code-signing](rules/code-signing.md) | iOS provisioning profile, Android keystore, 인증서 관리 |
+| HIGH | rule | [fastlane-setup](rules/fastlane-setup.md) | Fastfile 구성, match, supply, deliver, .env 관리 |
+| HIGH | rule | [codemagic-setup](rules/codemagic-setup.md) | codemagic.yaml 워크플로우, 환경변수, 빌드 트리거 |
+| HIGH | rule | [github-actions](rules/github-actions.md) | Flutter 빌드 워크플로우, 테스트-빌드-업로드 파이프라인 |
+| HIGH | rule | [store-deployment](rules/store-deployment.md) | TestFlight, Play Store tracks, 메타데이터, 단계적 출시 |
+| MEDIUM | rule | [versioning](rules/versioning.md) | 시맨틱 버저닝, 빌드 넘버 자동 증가, CHANGELOG, git 태그 |
+| — | ref | [ci-cd-pipeline](references/ci-cd-pipeline.md) | 파이프라인 아키텍처, 환경 설정, 시크릿 관리, 롤백 |
+
+## Quick Rules
+
+### 코드 서명
+- iOS: `match` 로 인증서/프로필 Git 저장소 관리 (팀 공유)
+- Android: keystore 파일을 CI 환경변수로 base64 주입
+- 개발용/배포용 인증서 분리 — 동일 인증서 사용 금지
+- 서명 키를 레포에 커밋 금지 — `.gitignore` 에 `*.keystore`, `*.jks`, `*.p12` 추가
+
+### Fastlane
+- `Fastfile` 에 `ios`/`android` 레인 분리
+- `match` → iOS 인증서 자동 관리 (Git 저장소 or Google Cloud Storage)
+- `supply` → Google Play 업로드, `deliver` → App Store 업로드
+- `.env` 로 환경별 설정 분리 (`.env.production`, `.env.staging`)
+
+### CI/CD 플랫폼
+- Codemagic: Flutter 네이티브 지원, `codemagic.yaml` 로 워크플로우 정의
+- GitHub Actions: `subosito/flutter-action` 으로 Flutter 설치, pub cache 캐시 필수
+- 빌드 트리거: 태그 푸시 (`v*`) → 릴리스, PR → 테스트만
+
+### 스토어 배포
+- TestFlight: `deliver` 또는 `app-store-connect` API로 업로드
+- Play Store: internal → closed → open → production 트랙 순서
+- 단계적 출시 (staged rollout): 1% → 5% → 20% → 50% → 100%
+- 메타데이터 (스크린샷, 설명) 코드로 관리 (`fastlane/metadata/`)
+
+### 버전 관리
+- `pubspec.yaml`: `version: major.minor.patch+buildNumber`
+- 빌드 넘버: CI에서 자동 증가 (`--build-number=$CI_BUILD_NUMBER`)
+- git 태그: `v1.2.3` 형식, 릴리스 빌드와 1:1 매핑
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | iOS 코드 서명 (provisioning profile + 인증서) CI에 구성 |
+| CRITICAL | Android keystore CI 환경변수로 안전하게 주입 |
+| CRITICAL | 서명 키/인증서 `.gitignore` 에 추가 확인 |
+| CRITICAL | CI 파이프라인: test → build → deploy 순서 보장 |
+| HIGH | Fastlane match 설정 (iOS 인증서 팀 공유) |
+| HIGH | 환경별 (dev/staging/prod) 빌드 설정 분리 |
+| HIGH | 스토어 업로드 자동화 (TestFlight + Play Store) |
+| HIGH | 빌드 넘버 자동 증가 전략 구현 |
+| MEDIUM | CHANGELOG 자동 생성 (conventional commits 기반) |
+| MEDIUM | 슬랙/디스코드 배포 알림 설정 |
+| MEDIUM | 롤백 절차 문서화 및 테스트 |

package/templates/base/skills/mobile/flutter/ci-cd/references/ci-cd-pipeline.md

@@ -0,0 +1,314 @@
+---
+title: CI/CD Pipeline Architecture
+category: reference
+source: internal
+tags: pipeline, architecture, environment, secrets, rollback, diagram
+---
+
+# CI/CD Pipeline Architecture
+
+파이프라인 아키텍처 다이어그램, 환경별 설정, 시크릿 관리 전략, 롤백 절차.
+
+## Key Concepts
+
+- **파이프라인**: 코드 변경 → 테스트 → 빌드 → 배포 자동화 흐름
+- **환경 분리**: dev/staging/prod 각각 독립 설정, 시크릿, 배포 대상
+- **시크릿 관리**: 서명 키, API 키, 서비스 계정을 안전하게 저장/주입
+- **롤백**: 문제 발생 시 이전 버전으로 빠르게 복원
+
+## Pipeline Architecture
+
+```
+코드 변경 흐름:
+
+Feature Branch    PR (→ main)       Tag (v*)         Store
+    │                 │                │               │
+    ▼                 ▼                ▼               ▼
+  [Lint]          [Test]          [Build]         [Deploy]
+  분석 +          단위 테스트       iOS IPA          TestFlight
+  포맷 검사       통합 테스트       Android AAB      Play Store
+                  커버리지                           단계적 출시
+    │                 │                │               │
+    ▼                 ▼                ▼               ▼
+  피드백           PR 체크           Artifact        Notify
+  즉시 알림        통과/실패          저장            Slack/Email
+```
+
+### 상세 파이프라인
+
+```
+PR 생성/업데이트:
+  ├─ 1. Checkout
+  ├─ 2. flutter pub get (캐시)
+  ├─ 3. flutter analyze
+  ├─ 4. flutter test --coverage
+  ├─ 5. 커버리지 리포트 업로드
+  └─ 6. PR 상태 업데이트 (pass/fail)
+
+태그 푸시 (v1.2.3):
+  ├─ 1. Checkout + 태그에서 버전 추출
+  ├─ 2. flutter pub get
+  ├─ 3. flutter test (릴리스 전 최종 검증)
+  ├─ 4. 코드 서명 설정
+  │     ├─ iOS: match (provisioning + 인증서)
+  │     └─ Android: keystore 복원
+  ├─ 5. 빌드
+  │     ├─ iOS: flutter build ipa --release
+  │     └─ Android: flutter build appbundle --release
+  ├─ 6. 스토어 업로드
+  │     ├─ iOS: upload_to_testflight
+  │     └─ Android: supply (internal track)
+  ├─ 7. Artifact 저장 (30일)
+  ├─ 8. GitHub Release 생성 + CHANGELOG
+  └─ 9. Slack 알림 (#deployments)
+```
+
+## Environment Configuration
+
+### Flavor/Scheme 기반 환경 분리
+
+```dart
+// lib/config/environment.dart
+enum Environment { dev, staging, prod }
+
+class EnvConfig {
+  final Environment env;
+  final String apiBaseUrl;
+  final String sentryDsn;
+  final bool enableAnalytics;
+
+  const EnvConfig({
+    required this.env,
+    required this.apiBaseUrl,
+    required this.sentryDsn,
+    required this.enableAnalytics,
+  });
+
+  static const dev = EnvConfig(
+    env: Environment.dev,
+    apiBaseUrl: 'https://api-dev.yourapp.com',
+    sentryDsn: '',
+    enableAnalytics: false,
+  );
+
+  static const staging = EnvConfig(
+    env: Environment.staging,
+    apiBaseUrl: 'https://api-staging.yourapp.com',
+    sentryDsn: 'https://xxx@sentry.io/staging',
+    enableAnalytics: false,
+  );
+
+  static const prod = EnvConfig(
+    env: Environment.prod,
+    apiBaseUrl: 'https://api.yourapp.com',
+    sentryDsn: 'https://xxx@sentry.io/prod',
+    enableAnalytics: true,
+  );
+}
+```
+
+### --dart-define 으로 빌드 시 주입
+
+```bash
+# Dev
+flutter run \
+  --dart-define=ENV=dev \
+  --dart-define=API_URL=https://api-dev.yourapp.com
+
+# Staging
+flutter build apk \
+  --dart-define=ENV=staging \
+  --dart-define=API_URL=https://api-staging.yourapp.com
+
+# Production
+flutter build appbundle \
+  --release \
+  --dart-define=ENV=prod \
+  --dart-define=API_URL=https://api.yourapp.com
+```
+
+```dart
+// 빌드 시 주입된 값 읽기
+class BuildConfig {
+  static const env = String.fromEnvironment('ENV', defaultValue: 'dev');
+  static const apiUrl = String.fromEnvironment('API_URL');
+
+  static bool get isProduction => env == 'prod';
+  static bool get isDev => env == 'dev';
+}
+```
+
+### CI 환경별 워크플로우
+
+```yaml
+# Codemagic: 환경별 워크플로우
+workflows:
+  dev-build:
+    triggering:
+      events: [push]
+      branch_patterns:
+        - pattern: "develop"
+    scripts:
+      - name: Build dev
+        script: |
+          flutter build apk --dart-define=ENV=dev
+
+  staging-build:
+    triggering:
+      events: [push]
+      branch_patterns:
+        - pattern: "release/*"
+    scripts:
+      - name: Build staging
+        script: |
+          flutter build appbundle --dart-define=ENV=staging
+
+  prod-build:
+    triggering:
+      events: [tag]
+      tag_patterns:
+        - pattern: "v*"
+    scripts:
+      - name: Build production
+        script: |
+          flutter build appbundle --release --dart-define=ENV=prod
+```
+
+## Secrets Management
+
+### 시크릿 분류
+
+```
+Level 1 — 최고 기밀 (유출 시 앱 탈취):
+├── Android keystore + 비밀번호
+├── iOS Distribution 인증서 + 개인키
+└── App Store Connect API Key (.p8)
+
+Level 2 — 기밀 (유출 시 서비스 악용):
+├── Google Play 서비스 계정 키
+├── Firebase 서비스 계정
+├── Sentry DSN (prod)
+└── match 암호화 비밀번호
+
+Level 3 — 일반 (유출 시 정보 노출):
+├── Slack Webhook URL
+├── Codecov Token
+└── Firebase App ID
+```
+
+### 시크릿 저장 위치
+
+```
+GitHub Actions:
+  Repository > Settings > Secrets and variables > Actions
+  ├── Repository secrets (레포 전체)
+  └── Environment secrets (환경별 분리)
+      ├── production (승인 필요 설정 가능)
+      └── staging
+
+Codemagic:
+  App Settings > Environment variables
+  ├── Variable groups (그룹별 관리)
+  └── Secure 체크 → 로그에 마스킹
+
+Fastlane:
+  .env 파일 (로컬) + CI 환경변수 (CI)
+  ├── .env.default (공통, .gitignore)
+  └── .env.production (.gitignore)
+```
+
+### 시크릿 접근 제한
+
+```yaml
+# GitHub Actions: 환경별 보호 규칙
+# Repository > Settings > Environments > production
+# ├── Required reviewers: 2명
+# ├── Wait timer: 5분
+# └── Deployment branches: main only
+
+jobs:
+  deploy-production:
+    runs-on: ubuntu-latest
+    environment: production  # 승인 필요
+    steps:
+      - name: Deploy
+        env:
+          # production 환경의 시크릿만 접근 가능
+          KEYSTORE: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
+        run: ...
+```
+
+## Rollback Procedures
+
+### iOS 롤백
+
+```
+App Store:
+1. 이전 버전으로 롤백 불가 (Apple 정책)
+2. 대안: 핫픽스 빌드를 새 버전으로 긴급 제출
+   - Expedited Review 요청 (App Store Connect)
+   - 심사 시간: 보통 24시간 → 긴급 시 수시간
+3. TestFlight: 이전 빌드 재활성화 가능
+
+긴급 핫픽스 절차:
+  git checkout -b hotfix/v1.2.4 v1.2.3
+  # 수정 적용
+  git tag v1.2.4
+  git push origin v1.2.4
+  # → CI 자동 빌드 → TestFlight 업로드 → 긴급 심사 요청
+```
+
+### Android 롤백
+
+```
+Play Store:
+1. Console > Release > Production > Release history
+2. 이전 릴리스의 "..." > "Release to Production"
+   (이전 버전을 새 릴리스로 재배포)
+3. 또는 단계적 출시 중이라면 "Halt rollout"
+
+자동 롤백 (Fastlane):
+  lane :rollback do |options|
+    version_code = options[:version_code]
+    # Play Store에서 이전 AAB 다운로드 후 재배포
+    # 또는 CI artifact에서 이전 빌드 가져와 재업로드
+    supply(
+      track: "production",
+      rollout: "1.0",
+      version_code: version_code,
+      json_key: ENV["GOOGLE_PLAY_JSON_KEY_PATH"],
+    )
+  end
+```
+
+### 롤백 판단 기준
+
+```
+즉시 롤백 (< 1시간 이내 판단):
+├── 크래시율 > 2% (이전 버전 대비 3배 이상 증가)
+├── ANR 비율 > 1%
+├── 결제/인증 등 핵심 기능 장애
+└── 데이터 손실 발생
+
+모니터링 후 판단 (24시간):
+├── 크래시율 1-2%
+├── 특정 기기/OS 버전에서만 발생
+├── 사용자 리뷰 평점 급락
+└── 비핵심 기능 장애
+
+유지 + 핫픽스:
+├── 크래시율 < 1% (경미)
+├── UI 버그 (기능 작동)
+└── 성능 저하 (크래시 아님)
+```
+
+## Common Pitfalls
+
+1. **빌드 넘버 충돌**: iOS/Android 빌드 넘버를 별도 관리 → 동일 CI 변수 사용 권장
+2. **캐시 오염**: Flutter/Gradle/CocoaPods 캐시가 오래되면 빌드 실패 → 주기적 캐시 무효화
+3. **시크릿 로그 노출**: `echo $SECRET` → CI 로그에 노출 → 항상 마스킹 확인
+4. **인증서 만료**: match 인증서 1년 만료 → 알림 설정 필수
+5. **Xcode 버전 차이**: CI와 로컬 Xcode 버전 불일치 → `xcode: 16.2` 고정
+6. **Gradle 메모리**: Android 빌드 OOM → `org.gradle.jvmargs=-Xmx4g` 설정
+7. **동시 빌드**: 같은 브랜치 여러 빌드 → `cancel_previous_builds` 설정
+8. **태그 실수**: 잘못된 태그 푸시 → production 빌드 트리거 → 태그 보호 규칙 설정

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

@@ -0,0 +1,106 @@
+---
+title: Code Signing
+impact: CRITICAL
+impactDescription: "서명 누락 → 스토어 업로드 불가, 키 유출 → 앱 탈취 위험"
+tags: code-signing, ios, android, provisioning, keystore, match
+---
+
+## Code Signing
+
+**Impact: CRITICAL (서명 누락 → 스토어 업로드 불가, 키 유출 → 앱 탈취 위험)**
+
+iOS provisioning profile, Android keystore 관리. CI 환경에서 안전한 서명 키 주입.
+
+### iOS 코드 서명 (match)
+
+**Incorrect (수동 관리):**
+```
+Xcode > Automatically manage signing 체크
+→ 개발자마다 다른 profile, CI 빌드 실패, 인증서 충돌
+```
+
+**Correct (match로 중앙 관리):**
+```ruby
+# fastlane/Matchfile
+git_url(ENV["MATCH_GIT_URL"])
+storage_mode("git")
+type("appstore")
+app_identifier("com.yourapp.id")
+
+# CI에서 실행
+create_keychain(
+  name: "ci_keychain",
+  password: ENV["KEYCHAIN_PASSWORD"],
+  default_keychain: true, unlock: true, timeout: 3600,
+)
+match(
+  type: "appstore",
+  keychain_name: "ci_keychain",
+  keychain_password: ENV["KEYCHAIN_PASSWORD"],
+  readonly: true,  # CI에서는 readonly — 인증서 생성 금지
+)
+```
+
+### Android 코드 서명
+
+**Incorrect (keystore를 레포에 포함):**
+```
+android/app/release.keystore  # 절대 금지!
+android/key.properties        # 비밀번호 하드코딩
+```
+
+**Correct (CI 환경변수로 주입):**
+```groovy
+// android/app/build.gradle
+android {
+    signingConfigs {
+        release {
+            if (System.getenv("ANDROID_KEYSTORE_BASE64")) {
+                storeFile file("../release.keystore")
+                storePassword System.getenv("ANDROID_KEYSTORE_PASSWORD")
+                keyAlias System.getenv("ANDROID_KEY_ALIAS")
+                keyPassword System.getenv("ANDROID_KEY_PASSWORD")
+            }
+        }
+    }
+}
+```
+
+```bash
+# CI에서 keystore 복원
+echo "$ANDROID_KEYSTORE_BASE64" | base64 --decode > android/release.keystore
+```
+
+### 개발/배포 인증서 분리
+
+```
+├── Development  — 디버그/테스트 (iOS provisioning, Android debug.keystore)
+├── Ad Hoc       — 내부 테스트 배포 (iOS only)
+└── Distribution — 스토어 제출 (iOS App Store, Android release.keystore)
+```
+
+### 키 로테이션
+
+- iOS: Apple 인증서 1년 만료 → `match nuke distribution` → `match appstore`
+- Android: Play App Signing 활성화 → Google이 앱 서명 키 관리, upload key만 팀 관리
+- Upload Key 분실 시 → Google Play Console에서 리셋 요청
+
+### .gitignore 필수 항목
+
+```gitignore
+*.mobileprovision
+*.p12
+*.cer
+*.keystore
+*.jks
+key.properties
+```
+
+### 규칙
+
+- `match` 로 iOS 인증서 관리 — 수동 Xcode 서명 관리 금지
+- CI에서 `match(readonly: true)` — 인증서 신규 생성 방지
+- Android keystore → base64 → CI 환경변수 주입
+- `key.properties` `.gitignore` 추가 — 레포 커밋 금지
+- Play App Signing 활성화 — upload key만 팀 관리
+- 개발/배포 인증서 분리 — 동일 인증서 혼용 금지

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

@@ -0,0 +1,116 @@
+---
+title: Codemagic Setup
+impact: HIGH
+impactDescription: "CI 미구성 → 수동 빌드, Codemagic 자동화 → Flutter 네이티브 지원"
+tags: codemagic, ci, yaml, workflow, artifact, trigger
+---
+
+## Codemagic Setup
+
+**Impact: HIGH (CI 미구성 → 수동 빌드, Codemagic 자동화 → Flutter 네이티브 지원)**
+
+codemagic.yaml 워크플로우 구성, 환경변수/시크릿, 빌드 트리거, artifact 배포.
+
+### codemagic.yaml
+
+**Incorrect (GUI만 사용):**
+```
+Codemagic 웹 UI에서 빌드 설정 → 코드 관리 불가, 롤백 불가, 팀 차이 발생
+```
+
+**Correct (yaml 코드 관리):**
+```yaml
+workflows:
+  ios-release:
+    name: iOS Release
+    max_build_duration: 30
+    instance_type: mac_mini_m2
+    environment:
+      groups: [ios_credentials, app_store_connect]
+      flutter: "3.27.0"
+      xcode: latest
+      cocoapods: default
+    triggering:
+      events: [tag]
+      tag_patterns:
+        - pattern: "v*"
+          include: true
+      cancel_previous_builds: true
+    scripts:
+      - name: Set up code signing
+        script: |
+          keychain initialize
+          app-store-connect fetch-signing-files $(BUNDLE_ID) --type IOS_APP_STORE --create
+          keychain add-certificates
+      - name: Build
+        script: |
+          xcode-project use-profiles
+          flutter packages pub get
+          flutter build ipa --release --build-number=$PROJECT_BUILD_NUMBER \
+            --export-options-plist=/Users/builder/export_options.plist
+    artifacts:
+      - build/ios/ipa/*.ipa
+    publishing:
+      app_store_connect:
+        auth: integration
+        submit_to_testflight: true
+      slack:
+        channel: "#deployments"
+        notify:
+          success: true
+          failure: true
+
+  android-release:
+    name: Android Release
+    instance_type: linux_x2
+    environment:
+      groups: [android_credentials, google_play]
+      flutter: "3.27.0"
+    triggering:
+      events: [tag]
+      tag_patterns:
+        - pattern: "v*"
+    scripts:
+      - name: Set up signing + Build
+        script: |
+          echo $ANDROID_KEYSTORE_BASE64 | base64 --decode > android/release.keystore
+          flutter packages pub get
+          flutter build appbundle --release --build-number=$PROJECT_BUILD_NUMBER
+    artifacts:
+      - build/app/outputs/bundle/release/*.aab
+    publishing:
+      google_play:
+        credentials: $GCLOUD_SERVICE_ACCOUNT_CREDENTIALS
+        track: internal
+
+  test:
+    name: Test & Analyze
+    instance_type: linux_x2
+    environment:
+      flutter: "3.27.0"
+    triggering:
+      events: [pull_request]
+    scripts:
+      - name: Test
+        script: |
+          flutter packages pub get && flutter analyze && flutter test --coverage
+```
+
+### 환경변수/시크릿
+
+```
+Codemagic UI > Environment variables:
+├── ios_credentials: CERTIFICATE_PRIVATE_KEY, BUNDLE_ID, PROVISIONING_PROFILE
+├── app_store_connect: ASC_KEY_ID, ASC_ISSUER_ID, ASC_API_KEY (.p8)
+├── android_credentials: ANDROID_KEYSTORE_BASE64, PASSWORD, ALIAS, KEY_PASSWORD
+└── google_play: GCLOUD_SERVICE_ACCOUNT_CREDENTIALS (JSON)
+```
+
+### 규칙
+
+- `codemagic.yaml` 로 워크플로우 정의 — GUI 설정 대신 코드 관리
+- 시크릿은 Codemagic UI에서만 설정 — yaml에 비밀값 금지
+- `instance_type: mac_mini_m2` — iOS 빌드는 macOS 필수
+- `cancel_previous_builds: true` — 동일 브랜치 중복 빌드 방지
+- PR → test, 태그 → release 워크플로우 분리
+- `PROJECT_BUILD_NUMBER` 활용 — 자동 증가 빌드 넘버