Binding Gating — flutter-skill 바인딩 활성 조건 표준

flutter-skill 의 FlutterSkillBinding 은 개발 탐색 빌드 에서만 활성화되고, Patrol integration_test / staging / production 에는 절대 포함되지 않아야 한다.

1. 원칙#

• Single-purpose binding: flutter-skill 바인딩은 exploration 목적에만 사용
• Compile-time gated: kDebugMode 분기는 release/profile 빌드에서 tree-shaken (kobic: 별도 환경변수 불필요)
• Mutual exclusion with Patrol: Patrol integration_test 실행 중에는 절대 로드 금지
• Production zero-trace: release 빌드의 바이너리에 flutter_skill 심볼이 존재하면 실패

2. main.dart 표준 패턴#

// app/{app_name}/lib/main.dart
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:flutter_skill/flutter_skill.dart';

void main() {
  _bootstrapFlutterSkillIfEnabled();
  runApp(const MyApp());
}

// kDebugMode 게이팅 → release/profile 빌드에서 tree-shaken (kobic: 별도 환경변수 불필요)
void _bootstrapFlutterSkillIfEnabled() {
  // Patrol integration_test 는 자체 entrypoint(integration_test/*.dart)로 구동되어
  // 이 lib/main.dart 의 main() 을 호출하지 않으므로 Patrol 과 자연 상호배타.
  if (kDebugMode) {
    FlutterSkillBinding.ensureInitialized();
  }
}

3. 플레이버별 허용#

4. 기동 명령#

debug 실행 (개발/탐색 공통)#

flutter run --debug --flavor dev
# kDebugMode=true → flutter-skill 바인딩 자동 활성 (별도 --dart-define 불필요)
# 실제 탐색 사용은 flutter-skill MCP 서버 토글(§5)로 게이트

Patrol integration_test#

patrol test \
  --target integration_test/scenarios/sign_in_email_login_success_test.dart
# Patrol 이 자체 IntegrationTestBinding + 자체 entrypoint 구동 → lib/main.dart 바인딩 미실행

5. MCP 서버 토글#

.mcp.json:

{
   " mcpServers " : {
     " patrol " : {
       " command " :  " .claude/run-patrol " 
     },
     " flutter-skill " : {
       " command " :  " flutter-skill " ,
       " args " : [ " server " ],
       " disabledByDefault " : true
    }
  }
}

• flutter-skill 은 disabledByDefault: true — Claude 가 /e2e:explore 진입 시에만 enable
• /e2e:lock 시 다시 disable
• e2e-authoring-agent 가 토글 상태를 추적 (상호 배타)

6. pubspec 위치#

flutter_skill 은 반드시 dev_dependencies 에 위치:

# app/{app_name}/pubspec.yaml
dev_dependencies:
  flutter_skill: ^0.9.36
  patrol: ^4.5.0
  patrol_mcp: ^0.1.2

dependencies 에 두면 release 빌드에 포함될 위험 — CI 검증으로 차단.

7. CI 검증#

다음 체크를 CI 에 포함 (현재는 제안, 별도 워크플로우):

release 바이너리 검사#

# release AAB/IPA 에 flutter_skill 심볼 잔존 여부
grep -r  " FlutterSkillBinding "   build/app/outputs/  & &   exit 1 || true

pubspec 위치 검사#

# flutter_skill 이 dependencies 에 있으면 실패
yq  ' .dependencies.flutter_skill '   app/**/pubspec.yaml | grep -v null  & &   exit 1 || true

Patrol 실행 중 flutter-skill 바인딩 차단#

Patrol 은 integration_test/*.dart 자체 entrypoint 로 구동되어 앱의 lib/main.dart main()(= _bootstrapFlutterSkillIfEnabled)을 호출하지 않으므로 바인딩이 자동 활성화되지 않는다. 방어적으로, Patrol 초기화 경로에서 FlutterSkillBinding 를 import/init 하지 않는다(§8):

Future<void> initializeApp(PatrolIntegrationTester $) async {
  // FlutterSkillBinding 를 test/Patrol 경로에서 import·init 하지 말 것.
  // (kobic 의 Patrol 컨텍스트 감지 API 가 있으면 그것으로 추가 방어 권장)
  // ... 나머지 초기화
}

8. 금지 사항#

• ❌ dependencies 섹션에 flutter_skill 포함 (반드시 dev_dependencies)
• ❌ Patrol 테스트 내에서 FlutterSkillBinding import / init
• ❌ kDebugMode 외의 런타임 플래그로 release/profile 에 바인딩 노출
• ❌ assert/!kReleaseMode 등 release 에서 tree-shake 안 되는 게이트 사용 (반드시 kDebugMode)

9. 탐색 중 빌드 전환 플로우#

개발자의 일반 작업 흐름:

1. 일반 개발/탐색: flutter run --debug (kDebugMode → 바인딩 활성, 별도 플래그 불필요)
2. 탐색 시작: /e2e:explore 호출 시 agent 가 flutter-skill MCP 서버를 enable (§5)
3. 탐색 완료: /e2e:lock 시 MCP 서버 disable (앱 재기동 불필요)

참고#

• tree-shaking 확인: flutter build apk --release --analyze-size 로 flutter_skill 심볼 부재 확인
• Patrol + flutter-skill 동시 기동 시 VM Service isolate 충돌 실험 결과가 있으면 issue 로 기록
• 웹 빌드(flutter_skill_web_interop.dart) 는 dart.library.js_interop 조건부 import — 문제 없음