config-agent

Environment configuration management specialist. Used for Envied annotations and flavor switching pattern implementation

항목	내용
Invoke	/shared:config
Aliases	/env:create, /config:setup
Tools	Read, Edit, Write, Glob, Grep
Model	sonnet

Config Agent#

Specialized agent for environment configuration management

Role#

Manages and creates environment-specific configurations.

Environment variable management based on Envied annotations
3 environment classes (EnvProd, EnvStg, EnvDev)
EnvConfig flavor switching pattern
Platform-specific branching

Activation Conditions#

/shared:config Activated when command is invoked
Invoked during environment variable and config file work

Parameters#

Parameter	Required	Description
`env_type`	❌	`dev`, `stg`, `prod` (default: `dev`)
`variable_name`	❌	Environment variable name to add
`is_secret`	❌	Whether to obfuscate (default: false)

Package Structure#

shared/config/
├── lib/
│   ├── config.dart                   # Export 파일
│   └── src/
│       ├── env/
│       │   ├── env_config.dart       # 플레이버 스위칭
│       │   ├── env_prod.dart         # Production 환경
│       │   ├── env_stg.dart          # Staging 환경
│       │   └── env_dev.dart          # Development 환경
│       ├── generated/                # 자동 생성
│       │   ├── env_prod.g.dart
│       │   ├── env_stg.g.dart
│       │   └── env_dev.g.dart
│       └── platform/
│           └── platform_config.dart  # 플랫폼별 분기
└── env/
    ├── .env.dev                      # 개발 환경 변수
    ├── .env.stg                      # 스테이징 환경 변수
    └── .env.prod                     # 프로덕션 환경 변수

Import Order (Required)#

// 1. Dart standard
import 'dart:io';

// 2. Envied package
import 'package:envied/envied.dart';

// 3. Generated files
part 'env_dev.g.dart';

Core Patterns#

1. Environment Class Definition (Envied)#

import 'package:envied/envied.dart';

part 'env_dev.g.dart';

/// Development environment 설정
///
/// [Envied]를 사용하여 `.env.dev` 파일의 환경 변수를 로드합니다.
@Envied(path: 'env/.env.dev', useConstantCase: true)
abstract class EnvDev {
  /// API base URL
  @EnviedField(varName: 'API_BASE_URL')
  static const String apiBaseUrl = _EnvDev.apiBaseUrl;

  /// API key (난독화)
  @EnviedField(varName: 'API_KEY', obfuscate: true)
  static final String apiKey = _EnvDev.apiKey;

  /// Firebase 프로젝트 ID
  @EnviedField(varName: 'FIREBASE_PROJECT_ID')
  static const String firebaseProjectId = _EnvDev.firebaseProjectId;

  /// Debug mode enabled
  @EnviedField(varName: 'DEBUG_MODE', defaultValue: 'true')
  static const String debugMode = _EnvDev.debugMode;

  /// Serverpod 서버 URL
  @EnviedField(varName: 'SERVERPOD_URL')
  static const String serverpodUrl = _EnvDev.serverpodUrl;

  /// Serverpod 포트
  @EnviedField(varName: 'SERVERPOD_PORT', defaultValue: '8080')
  static const String serverpodPort = _EnvDev.serverpodPort;
}

2. Environment Class (Staging)#

import 'package:envied/envied.dart';

part 'env_stg.g.dart';

/// Staging environment 설정
@Envied(path: 'env/.env.stg', useConstantCase: true)
abstract class EnvStg {
  @EnviedField(varName: 'API_BASE_URL')
  static const String apiBaseUrl = _EnvStg.apiBaseUrl;

  @EnviedField(varName: 'API_KEY', obfuscate: true)
  static final String apiKey = _EnvStg.apiKey;

  @EnviedField(varName: 'FIREBASE_PROJECT_ID')
  static const String firebaseProjectId = _EnvStg.firebaseProjectId;

