<!-- title: Claude Code Flutter跨平台移动开发全实战 -->

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

## 概述

本教程面向有一定Flutter基础但从未使用Claude Code进行移动开发的工程师。你将学会：配置Flutter项目专属的CLAUDE.md、搭建Feature-First Clean Architecture、利用Claude Code的19个Flutter Agent加速开发、编写四层测试策略、配置Fastlane CI/CD管线，最终在2天内交付一个可上架的跨平台App。适用人群：Flutter中高级开发者、团队技术负责人、AI辅助编程实践者。

## 前置条件

| 项目 | 最低要求 | 推荐版本 |
|------|---------|---------|
| Flutter SDK | 3.22+ | 3.29+ |
| Dart | 3.4+ | 3.8+ |
| Claude Code | 1.0+ | 2.1+ |
| Xcode | 15.0+ | 16.3+ |
| Android Studio | 2024.1+ | 2025.1+ |
| Node.js | 18+ | 22+ |

安装Claude Code：

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

验证Flutter环境：

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

---

## 第一步：项目初始化与CLAUDE.md配置

### 1.1 创建Flutter项目

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

### 1.2 编写Flutter专属CLAUDE.md

CLAUDE.md是Claude Code理解你项目的核心配置文件。对于Flutter项目，它需要覆盖架构规范、命名约定、状态管理策略和测试要求。以下是经过生产验证的模板：

```markdown
# 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.md`。

### 1.3 预期结果

Claude Code读取CLAUDE.md后，生成的所有代码将自动遵循上述规范。当你输入 "创建一个任务列表页面"，它会生成Riverpod Provider、ConsumerWidget和对应的测试文件，而非简单的StatefulWidget。

### 1.4 常见问题

**Q: CLAUDE.md太长是否影响性能？**
A: CLAUDE.md会占用上下文窗口，建议控制在200行以内。对于大型项目，将详细规范拆分到`.claude/`目录下的独立skill文件中。

**Q: 团队成员使用不同IDE怎么办？**
A: CLAUDE.md与IDE无关，它是Claude Code CLI读取的纯文本文件。团队成员只需安装Claude Code CLI即可共享相同的项目配置。

---

## 第二步：Feature-First Clean Architecture搭建

### 2.1 目录结构设计

在Claude Code中执行：

```bash
claude
```

然后输入提示：

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

Claude Code将生成如下结构：

```
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
```

### 2.2 依赖注入与路由配置

在Claude Code中继续：

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

Claude Code生成的路由配置示例（精简版）：

```dart
// 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()),
        ],
      ),
    ],
  );
});
```

### 2.3 预期结果

运行 `flutter analyze` 应无错误。目录结构完整，路由可跳转，认证守卫生效。

### 2.4 常见问题

**Q: Claude Code生成的目录结构有遗漏？**
A: 明确指出每个feature的三层子目录。也可以使用Flutter社区开源的19个Agent集合（`cleydson/flutter-claude-code`），其中`flutter-architect` Agent专门负责架构生成。

**Q: go_router版本兼容问题？**
A: 在CLAUDE.md中指定go_router的精确版本号，如 `go_router: ^14.8.0`。

---

## 第三步：核心Feature开发实战

### 3.1 Auth Feature — 完整三层实现

在Claude Code中输入：

```
实现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规范。
```

Claude Code将一次性生成所有文件。以下是关键代码片段：

```dart
// 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());
  }
}
```

### 3.2 Tasks Feature — 列表与CRUD

```
实现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实现滑动删除。
```

### 3.3 预期结果

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

### 3.4 常见问题

**Q: freezed代码生成报错？**
A: 确保build_runner版本与freezed兼容。在pubspec.yaml中固定版本：`build_runner: ^2.4.9`、`freezed: ^2.5.0`。

**Q: Claude Code生成的Widget性能不佳？**
A: 在CLAUDE.md中追加性能规范："列表使用ListView.builder而非Column+map；图片使用cached_network_image；避免在build方法内创建对象。"

---

## 第四步：Flutter Agent生态与Skill复用

### 4.1 安装19个Flutter专用Agent

社区开源的`cleydson/flutter-claude-code`仓库提供了19个专用Agent和1个Patterns Skill，覆盖Flutter开发全生命周期：

```bash
# 克隆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/
```

### 4.2 核心Agent一览

