Claude Code Flutter跨平台移动开发全实战

npm install -g @anthropic-ai/claude-code
claude --version

flutter doctor -v
# 确保至少 iOS Simulator 和 Android Emulator 均为 ✓

flutter create --org com.example --project-name taskflow \
  --platforms android,ios,web,macos taskflow_app
cd taskflow_app

# TaskFlow - Claude Code 项目指引

## 技术栈
- Flutter 3.29+ / Dart 3.8+
- 状态管理: Riverpod (flutter_riverpod)
- 路由: go_router
- 网络层: dio + retrofit
- 本地存储: drift (SQLite)
- 序列化: freezed + json_serializable

## 架构规范
- 采用 Feature-First Clean Architecture
- 每个feature目录结构: presentation/ domain/ data/ widgets/
- presentation层: Provider + ConsumerWidget/ConsumerStatefulWidget
- domain层: Entity + Repository接口 + UseCase
- data层: Repository实现 + DataSource + Model
- 严禁跨feature直接引用，必须通过domain层接口

## 命名约定
- 文件: snake_case (task_list_page.dart)
- 类: PascalCase (TaskListPage)
- Provider: camelCaseProvider 后缀 (taskListProvider)
- 路由: /feature/action 格式 (/tasks/detail)
- 常量: camelCase (kDefaultTimeout)

## 测试要求
- 单元测试: domain层所有UseCase和Entity
- Widget测试: 每个页面至少3个测试
- 集成测试: 核心用户流程
- 测试文件路径: test/ 目录镜像 lib/ 结构

## 代码生成
- 修改freezed/json_serializable模型后运行:
  dart run build_runner build --delete-conflicting-outputs
- 不要手动编辑 *.g.dart / *.freezed.dart 文件

## 禁止事项
- 不要在Widget内写业务逻辑
- 不要在presentation层直接导入data层
- 不要使用setState管理跨组件状态
- 不要硬编码字符串，使用ARb国际化

claude

根据CLAUDE.md中的架构规范，为TaskFlow应用创建完整的Feature-First目录结构。
应用包含3个核心feature：auth（认证）、tasks（任务管理）、profile（个人中心）。
每个feature包含presentation/domain/data三层。
同时创建共享层：core/theme、core/network、core/utils。

lib/
├── core/
│   ├── theme/
│   │   ├── app_theme.dart
│   │   └── color_tokens.dart
│   ├── network/
│   │   ├── dio_client.dart
│   │   └── api_interceptor.dart
│   └── utils/
│       ├── validators.dart
│       └── extensions/
├── features/
│   ├── auth/
│   │   ├── presentation/
│   │   │   ├── pages/
│   │   │   ├── widgets/
│   │   │   └── providers/
│   │   ├── domain/
│   │   │   ├── entities/
│   │   │   ├── repositories/
│   │   │   └── usecases/
│   │   └── data/
│   │       ├── models/
│   │       ├── datasources/
│   │       └── repositories/
│   ├── tasks/
│   │   └── (同auth结构)
│   └── profile/
│       └── (同auth结构)
├── app.dart
└── main.dart

配置go_router路由，包含以下路由表：
- /splash → SplashPage
- /login → LoginPage
- /register → RegisterPage
- /tasks → TaskListPage（需认证守卫）
- /tasks/detail/:id → TaskDetailPage（需认证守卫）
- /tasks/create → TaskCreatePage（需认证守卫）
- /profile → ProfilePage（需认证守卫）
使用Riverpod的Provider来管理认证状态，未登录自动重定向到/login。

// lib/core/router/app_router.dart
final routerProvider = Provider<GoRouter>((ref) {
  final authState = ref.watch(authStateProvider);
  return GoRouter(
    initialLocation: '/splash',
    redirect: (context, state) {
      final isLoggedIn = authState.valueOrNull != null;
      final isAuthRoute = state.matchedLocation.startsWith('/login') ||
          state.matchedLocation.startsWith('/register');
      if (!isLoggedIn && !isAuthRoute) return '/login';
      if (isLoggedIn && isAuthRoute) return '/tasks';
      return null;
    },
    routes: [
      GoRoute(path: '/splash', builder: (_, __) => const SplashPage()),
      GoRoute(path: '/login', builder: (_, __) => const LoginPage()),
      GoRoute(path: '/register', builder: (_, __) => const RegisterPage()),
      ShellRoute(
        builder: (_, __, child) => MainShell(child: child),
        routes: [
          GoRoute(path: '/tasks', builder: (_, __) => const TaskListPage()),
          GoRoute(
            path: '/tasks/detail/:id',
            builder: (_, state) => TaskDetailPage(id: state.pathParameters['id']!),
          ),
          GoRoute(path: '/tasks/create', builder: (_, __) => const TaskCreatePage()),
          GoRoute(path: '/profile', builder: (_, __) => const ProfilePage()),
        ],
      ),
    ],
  );
});

