flutter-brainstorming

概述

flutter-brainstorming 用于将想法转化为完整的 Flutter 设计与规格说明，通过自然的协作式对话完成。在进行任何创造性工作（创建功能、构建组件、添加功能或修改行为）之前，必须先使用本技能。

开始时应理解当前项目上下文（pubspec.yaml、lib/ 结构、已有功能），然后一次只问一个问题来细化想法。一旦理解要构建的内容，就以小段落（200-300 字）呈现设计，并在每段之后检查是否符合预期。

开始时需声明：“I'm using the flutter-brainstorming skill to design this feature.”

使用方式

阶段 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"

一次只问一个问题，尽量使用多选题，每条消息只问一个问题，聚焦理解：目的、约束、成功标准。

需要探索的关键问题：

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

阶段 2：探索方案

提出 2-3 种不同方案并说明权衡。例如状态管理：

方案 A：Riverpod + Freezed（推荐用于新项目）
方案 B：BLoC Pattern
方案 C：Provider + ChangeNotifier

以 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 字的段落呈现设计，包括：功能概览（目的与范围、用户故事）、Clean Architecture 结构、数据流、API 契约、本地存储模式、状态转换、UI/UX 设计（Widget 层级、导航流程、错误状态）、基于优先级的测试策略：

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

每段之后询问：“Does this look right so far?”

设计之后

将验证过的设计写入 docs/plans/YYYY-MM-DD-<feature>-design.md，模板包含：概述、用户故事、Clean Architecture（Domain/Data/Presentation 层）、数据流、API 契约、测试计划、依赖。

提交设计文档到 git：

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

实现（如继续）

询问：“Ready to create an implementation plan?”

如果同意：

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

必需的子技能

完成头脑风暴并记录设计后，必须调用： → Skill tool: flutter-craft:flutter-planning

这不是可选项。没有详细实现计划，工作流就是不完整的。

关键原则

一次只问一个问题
优先使用多选题
始终采用 Clean Architecture：Domain → Data → Presentation 层顺序
严格遵循 YAGNI，移除所有不必要功能
探索替代方案，在确定前始终提出 2-3 种方案
增量验证，分段呈现设计并逐段确认
测试优先级：Repository/DataSource → 状态 → Widget

警示信号

不要因为以下理由跳过头脑风暴：

“这只是一个简单小组件” → 组件需要架构上下文
“我已经知道要构建什么” → 用户可能有不同预期
“时间紧张” → 糟糕的设计日后会花费更多时间
“这很明显” → 假设会导致 bug