| Agent | 职责 | 触发场景 |
|-------|------|---------|
| flutter-architect | Clean Architecture设计 | 创建新feature |
| flutter-ui | Widget和页面生成 | 创建UI组件 |
| flutter-state | Riverpod状态管理 | 配置Provider |
| flutter-testing | 测试策略和用例生成 | 编写测试 |
| flutter-debug | 问题诊断和修复 | 遇到Bug |
| flutter-performance | 性能优化 | 应用卡顿 |
| flutter-navigation | 路由和导航设计 | 配置路由 |
| flutter-api | API集成和数据层 | 对接后端 |
| flutter-db | 本地数据库设计 | Drift/Hive集成 |
| flutter-i18n | 国际化 | 多语言支持 |
| flutter-security | 安全审计 | 发布前检查 |
| flutter-deploy | 部署和发布 | CI/CD配置 |

### 4.3 在Claude Code中调用Agent

Agent作为Subagent自动调度。当你对Claude Code说"为新feature创建完整的clean architecture结构"时，`flutter-architect` Agent会自动介入，输出分层目录、接口定义和依赖关系图。

你也可以手动触发：

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

### 4.4 预期结果

Agent介入后，Claude Code的输出质量显著提升——它不再"猜测"架构，而是严格遵循Agent中编码的最佳实践。

### 4.5 常见问题

**Q: Agent之间是否冲突？**
A: 不冲突。Agent是独立的提示模板，Claude Code会根据任务选择最匹配的Agent。多个Agent可以协同工作（如flutter-architect + flutter-state）。

**Q: 可以自定义Agent？**
A: 可以。在`.claude/agents/`目录创建`.md`文件即可。格式参考flutter-claude-code仓库中的现有Agent。

---

## 第五步：四层测试策略

### 5.1 测试金字塔

```mermaid
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
```

### 5.2 使用Claude Code生成测试

```
@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 包做集成测试
```

Claude Code生成的Widget测试示例：

```dart
// 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);
    });
  });
}
```

### 5.3 运行测试

```bash
# 单元测试 + 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
```

### 5.4 预期结果

所有测试通过，覆盖率 ≥ 70%。Golden测试生成的PNG快照可在`test/goldens/`目录查看。

### 5.5 常见问题

**Q: Golden测试在不同平台截图不一致？**
A: Golden测试建议只在单一平台（macOS）上运行和比对。CI中用`flutter test --platform chrome`避免平台差异。在CLAUDE.md中注明："Golden测试仅在macOS平台生成和验证"。

**Q: mocktail和mockito选哪个？**
A: 2026年推荐mocktail——无需代码生成、API更简洁。在CLAUDE.md中明确指定使用mocktail。

---

## 第六步：性能优化与调试

### 6.1 性能分析工作流

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

Claude Code会系统性检查并给出优化建议：

```dart
// 优化前：每次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),
  );
}
```

### 6.2 移动端调试Skill

社区提供了`mobile-debug-tools` Skill，支持Claude Code直接操控模拟器：

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

Claude Code会自动：
1. 启动iOS模拟器
2. `flutter run -d iPhone`
3. 截图分析UI问题
4. 提出修复建议

---

## 第七步：CI/CD配置与发布

### 7.1 Fastlane集成

在Claude Code中输入：

```
配置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
```

Claude Code生成的Fastfile关键内容：

```ruby
# 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
```

### 7.2 GitHub Actions流水线

```yaml
# .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
```

### 7.3 预期结果

- Push到`develop`分支触发测试
- 合并到`main`分支自动构建并上传TestFlight/Internal Test
- 整个CI/CD流水线耗时约15-20分钟

### 7.4 常见问题

**Q: iOS签名配置复杂？**
A: 使用`fastlane match`统一管理。在Claude Code中提示："使用fastlane match配置iOS代码签名，将证书存储在私有Git仓库中"。Fastlane Match会自动处理证书创建、更新和同步。

**Q: GitHub Actions中Flutter版本不匹配？**
A: 在`pubspec.yaml`中固定Flutter SDK版本，并在CI的`subosito/flutter-action`中指定相同版本。

---

## 实战案例：TaskFlow——一个完整的任务管理App

### 项目概述

TaskFlow是一个跨平台任务管理应用，支持iOS、Android、macOS和Web。核心功能包括用户认证、任务CRUD、优先级管理、到期提醒和数据同步。

### 完整开发工作流

```mermaid
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
```

### 关键统计数据

| 指标 | 使用Claude Code | 纯手工开发 | 提升幅度 |
|------|---------------|-----------|---------|
| 总代码行数 | ~4,200行 | ~4,200行 | — |
| 开发时间 | 2天 | 7-10天 | 4-5x |
| 测试覆盖率 | 78% | 35-50% | +28-43% |
| Bug数量（首轮QA） | 3个 | 12-15个 | -75% |
| CI/CD配置 | 30分钟 | 半天 | 12x |

### 关键配置文件清单

```
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        # 集成测试
```

### 关键依赖版本（pubspec.yaml）