实现auth feature的完整三层代码：

Domain层：
- User entity (freezed)
- AuthRepository 抽象类 (login, register, logout, getCurrentUser)
- LoginUseCase, RegisterUseCase, GetCurrentUserUseCase

Data层：
- UserModel (freezed + json_serializable)
- AuthRemoteDataSource (dio + retrofit)
- AuthLocalDataSource (drift 缓存token)
- AuthRepositoryImpl 实现

Presentation层：
- AuthState (freezed: authenticated/unauthenticated/loading/error)
- authStateProvider (StreamProvider 监听认证状态)
- LoginPage (ConsumerWidget + 表单验证)
- RegisterPage

API端点：
- POST /auth/login {email, password}
- POST /auth/register {email, password, name}
- GET /auth/me (Bearer token)

确保所有代码遵循CLAUDE.md规范。

// lib/features/auth/domain/entities/user.dart
@freezed
class User with _$User {
  const factory User({
    required String id,
    required String email,
    required String name,
    String? avatarUrl,
    required DateTime createdAt,
  }) = _User;

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
}

// lib/features/auth/presentation/providers/auth_provider.dart
@riverpod
class AuthState extends _$AuthState {
  @override
  FutureOr<AuthValue> build() {
    return ref.watch(getCurrentUserUseCaseProvider).call();
  }

  Future<void> login(String email, String password) async {
    state = const AsyncLoading();
    state = await AsyncValue.guard(() async {
      final user = await ref.read(loginUseCaseProvider).call(email, password);
      return user;
    });
  }

  Future<void> logout() async {
    await ref.read(logoutUseCaseProvider).call();
    state = const AsyncData(Unauthenticated());
  }
}

实现tasks feature的完整CRUD功能：

- Task entity: id, title, description, status(todo/inProgress/done), priority(low/medium/high), dueDate, createdAt, updatedAt
- TaskListPage: 下拉刷新 + 无限滚动加载 + 按状态筛选的Chip组
- TaskCreatePage: 表单 + 日期选择器 + 优先级选择
- TaskDetailPage: 详情展示 + 状态切换 + 删除确认

使用SliverAppBar实现任务列表页面的响应式头部。
列表项使用Dismissible实现滑动删除。

flutter run -d macos  # 或 -d ios / -d android
# 可以看到完整的应用流程：登录 → 任务列表 → 创建任务 → 任务详情
flutter analyze       # 0 issues found
dart run build_runner build --delete-conflicting-outputs  # 生成成功

# 克隆Agent集合到项目
git clone https://github.com/cleydson/flutter-claude-code.git .claude/flutter-agents

# 或者选择性安装核心Agent
mkdir -p .claude/agents
# 只拷贝你需要的Agent
cp flutter-claude-code/.claude/agents/flutter-architect.md .claude/agents/
cp flutter-claude-code/.claude/agents/flutter-testing.md .claude/agents/
cp flutter-claude-code/.claude/agents/flutter-debug.md .claude/agents/

@flutter-testing 为tasks feature的TaskListPage编写完整的Widget测试，
包含：正常渲染、空状态、加载状态、下拉刷新、筛选切换五个场景。
使用Mocktail mock所有依赖的Provider。

graph TD
    A["Golden Tests<br/>UI回归快照<br/>数量: 少"] --> B["Integration Tests<br/>端到端用户流程<br/>数量: 中"]
    B --> C["Widget Tests<br/>组件交互验证<br/>数量: 多"]
    C --> D["Unit Tests<br/>纯逻辑验证<br/>数量: 最多"]

    style A fill:#ff6b6b,color:#fff
    style B fill:#ffd93d,color:#333
    style C fill:#6bcb77,color:#fff
    style D fill:#4d96ff,color:#fff

@flutter-testing 为TaskListPage生成四层测试：

1. Unit Test: TaskListUseCase 的 execute 方法
2. Widget Test: TaskListPage 渲染、空状态、加载态、错误态
3. Integration Test: 登录→创建任务→查看任务列表 完整流程
4. Golden Test: 任务列表项的视觉快照

测试依赖：
- mocktail 做 mock
- flutter_test 内置golden比对
- integration_test 包做集成测试

// test/features/tasks/presentation/pages/task_list_page_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:mocktail/mocktail.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

class MockTaskListUseCase extends Mock implements TaskListUseCase {}

