Flutter AI 技能与规则，适用于 Cursor、Copilot、Antigravity 等 AI 驱动的 IDE

⚡ 快速概览

主要方法： 将 skills/ 文件夹中的技能复制到你的 IDE 的技能目录中（例如 .cursor/skills/、.windsurf/skills/）。代理会根据你的任务自动使用相关的技能。

对于传统规则：如果你想使用 .cursor/rules 或 .windsurfrules，只需将你选择的规则集内容（例如 combined/flutter_dart__under_6K.md）复制到你的 IDE 的全局或本地规则中即可。
为了获得最大的控制权，你也可以将 /rules 文件夹复制到你的项目中，并根据需要引用规则（例如：“阅读 @rules/firebase/ 并设置一个包含实时数据库、App Check 和 Analytics 的项目。”）。

🚀 简介

此仓库提供了一套全面且（几乎）无偏见的 Flutter 相关规则，专为 Windsurf、Cursor 和其他 AI 驱动的 IDE 设计。这些规则旨在改善你的开发工作流程、确保一致性，并帮助你充分利用 AI 编码助手的功能。

📁 仓库结构

• skills/
  新增！ 技能是一种开放标准，用于扩展代理的能力。技能是一个包含 SKILL.md 文件的文件夹，其中包含了代理在处理特定任务时可以遵循的指令。它们本质上就是以前所说的“动态规则”——当代理根据描述判断其相关性时，会自动应用。

  将任何技能文件夹复制或创建符号链接到 .cursor/skills/、.agent/skills/ 或其他支持的位置。

• rules/
  包含单个规则文件，每个文件专注于一个特定的主题或工具（例如 bloc.md、effective_dart.md 等）。
  这些文件：

  • 完全基于 Flutter、Dart 或相关包的官方网站文档。
  • 按主题分类，便于混合、匹配和引用。
  • 可以根据你的项目需求进行优化、调整或提取。

• combined/
  包含预先制作好的、精选的规则集合，结合了常用的主题（例如 Flutter + Riverpod + Mockito）。
  这些文件：

  • 字数控制在 6,000 字符 以内，以符合 Windsurf 的限制。
  • 可以直接复制到你的全局或本地规则配置中使用。

✅ 使用方法

方法 1：技能——由代理决定使用哪些

1. 浏览 skills/ 文件夹。
2. 将技能文件夹复制或创建符号链接到你的 IDE 的技能目录中（例如 .cursor/skills/、.windsurf/skills/）。
3. 代理会根据你的任务描述自动使用相关的技能。
4. 你就可以开始使用了——技能会在上下文中自动激活，无需手动选择。

方法 2：使用预设的组合规则

如果你想要快速设置传统规则：

1. 浏览 combined/ 文件夹。
2. 复制一个适合你项目的文件。
3. 将其粘贴到你的 IDE 的全局或本地规则配置中。
4. 你就可以开始使用了。

方法 3：使用单个规则文件

如果你更喜欢更精细的控制：

1. 浏览 rules/ 文件夹。
2. 选择与你的项目相关的文件（例如 riverpod.md、bloc.md 等）。
3. 你可以：
   • 直接将其纳入你的 IDE 设置中。
   • 在提示中引用它们以增加上下文。
   • 只提取对你当前场景有用的部分。
   • 将其部分或全部纳入产品需求文档（PRD）中。

一切都是模块化的——选择最适合你的方式即可。

方法 4：通过 CLI 下载所有技能

你可以使用一条命令将最新的技能直接下载到你的项目中：

git clone --depth 1 https://github.com/evanca/flutter-ai-rules.git temp_repo && mkdir -p .skills && cp -r temp_repo/skills/* .skills && rm -rf temp_repo

这将会把所有技能复制到你项目的 .skills 文件夹中。一旦所有技能都进入 .skills 文件夹，你可以根据自己的需求单独引用它们。例如：

“阅读 @.skills/bloc/SKILL.md，并为新方法创建测试覆盖率。”

小贴士：
你还可以配置你的 IDE 自动加载这个 .skills 文件夹中的技能，或者在提示中引用它们以获取具体的指导。

📏 无偏见，只基于文档

所有规则均来源于官方文档——没有任何个人偏好或主观解释。这是有意为之。你可以根据自己的喜好修改它们，但这个仓库坚持从原始资料出发，保持客观性。

注意：这有时可能会导致规则相互矛盾（例如，如果一个包建议一种文件夹架构，而另一个包又推荐另一种架构）。

📌 使用场景