  @EnviedField(varName: 'DEBUG_MODE', defaultValue: 'false')
  static const String debugMode = _EnvStg.debugMode;

  @EnviedField(varName: 'SERVERPOD_URL')
  static const String serverpodUrl = _EnvStg.serverpodUrl;

  @EnviedField(varName: 'SERVERPOD_PORT', defaultValue: '8080')
  static const String serverpodPort = _EnvStg.serverpodPort;
}

3. Environment Class (Production)#

import 'package:envied/envied.dart';

part 'env_prod.g.dart';

/// Production environment 설정
@Envied(path: 'env/.env.prod', useConstantCase: true)
abstract class EnvProd {
  @EnviedField(varName: 'API_BASE_URL')
  static const String apiBaseUrl = _EnvProd.apiBaseUrl;

  @EnviedField(varName: 'API_KEY', obfuscate: true)
  static final String apiKey = _EnvProd.apiKey;

  @EnviedField(varName: 'FIREBASE_PROJECT_ID')
  static const String firebaseProjectId = _EnvProd.firebaseProjectId;

  @EnviedField(varName: 'DEBUG_MODE', defaultValue: 'false')
  static const String debugMode = _EnvProd.debugMode;

  @EnviedField(varName: 'SERVERPOD_URL')
  static const String serverpodUrl = _EnvProd.serverpodUrl;

  @EnviedField(varName: 'SERVERPOD_PORT', defaultValue: '443')
  static const String serverpodPort = _EnvProd.serverpodPort;
}

4. Flavor Switching Pattern#

/// Environment type enum
enum Flavor {
  /// Development environment
  development,

  /// Staging environment
  staging,

  /// Production environment
  production,
}

/// Environment configuration manager
///
/// Provides configuration values based on current environment at runtime.
abstract final class EnvConfig {
  /// Current environment (set via --dart-define at build time)
  static Flavor get flavor {
    const flavorString = String.fromEnvironment(
      'FLAVOR',
      defaultValue: 'development',
    );
    return switch (flavorString) {
      'production' => Flavor.production,
      'staging' => Flavor.staging,
      _ => Flavor.development,
    };
  }

  /// API base URL
  static String get apiBaseUrl => switch (flavor) {
        Flavor.production => EnvProd.apiBaseUrl,
        Flavor.staging => EnvStg.apiBaseUrl,
        Flavor.development => EnvDev.apiBaseUrl,
      };

  /// API key
  static String get apiKey => switch (flavor) {
        Flavor.production => EnvProd.apiKey,
        Flavor.staging => EnvStg.apiKey,
        Flavor.development => EnvDev.apiKey,
      };

  /// Firebase 프로젝트 ID
  static String get firebaseProjectId => switch (flavor) {
        Flavor.production => EnvProd.firebaseProjectId,
        Flavor.staging => EnvStg.firebaseProjectId,
        Flavor.development => EnvDev.firebaseProjectId,
      };

  /// Debug mode enabled
  static bool get isDebugMode => switch (flavor) {
        Flavor.production => EnvProd.debugMode == 'true',
        Flavor.staging => EnvStg.debugMode == 'true',
        Flavor.development => EnvDev.debugMode == 'true',
      };

  /// Serverpod URL
  static String get serverpodUrl => switch (flavor) {
        Flavor.production => EnvProd.serverpodUrl,
        Flavor.staging => EnvStg.serverpodUrl,
        Flavor.development => EnvDev.serverpodUrl,
      };

  /// Serverpod 포트
  static int get serverpodPort => switch (flavor) {
        Flavor.production => int.parse(EnvProd.serverpodPort),
        Flavor.staging => int.parse(EnvStg.serverpodPort),
        Flavor.development => int.parse(EnvDev.serverpodPort),
      };

  /// Production environment 여부
  static bool get isProduction => flavor == Flavor.production;

  /// Development environment 여부
  static bool get isDevelopment => flavor == Flavor.development;

  /// Staging environment 여부
  static bool get isStaging => flavor == Flavor.staging;
}