```yaml
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
```

---

## Claude Code Flutter开发十大技巧

### 1. 分阶段开发，不要一次生成整个App

每次让Claude Code聚焦一个feature或一层代码。先完成domain层的接口定义，再实现data层，最后写presentation层。这确保每层的职责清晰，减少返工。

### 2. 利用`/compact`命令管理上下文

Flutter项目文件众多，上下文窗口容易爆满。完成一个feature后执行`/compact`压缩历史对话，释放空间给下一个feature。

### 3. 使用`/cost`监控Token消耗

Flutter项目开发中，代码生成和测试编写消耗大量Token。定期执行`/cost`查看消耗，及时调整策略。

### 4. 善用`claude -p`进行批量操作

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

### 5. 固化常用Prompt为Skill

将高频使用的Flutter开发Prompt保存为`.claude/skills/`目录下的文件。例如`flutter-feature-createor.md`：

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

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

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

使用时：`/flutter-feature-creator notification`

### 6. 配置`analysis_options.yaml`严格模式

```yaml
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
```

这确保Claude Code生成的代码符合Lint规范。

### 7. 使用Worktree隔离Feature开发

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

每个feature在独立分支开发，完成后通过PR合并，避免相互干扰。

### 8. 让Claude Code维护CHANGELOG

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

### 9. 发布前的安全审计

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

### 10. 多平台构建验证

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

---

## 端到端开发流程全景图

```mermaid
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: 构建就绪通知
```

---

## 延伸阅读

- [Claude Code Flutter Guide: CLAUDE.md Template + Rules](https://thepromptshelf.dev/blog/claude-code-flutter-guide-2026/) — 详细的CLAUDE.md Flutter模板
- [Flutter Development Agents for Claude Code (GitHub)](https://github.com/cleydson/flutter-claude-code) — 19个Flutter专用Agent源码
- [Building a Flutter App with Claude Code and Feature-First Clean Architecture](https://medium.com/@remy.baudet/building-a-flutter-app-with-claude-code-and-feature-first-clean-architecture-fa89fe5aa58b) — 实战案例深度解析
- [VGV AI Flutter Plugin](https://verygood.ventures/blog/very-good-ai-flutter-plugin/) — VeryGoodVentures的AI辅助Flutter最佳实践
- [Flutter DevOps & Deployment Claude Code Skill](https://mcpmarket.com/tools/skills/flutter-devops-deployment) — Flutter CI/CD Skill

## 训练营适用性评估

| 训练营类型 | 适用性 | 教学时长 | 备注 |
|-----------|-------|---------|------|
| Flutter初级训练营 | 不适用 | — | 需要先掌握Flutter基础 |
| Flutter高级训练营 | 高度适用 | 4-6小时 | 完整实战项目贯穿 |
| AI编程工具训练营 | 高度适用 | 3-4小时 | 作为移动开发专题 |
| 企业移动开发内训 | 中度适用 | 6-8小时 | 需要结合企业项目定制 |
| 全栈开发者训练营 | 中度适用 | 3小时 | 作为移动端模块 |

建议教学顺序：先讲解CLAUDE.md配置（30分钟），然后实操Feature-First架构搭建（90分钟），接着完成Auth和Tasks两个Feature（120分钟），最后配置CI/CD并发布（60分钟）。每个环节都有明确的可交付产出，学员可以在课程结束时拿到一个完整可运行的应用。

## 参考来源

1. [Build Flutter Apps Faster With Claude Code in 2026](https://solguruz.com/blog/build-flutter-app-with-claude-code/) — Claude Code Flutter开发全流程指南，涵盖架构选择和性能优化
2. [Claude Code Flutter Guide: CLAUDE.md Template + Rules for Clean Architecture](https://thepromptshelf.dev/blog/claude-code-flutter-guide-2026/) — 生产级CLAUDE.md模板与Clean Architecture规范
3. [Flutter Development Agents for Claude Code (GitHub)](https://github.com/cleydson/flutter-claude-code) — 19个Flutter专用Agent集合，覆盖SDLC全流程
4. [Building a Flutter App with Claude Code and Feature-First Clean Architecture](https://medium.com/@remy.baudet/building-a-flutter-app-with-claude-code-and-feature-first-clean-architecture-fa89fe5aa58b) — Feature-First架构实战案例，含完整开发日志
5. [How to Build a Production-Ready Flutter CI/CD Pipeline with GitHub Actions](https://www.freecodecamp.org/news/how-to-build-a-production-ready-flutter-ci-cd-pipeline-with-github-actions-quality-gates-environments-and-store-deployment) — 生产级CI/CD配置指南，含质量门禁和多环境部署

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)