void main() {
  group('TaskListPage', () {
    late MockTaskListUseCase mockUseCase;

    setUp(() {
      mockUseCase = MockTaskListUseCase();
    });

    testWidgets('renders task list when data loaded', (tester) async {
      final tasks = [
        Task(id: '1', title: 'Buy groceries', status: TaskStatus.todo,
             priority: Priority.high, dueDate: DateTime(2026, 6, 1),
             createdAt: DateTime(2026, 5, 20)),
      ];

      when(() => mockUseCase.call()).thenAnswer((_) async => tasks);

      await tester.pumpWidget(
        ProviderScope(
          overrides: [
            taskListUseCaseProvider.overrideWithValue(mockUseCase),
          ],
          child: const MaterialApp(home: TaskListPage()),
        ),
      );

      await tester.pumpAndSettle();

      expect(find.text('Buy groceries'), findsOneWidget);
      expect(find.byType(Chip), findsWidgets); // 筛选Chip
    });

    testWidgets('shows empty state when no tasks', (tester) async {
      when(() => mockUseCase.call()).thenAnswer((_) async => []);

      await tester.pumpWidget(
        ProviderScope(
          overrides: [
            taskListUseCaseProvider.overrideWithValue(mockUseCase),
          ],
          child: const MaterialApp(home: TaskListPage()),
        ),
      );

      await tester.pumpAndSettle();

      expect(find.text('No tasks yet'), findsOneWidget);
      expect(find.byIcon(Icons.add_task), findsOneWidget);
    });
  });
}

# 单元测试 + Widget测试
flutter test --coverage

# Golden测试（首次生成基线）
flutter test --update-goldens

# 集成测试
flutter test integration_test/app_test.dart -d macos

# 查看覆盖率
genhtml coverage/lcov.info -o coverage/html
open coverage/html/index.html

@flutter-debug TaskListPage滚动时出现卡顿，请分析原因并优化。
检查以下可能的问题：
1. 列表项是否使用了builder
2. 是否有不必要的rebuild
3. 图片加载是否有缓存
4. 是否有耗时操作在主线程
使用Flutter DevTools的性能面板数据进行分析。

// 优化前：每次rebuild都创建新的Color和TextStyle
Widget build(BuildContext context) {
  return Container(
    color: Colors.blue.shade100, // 每次创建新Color对象
    child: Text(task.title, style: TextStyle(fontSize: 16)), // 每次创建新TextStyle
  );
}

// 优化后：使用const和缓存
static const _itemColor = Color(0xFFBBDEFB);
static const _titleStyle = TextStyle(fontSize: 16);

@override
Widget build(BuildContext context) {
  return Container(
    color: _itemColor,
    child: Text(task.title, style: _titleStyle),
  );
}

@flutter-debug 在iOS模拟器上运行应用，截取TaskListPage的屏幕截图，
检查是否有渲染溢出或布局问题。

配置Fastlane实现Flutter应用自动化发布：

iOS:
- match管理证书和Profile
- snapshot做截图自动化
- deliver上传App Store Connect

Android:
- supply管理Google Play
- screengrab做截图自动化

两个平台共用的lane：
- beta: 构建beta版本上传到TestFlight/Internal Test
- release: 构建release版本上传到App Store/Google Play
- screenshot: 自动生成各尺寸截图

项目信息：
- bundleId: com.example.taskflow
- packageName: com.example.taskflow

# ios/fastlane/Fastfile
default_platform(:ios)

platform :ios do
  desc "Build and upload to TestFlight"
  lane :beta do
    build_flutter_app
    upload_to_testflight(
      skip_waiting_for_build_processing: true
    )
  end

  desc "Build and release to App Store"
  lane :release do
    build_flutter_app
    deliver(
      submit_for_review: true,
      automatic_release: true,
      force: true
    )
  end

  def build_flutter_app
    sh("cd ../.. && flutter build ios --release --no-codesign")
    build_app(
      workspace: "Runner.xcworkspace",
      scheme: "Runner",
      export_method: "app-store"
    )
  end
end

# .github/workflows/flutter-ci.yml
name: Flutter CI/CD

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.29.0'
          channel: 'stable'
      - run: flutter pub get
      - run: dart run build_runner build --delete-conflicting-outputs
      - run: flutter analyze
      - run: flutter test --coverage
      - uses: codecov/codecov-action@v4
        with:
          files: coverage/lcov.info

  build-ios:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
      - run: flutter build ios --release --no-codesign
      - uses: ruby/setup-ruby@v1
      - run: |
          cd ios
          bundle install
          bundle exec fastlane beta

  build-android:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
      - run: flutter build apk --release
      - uses: ruby/setup-ruby@v1
      - run: |
          cd android
          bundle install
          bundle exec fastlane beta

flowchart LR
    A["CLAUDE.md<br/>项目配置"] --> B["目录结构<br/>生成"]
    B --> C["Feature开发<br/>Auth/Tasks/Profile"]
    C --> D["代码生成<br/>build_runner"]
    D --> E["四层测试<br/>Unit/Widget/Integration/Golden"]
    E --> F["性能优化<br/>DevTools"]
    F --> G["CI/CD<br/>Fastlane+GitHub Actions"]
    G --> H["发布<br/>App Store+Google Play"]

    I["Flutter Agents<br/>19个专用Agent"] -.-> C
    I -.-> E
    I -.-> F

    style A fill:#6c5ce7,color:#fff
    style I fill:#fd79a8,color:#fff
    style H fill:#00b894,color:#fff

