LogoSkills

route-agent

GoRouter TypedRoute 설정 생성 전문가입니다. 라우트 정의와 내비게이션 패턴 구현에 사용합니다.

/app:route — 화면 길 안내(라우트) 자동 생성기#

항목내용
실행 명령/app:route
별칭/route:create, /nav:setup
모델sonnet
사용 도구 Read, Edit, Write, Glob, Grep
연계 스킬flutter-ui

한마디로#

앱의 화면과 화면을 잇는 "길 안내 지도"를 자동으로 만들어 주는 도구입니다. 건물에 새 방을 만들면 "이 방으로 가려면 몇 층 몇 호" 하는 주소와 이동 통로가 필요하듯, 새 화면을 추가할 때 그 화면으로 가는 주소(경로)와 이동 방식(전환 효과)을 코드로 만들어 줍니다.

누가·언제 쓰나요#

  • 앱에 새 화면을 추가하고 그 화면으로 이동하는 길을 연결해야 하는 개발자
  • /app:route 명령을 직접 실행할 때
  • 큰 기능을 한 번에 만드는 /cc-flutter:feature:create 작업이 진행되는 중, 화면(Presentation) 단계에서 자동으로 호출될 때

무엇을 해주나요#

feature/{앱종류}/{기능이름}/lib/src/route/ 폴더 아래에 화면 길 안내 파일 3개를 만들어 줍니다.

  • route.dart — 묶음(내보내기) 파일
  • {기능이름}_route.dart — 실제 길(경로) 정의
  • {기능이름}_route.g.dart — 자동 생성되는 파일(build_runner가 만듦)

여기에는 화면 주소(예: /store), 상세 화면 주소(예: /store/3), 화면이 바뀔 때의 전환 효과(은은하게 바뀜·옆에서 밀려옴·효과 없음) 등이 담깁니다.

어떻게 쓰나요#

# 기본 사용 (기능 이름만 지정)
/app:route   # feature_name 지정 (snake_case, 예: store)

# 별칭(같은 기능)
/route:create
/nav:setup

지정할 수 있는 값(파라미터):

  • feature_name (필수) — 기능 모듈 이름(snake_case)
  • route_type (선택) — app 또는 console (기본값 app)
  • transition (선택) — 화면 전환 효과 fade(은은하게) / slide(밀려옴) / none(효과 없음) (기본값 fade)
  • nested_routes (선택) — 화면 안의 하위 화면 목록

안에서 무슨 일이 벌어지나요#

  1. 화면 주소표(TypedGoRoute)를 붙여 각 화면이 어떤 주소로 열리는지 정의합니다.
  2. 일반 앱 화면, 어드민 콘솔 화면, 상세(하위) 화면 등 상황에 맞는 길 정의 코드를 골라 만들어 줍니다.
  3. 화면 전환 효과(은은하게/밀려옴/효과 없음)를 상황에 맞게 선택합니다.
  4. 같은 화면이 중복되지 않고 올바르게 다시 그려지도록 화면마다 고유한 식별 키를 생성합니다.
  5. 주소에 딸려 오는 추가 정보(쿼리 파라미터, 예: 검색어·필터)를 읽어 처리합니다.
  6. 마지막으로 자동 생성 파일을 연결하고, melos run build(build_runner)를 실행해 나머지 코드를 완성합니다.
⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Role#

Generates GoRouter-based TypedRoute configuration.

  • TypedGoRoute annotation definition
  • GoRouteData class implementation
  • RouteName abstract class pattern
  • Transition page configuration
  • Nested route structure

Activation Conditions#

  • /app:route Activated when command is invoked
  • Called after /cc-flutter:feature:create orchestration Presentation Phase

Parameters#

ParameterRequiredDescription
feature_name✅Feature module name (snake_case)
route_type❌app, console (default: app)
transition❌fade, slide, none (default: fade)
nested_routes❌Nested Route List

Generated Files#

feature/{app_type}/{feature_name}/lib/src/route/
├── route.dart                    # Export 파일
├── {feature_name}_route.dart     # 라우트 정의
└── {feature_name}_route.g.dart   # 자동 생성 (build_runner)

Import Order (Required)#

// 1. Feature package (page import)
import 'package:{feature_name}/{feature_name}.dart';

// 2. Dependency packages
import 'package:dependencies/dependencies.dart';

// 3. Core (transition pages)
import 'package:core/core.dart';

// 4. Generated files
part '{feature_name}_route.g.dart';

Core Patterns#

1. App Route Definition (FadeTransitionPage)#

part '{feature_name}_route.g.dart';

/// {Feature} 화면 라우트 정의
///
/// 앱의 {feature} 화면으로 연결됩니다.
/// 애니메이션 효과로 [FadeTransitionPage]를 사용합니다.
@TypedGoRoute<{Feature}Route>(
  path: {Feature}RouteName.path,
  routes: [
    // in progress첩 라우트 정의
    TypedGoRoute<{Feature}DetailRoute>(
      path: {Feature}DetailRoute.path,
    ),
  ],
)
class {Feature}Route extends GoRouteData with ${Feature}Route {
  /// {Feature} 화면 라우트 생성자
  const {Feature}Route({this.initialId});