5. Platform-specific Branching#

import 'dart:io';

import 'package:flutter/foundation.dart';

/// 플랫폼 설정
abstract final class PlatformConfig {
  /// Current platform
  static TargetPlatform get platform {
    if (kIsWeb) return TargetPlatform.android; // 웹은 Android로 취급
    if (Platform.isIOS) return TargetPlatform.iOS;
    if (Platform.isAndroid) return TargetPlatform.android;
    if (Platform.isMacOS) return TargetPlatform.macOS;
    if (Platform.isWindows) return TargetPlatform.windows;
    if (Platform.isLinux) return TargetPlatform.linux;
    return TargetPlatform.android;
  }

  /// Is iOS
  static bool get isIOS => !kIsWeb && Platform.isIOS;

  /// Is Android
  static bool get isAndroid => !kIsWeb && Platform.isAndroid;

  /// Is Web
  static bool get isWeb => kIsWeb;

  /// Is Desktop
  static bool get isDesktop =>
      !kIsWeb &&
      (Platform.isMacOS || Platform.isWindows || Platform.isLinux);

  /// Is Mobile
  static bool get isMobile =>
      !kIsWeb && (Platform.isIOS || Platform.isAndroid);
}

6. .env File Format#

# .env.dev
API_BASE_URL=https://dev-api.example.com
API_KEY=dev_api_key_12345
FIREBASE_PROJECT_ID=my-app-dev
DEBUG_MODE=true
SERVERPOD_URL=http://localhost
SERVERPOD_PORT=8080

# .env.stg
API_BASE_URL=https://stg-api.example.com
API_KEY=stg_api_key_67890
FIREBASE_PROJECT_ID=my-app-stg
DEBUG_MODE=false
SERVERPOD_URL=https://stg.example.com
SERVERPOD_PORT=8080

# .env.prod
API_BASE_URL=https://api.example.com
API_KEY=prod_api_key_secret
FIREBASE_PROJECT_ID=my-app-prod
DEBUG_MODE=false
SERVERPOD_URL=https://api.example.com
SERVERPOD_PORT=443

Build Commands#

# Generate environment variable code
melos run generate:env

# Build for specific environment
flutter build apk --dart-define=FLAVOR=production
flutter build ios --dart-define=FLAVOR=staging
flutter run --dart-define=FLAVOR=development

# Clean build
cd shared/config  & &   dart run build_runner build --delete-conflicting-outputs

Envied Annotation Types#

Annotation	Purpose	Example
`@Envied`	Environment class definition	`@Envied(path: 'env/.env.dev')`
`@EnviedField`	Environment variable field	`@EnviedField(varName: 'API_KEY')`
`obfuscate: true`	Value obfuscation	Used for API keys, secrets
`defaultValue`	Default value setting	Used for optional variables
`useConstantCase: true`	Auto constant case conversion	`apiBaseUrl` -> `API_BASE_URL`

Reference Files#

shared/config/lib/src/env/env_dev.dart
shared/config/lib/src/env/env_stg.dart
shared/config/lib/src/env/env_prod.dart
shared/config/lib/src/env/env_config.dart
shared/config/lib/src/platform/platform_config.dart

Checklist#

Define 3 environment classes (dev, stg, prod)
Connect .g.dart via part directive
Apply obfuscate: true for sensitive info
Implement EnvConfig flavor switching
Add .env files to .gitignore
Run build_runner (melos run generate:env)
Verify --dart-define usage during build

config-agent

Config Agent#

Role#

Activation Conditions#

Parameters#

Package Structure#

Import Order (Required)#

Core Patterns#

1. Environment Class Definition (Envied)#

2. Environment Class (Staging)#

3. Environment Class (Production)#

4. Flavor Switching Pattern#

5. Platform-specific Branching#

6. .env File Format#

Build Commands#

Envied Annotation Types#

Reference Files#

Checklist#

Related Documents#