taskflow_app/
├── CLAUDE.md                    # Claude Code项目指引
├── .claude/
│   ├── agents/                  # 自定义Flutter Agent
│   │   ├── flutter-architect.md
│   │   ├── flutter-testing.md
│   │   └── flutter-debug.md
│   └── settings.json            # 项目级Claude Code设置
├── pubspec.yaml                 # 依赖管理（含build_runner配置）
├── analysis_options.yaml        # Dart静态分析规则
├── .github/workflows/
│   └── flutter-ci.yml           # GitHub Actions CI/CD
├── ios/fastlane/
│   ├── Fastfile                 # iOS发布lane
│   └── Matchfile                # 证书管理
├── android/fastlane/
│   └── Fastfile                 # Android发布lane
└── test/
    ├── goldens/                 # Golden测试快照
    └── integration_test/
        └── app_test.dart        # 集成测试

dependencies:
  flutter:
    sdk: flutter
  flutter_riverpod: ^2.6.1
  riverpod_annotation: ^2.6.1
  go_router: ^14.8.0
  dio: ^5.7.0
  retrofit: ^4.4.1
  drift: ^2.24.0
  freezed_annotation: ^2.4.4
  json_annotation: ^4.9.0
  cached_network_image: ^3.4.1

dev_dependencies:
  flutter_test:
    sdk: flutter
  integration_test:
    sdk: flutter
  build_runner: ^2.4.14
  freezed: ^2.5.8
  json_serializable: ^6.9.4
  riverpod_generator: ^2.6.3
  retrofit_generator: ^9.1.7
  drift_dev: ^2.24.0
  mocktail: ^1.0.4
  flutter_lints: ^5.0.0

# 为所有feature生成缺失的测试文件
for feature in auth tasks profile; do
  claude -p "为lib/features/$feature/下所有未测试的文件生成Widget测试" \
    --allowedTools Edit,Write,Read,Bash
done

---
name: flutter-feature-creator
description: 创建新Flutter Feature的完整Clean Architecture代码
---

根据以下规格创建完整的Flutter Feature：

Feature名称: $ARGUMENTS
包含三层: presentation/domain/data
状态管理: Riverpod
测试: 单元测试 + Widget测试

include: package:flutter_lints/flutter.yaml
analyzer:
  errors:
    invalid_annotation_target: ignore
  exclude:
    - "**/*.g.dart"
    - "**/*.freezed.dart"
linter:
  rules:
    prefer_single_quotes: true
    always_declare_return_types: true
    avoid_print: true
    prefer_const_constructors: true
    prefer_const_declarations: true

# 为每个feature创建独立worktree
claude worktree create feature/auth
claude worktree create feature/tasks
claude worktree create feature/profile

根据本次会话中的所有代码变更，更新CHANGELOG.md，
格式遵循 Keep a Changelog 规范。

@flutter-security 对TaskFlow应用进行安全审计：
1. 检查API密钥是否硬编码
2. 验证HTTPS证书固定
3. 检查本地存储是否加密敏感数据
4. 验证输入验证是否完备
5. 检查ProGuard/R8混淆配置

# 一键验证所有平台构建
claude -p "依次构建TaskFlow的所有目标平台并报告结果：
flutter build apk --release
flutter build ios --release --no-codesign
flutter build web --release
flutter build macos --release
列出每个平台的构建状态、包大小和警告信息。"

sequenceDiagram
    participant Dev as 开发者
    participant CC as Claude Code
    participant Agent as Flutter Agents
    participant CI as GitHub Actions
    participant Store as App Store/Google Play

    Dev->>CC: 创建CLAUDE.md
    Dev->>CC: 描述Feature需求
    CC->>Agent: 调用flutter-architect
    Agent-->>CC: 返回架构设计
    CC->>CC: 生成Domain层接口
    CC->>CC: 生成Data层实现
    CC->>CC: 生成Presentation层UI
    CC->>CC: 运行build_runner
    Dev->>CC: 请求测试
    CC->>Agent: 调用flutter-testing
    Agent-->>CC: 返回测试策略
    CC->>CC: 生成四层测试
    CC->>CC: flutter test
    Dev->>CC: 请求性能优化
    CC->>Agent: 调用flutter-debug
    CC->>CC: 分析并优化
    Dev->>CI: git push
    CI->>CI: flutter analyze
    CI->>CI: flutter test
    CI->>CI: flutter build
    CI->>Store: Fastlane上传
    Store-->>Dev: 构建就绪通知