flutter-brainstorming

将 Flutter 功能构思为设计方案

概述

通过自然、协作式的对话，帮助将想法转化为完整的 Flutter 设计方案和规格说明。

首先了解当前项目的上下文（pubspec.yaml、lib/ 结构、现有功能），然后每次提出一个问题，逐步完善想法。了解要构建的内容后，将设计分成简短的章节（200-300 个词），并在每个章节后确认目前看来是否合适。

开始时宣布：“我正在使用 flutter-brainstorming 技能来设计此功能。”

流程

阶段 1：了解想法

先检查项目上下文：

# Check pubspec.yaml for dependencies
cat pubspec.yaml

# Check existing lib/ structure
ls -la lib/

# Check existing features
ls -la lib/features/ 2>/dev/null || echo "No features folder yet"

每次提出一个问题：

• 尽可能优先使用选择题
• 每条消息只问一个问题
• 重点了解：目标、约束条件、成功标准

需要探讨的关键问题：

1. 此功能要解决什么用户问题？
2. 此功能需要哪些数据？
3. 需要哪些 UI 交互？
4. 需要管理哪些状态？
5. 是否有外部依赖（API、数据库）？

阶段 2：探索方案

提出 2-3 种不同方案并说明各自的权衡：

状态管理示例：

Approach A: Riverpod + Freezed (Recommended for new projects)
- Pros: Compile-time safety, immutable states, no boilerplate with codegen
- Cons: Learning curve, requires build_runner
- Best for: Most Flutter projects

Approach B: BLoC Pattern
- Pros: Separation of concerns, testable, scalable
- Cons: More boilerplate
- Best for: Complex state, multiple streams, large teams

Approach C: Provider + ChangeNotifier
- Pros: Simple, familiar
- Cons: Less structured, harder to test
- Best for: Simple local state, small projects

Riverpod + Freezed 模式示例：

// State with freezed (3.x: union classes must be sealed; use Dart 3
// switch patterns instead of the removed .when()/.map())
@freezed
sealed class AuthState with _$AuthState {
  const factory AuthState.initial() = AuthInitial;
  const factory AuthState.loading() = AuthLoading;
  const factory AuthState.authenticated(User user) = AuthAuthenticated;
  const factory AuthState.error(String message) = AuthError;
}

// Notifier with riverpod_generator
@riverpod
class Auth extends _$Auth {
  @override
  AuthState build() => const AuthState.initial();

  Future<void> login(String email, String password) async {
    state = const AuthState.loading();
    try {
      final user = await ref.read(authRepositoryProvider).login(email, password);
      state = AuthState.authenticated(user);
    } catch (e) {
      state = AuthState.error(e.toString());
    }
  }
}

先给出你的推荐方案，并解释原因。

阶段 3：呈现设计

将设计分成每节 200-300 个词的章节：

1. 功能概述

   • 目标和范围
   • 用户故事

2. 整洁架构结构

   lib/features/<feature_name>/
   ├── domain/
   │   ├── entities/          # Business objects
   │   ├── repositories/      # Repository interfaces
   │   └── usecases/          # Business logic
   ├── data/
   │   ├── models/            # DTOs (fromJson, toJson)
   │   ├── datasources/       # Remote & Local data sources
   │   └── repositories/      # Repository implementations
   └── presentation/
       ├── bloc/ or provider/ # State management
       ├── widgets/           # Reusable UI components
       └── screens/           # Full screen widgets
   

3. 数据流

   • API 契约（如适用）
   • 本地存储架构（如适用）
   • 状态转换

4. UI/UX 设计

   • Widget 层级结构
   • 导航流程
   • 错误状态

5. 测试策略（按优先级排序）

   • 优先级 1：Repository、DataSource 单元测试
   • 优先级 2：状态管理（BLoC/Provider）单元测试
   • 优先级 3：Widget 测试（可选）
   • 优先级 4：Golden 测试（可选，视觉回归）

每个章节后询问：“目前看来合适吗？”

设计完成后

文档

将经验证的设计写入：

docs/plans/YYYY-MM-DD-<feature>-design.md

设计文档模板：

# <Feature Name> Design

## Overview
[1-2 sentences describing the feature]

## User Stories
- As a user, I want to...

## Clean Architecture

### Domain Layer
- Entities: [list]
- UseCases: [list]
- Repository interfaces: [list]

### Data Layer
- Models: [list]
- DataSources: [list]
- Repository implementations: [list]

### Presentation Layer
- State Management: [BLoC/Provider/Riverpod]
- Screens: [list]
- Widgets: [list]

## Data Flow
[Diagram or description]

## API Contract
[If applicable]

## Testing Plan
- Unit tests: [list]
- Widget tests: [list]
- Integration tests: [if needed]

## Dependencies
[New packages needed in pubspec.yaml]

将设计文档提交到 git：

git add docs/plans/
git commit -m "docs: add <feature> design document"

实施（如需继续）

询问：“准备好创建实施计划了吗？”

如果是：

• 使用 flutter-craft:flutter-planning 创建详细的实施计划
• 如果需要隔离的工作区，则使用 flutter-craft:flutter-worktrees

必需的子技能

完成构思并记录设计后，必须调用： → Skill 工具：flutter-craft:flutter-planning

此步骤不可省略。没有详细的实施计划，工作流就不完整。

核心原则

• 一次只问一个问题——不要一次提出多个问题，让用户应接不暇
• 优先使用选择题——比开放式问题更容易回答
• 始终采用整洁架构——按 Domain → Data → Presentation 的层级顺序
• 严格遵循 YAGNI 原则——从所有设计中移除不必要的功能
• 探索替代方案——确定方案前始终提出 2-3 种方案
• 逐步验证——分章节呈现设计，并逐节验证
• 测试优先级——Repository/DataSource → State → Widget

警示信号

绝不可因为以下理由跳过构思：

• “这只是一个简单的 Widget” → Widget 也需要架构上下文
• “我已经知道要构建什么” → 用户可能有不同的预期
• “时间紧迫” → 糟糕的设计会在之后耗费更多时间
• “这显而易见” → 假设会导致 Bug