• 在你的 IDE 中安装技能，以便在开发过程中获得自动化的上下文相关帮助。
• 在你的 IDE 中为 Flutter 项目设置全局规则。
• 为流行的状态管理库配置项目特定的约束条件。
• 在团队协作时，在 PRD 中明确期望。
• 只提取你需要的内容，避免规则过于冗杂。
• 在提示中引用单个技能或规则，以获得具体的指导。

🛠️ 贡献

欢迎贡献！如果你想提出新的规则或改进现有规则，可以按照以下步骤操作：

1. 分支此仓库。
2. 在相应的文件夹中添加或修改规则。
3. 提交一个带有清晰说明的拉取请求。
   请务必为任何你添加或修改的规则集附上官方文档链接，以确保所有内容客观可靠。

📚 参考文献

以下是构建这些规则所使用的官方资料：

Flutter

• Flutter 应用架构 —— 官方 Flutter 架构指南
• Flutter 常见错误 —— 常见错误文档
• Flutter ChangeNotifier 状态管理 —— 使用 ChangeNotifier 的简单状态管理

Dart

• Effective Dart —— 官方 Dart 风格指南
• Dart 3 更新 —— 关于 Dart 3 特性的文档，包括：
  • 元组
  • 模式匹配
  • 模式类型
  • 分支语句

状态管理

• Bloc 库 —— 官方 Bloc 库文档
• Provider —— 官方 Provider 包文档
• Riverpod —— 官方 Riverpod 文档

测试

• Mockito - Dart 官方 Mockito 文档
• Mocktail - Mocktail 官方文档

Firebase

• Firebase for Flutter - Firebase Flutter 官方文档
• Code with Andrea - 如何使用 FlutterFire CLI 为 Flutter 和 Firebase 设置多环境配置

flutter-ai-rules 快速上手指南

flutter-ai-rules 是一个专为 Flutter 开发者设计的开源规则库，旨在提升 Cursor、Windsurf、Copilot 等 AI 编程助手的代码生成质量。它基于官方文档（Flutter/Dart/主流包），提供模块化技能和预设规则，确保 AI 输出的代码符合最佳实践。

环境准备

• 系统要求：Windows, macOS, 或 Linux。
• 前置依赖：
  • 已安装支持自定义规则/Skills 的 AI IDE（推荐 Cursor 或 Windsurf）。
  • 已安装 git 命令行工具。
  • 熟悉 Flutter 和 Dart 基础开发流程。

安装步骤

你可以根据需求选择以下任一方式将规则集成到项目中。

方式一：一键克隆所有 Skills（推荐）

使用单行命令将所有技能文件下载到项目本地的 .skills 目录中，便于灵活引用。

git clone --depth 1 https://github.com/evanca/flutter-ai-rules.git temp_repo && mkdir -p .skills && cp -r temp_repo/skills/* .skills && rm -rf temp_repo

方式二：手动配置全局/局部规则

如果你希望 AI 自动应用规则而无需每次指定：

1. 浏览本仓库的 skills/ 文件夹（用于动态技能）或 combined/ 文件夹（用于传统静态规则）。
2. 将选中的文件夹（如 skills/bloc）复制或软链接到你的 IDE 配置目录：
   • Cursor: .cursor/skills/ 或 .cursor/rules/
   • Windsurf: .windsurf/skills/ 或 .windsurfrules
3. IDE 重启后会自动加载这些上下文。

提示：国内用户若克隆速度慢，可尝试使用镜像加速服务，或将仓库 Fork 到国内代码托管平台（如 Gitee）后再克隆。

基本使用

场景 A：自动上下文感知（使用 Skills）

如果你采用了方式一或方式二安装了 Skills 文件夹，AI 会根据你的任务描述自动匹配规则。

操作示例： 直接在对话框中输入自然语言指令，无需额外参数：

"为当前的 User 模型创建单元测试。"

AI 会自动读取 .skills/ 中相关的测试规范（如 Mocktail 规则）并生成符合标准的代码。

场景 B：手动指定规则（精准控制）

如果你只想在特定任务中应用某项规则，可以在提示词中显式引用本地文件。

操作示例： 假设你已下载 skills 到 .skills 目录，需要创建 Bloc 测试：

"Read @.skills/bloc/SKILL.md and create test coverage for new methods."

或者在中文提示中引用：

"请参考 @.skills/riverpod/SKILL.md 中的规范，重构当前的状态管理代码。"

场景 C：使用预设组合规则

对于新项目，可以直接使用 combined/ 目录下的整合规则文件（如 flutter_dart__under_6K.md），将其内容复制到 IDE 的全局规则设置中。这将一次性注入 Flutter + Dart + 常用库的综合最佳实践，适合快速初始化项目环境。