  /// 초기 ID (선택사항)
  final int? initialId;

  /// {Feature} 화면 라우트 경로
  static const String path = {Feature}RouteName.path;

  static const LocalKey _key = ValueKey(path);

  @override
  FadeTransitionPage buildPage(BuildContext context, GoRouterState state) {
    return FadeTransitionPage(
      key: _key,
      child: {Feature}Page(initialId: initialId),
    );
  }
}

2. Console Route Definition (NoTransitionPage)#

/// Console {Feature} 화면 라우트 정의
///
/// 어드민 콘솔의 {feature} 화면으로 연결됩니다.
/// 트랜지션 없이 [NoTransitionPage]를 사용합니다.
@TypedGoRoute<Console{Feature}Route>(
  path: Console{Feature}RouteName.path,
  routes: [
    TypedGoRoute<{Feature}DetailRoute>(
      path: {Feature}DetailRoute.path,
    ),
  ],
)
class Console{Feature}Route extends GoRouteData with $Console{Feature}Route {
  /// Console{Feature} 화면 라우트 생성자
  const Console{Feature}Route();

  /// Console{Feature} default 경로
  static RouteBase get base => Console{Feature}RouteName.base;

  @override
  Page<void> buildPage(BuildContext context, GoRouterState state) {
    // 🔑 동적 key 생성 (쿼리 변화에 따라 페이지 재생성)
    final query = state.uri.query;
    final pageKey = ValueKey(
      'console_{feature}_list-${query.isNotEmpty ? query : 'noq'}',
    );

    return NoTransitionPage<void>(
      key: pageKey,
      child: const Console{Feature}Page(),
    );
  }
}

3. RouteName Abstract Class Pattern#

/// {Feature} 라우트 경로 이름을 정의하는 추상 클래스
///
/// [path]는 '/{feature}'로 설정되어 {feature} 화면의 경로로 사용됩니다.
abstract class {Feature}RouteName {
  /// {Feature} 화면 라우트 베이스
  static RouteBase get base => ${featureCamel}Route;

  /// {Feature} 화면 라우트 경로
  static const String path = '/{feature}';

  /// {Feature} 화면 라우트 이름
  static const String name = '{feature}';
}

4. Nested Route Definition#

/// {Feature} 상세 화면 라우트 정의
///
/// 실제 경로는 '/{feature}/{id}'가 됩니다.
@immutable
class {Feature}DetailRoute extends GoRouteData with ${Feature}DetailRoute {
  /// {Feature} 상세 화면 라우트 생성자
  const {Feature}DetailRoute({required this.id});

  /// 조회할 {feature}의 ID
  final int id;

  /// {Feature} 상세 화면 라우트 경로
  static const String path = ':id';

  @override
  FadeTransitionPage buildPage(BuildContext context, GoRouterState state) {
    // id와 전체 쿼리 문자열을 포함하여 고유한 키 생성
    final fullPath = state.uri.toString();
    final pageKey = ValueKey('{feature}Detail/$fullPath');

    return FadeTransitionPage(
      key: pageKey,
      child: {Feature}DetailPage(id: id),
    );
  }
}

5. Query Parameter Parsing Helpers#

/// 쿼리 파라미터에서 정수 값을 파싱하는 헬퍼 함수
int? _parseIntQueryParam(String? value) {
  return value != null ? int.tryParse(value) : null;
}

/// 쿼리 파라미터에서 불리언 값을 파싱하는 헬퍼 함수
bool _parseBoolQueryParam(String? value) {
  return value?.toLowerCase() == 'true';
}

6. Route Constants Definition#

/// 라우트 상수 정의 (private)
abstract class _RouteConstants {
  /// Detail 라우트 식별자
  static const String detail = 'detail';

  /// 편집 라우트 식별자
  static const String edit = 'edit';

  /// 추가 라우트 식별자
  static const String add = 'add';
}

Transition Page Types#

TypeClassWhere Used
FadeFadeTransitionPageApp general screens
SlideSlideTransitionPageModal, detail screens
NoneNoTransitionPageConsole, tab switching

Reference Files#

feature/application/store/lib/src/route/store_route.dart
feature/console/console_member_list/lib/src/route/console_member_list_route.dart
feature/application/app_router/lib/src/route/app_routes.dart
package/core/lib/src/transition/

Checklist#

  • TypedGoRoute Annotation Definition
  • GoRouteData extends + mixin Apply
  • Define RouteName abstract Class
  • Select appropriate transition Page
  • Generate unique ValueKey
  • Handle query parameters
  • Write KDoc comments
  • Connect .g.dart via part directive
  • build_runner Execution (melos run build)