1. 项目概述：为AI编程助手制定“行为准则”

如果你和我一样，日常开发已经离不开像 Cursor、TRAE 这类 AI 编程助手，那你肯定也经历过类似的“甜蜜烦恼”：助手生成的代码功能上没问题，但风格五花八门，命名随心所欲，结构也谈不上优雅。每次都得手动调整，效率反而打了折扣。这让我意识到，AI 助手虽然强大，但它缺乏一套统一的、符合最佳实践的“行为准则”。于是，我动手整理并开源了 IDE-Agent-Rules 这个项目。

简单来说，这是一个专门为 AI 编程助手（如 Cursor, TRAE 等）设计的规则库。它的核心目标不是替代开发者，而是“赋能”AI，让它生成的代码从一开始就更干净、更可读、更符合团队规范。你可以把它看作是 AI 助手的“编码规范手册”或“最佳实践指南”。目前，项目主要聚焦于 Dart/Flutter 技术栈，并基于 Robert C. Martin 的《代码整洁之道》等经典理论，提炼出了一套可直接用于指导 AI 的规则。

无论你是独立开发者，还是团队的技术负责人，这个项目都能帮你解决几个实际问题：统一团队的代码风格、降低 AI 生成代码的后期调整成本、系统性地提升代码库的可维护性。接下来，我将详细拆解这个项目的设计思路、核心规则、如何集成到你的工作流，以及我踩过的一些坑。

2. 核心设计思路：为什么需要为AI制定规则？

在深入具体规则之前，我想先聊聊背后的设计哲学。很多人可能会问：AI不是已经很强了吗，为什么还要给它定规则？这正是问题的关键。

2.1 AI编码的现状与挑战

当前的 AI 编程助手，本质上是基于海量开源代码训练出的概率模型。它能生成“可行”的代码，但“优秀”的代码往往需要遵循一些超越单纯功能性的原则，比如可读性、可维护性、单一职责等。这些原则在庞杂的训练数据中可能被稀释了。因此，AI 容易产生一些典型的“代码异味”：

  • 命名模糊 ：生成 processData() 、 handle() 这类表意不清的函数名。
  • 函数过长 ：倾向于在一个函数里堆砌所有逻辑，而不是拆分职责。
  • 魔法数字/字符串 ：在代码中直接硬编码数值或字符串，不加解释。
  • 错误处理缺失 ：生成乐观路径的代码，忽略异常或边缘情况。

IDE-Agent-Rules 的设计初衷，就是通过明确的、结构化的规则，主动引导 AI 避开这些陷阱，向“专业开发者”的思维靠拢。

2.2 规则库的定位与边界

这个项目有几个明确的定位：

  1. 补充而非替代 ：它不替代像 dart format 或 linter 这样的格式化、静态分析工具，而是专注于这些工具覆盖不到的“设计层面”和“意图层面”的规则。例如， linter 可以检查命名规范（如使用小驼峰），但无法判断一个命名是否“表意清晰”；而我们的规则可以指导 AI 如何起一个好名字。
  2. 面向AI，服务人类 ：所有规则的描述和示例，都优先考虑如何能被 AI 助手准确理解和执行。同时，其产出最终服务于开发者，因此规则本身必须符合人类的工程学认知和团队协作习惯。
  3. 语言相关与通用性结合 ：目前以 Dart/Flutter 为具体载体，因为规则必须有具体的代码示例才具有可操作性。但其背后的原则（如单一职责、有意义的命名）是跨语言的。项目结构也为未来扩展其他语言（如 JavaScript, Python）预留了空间。
  4. 渐进式采纳 ：规则不是铁律。项目鼓励团队根据自身情况，选取最急需、最认同的规则子集开始实践，逐步演进，形成自己的“规则配置”。

2.3 技术选型：为什么是Markdown？

你可能会注意到，这个仓库的核心内容都是 .md 文件。这不是偷懒，而是深思熟虑后的选择。

  • 可读性优先 ：规则本身需要被开发者阅读、理解和讨论。Markdown 格式在任何平台都能获得良好的阅读体验，便于在团队内传播和评审。
  • AI友好性 ：主流的 AI 编程助手对 Markdown 的解析和支持都非常好。你可以直接将整段规则描述、连同代码示例一起粘贴到聊天框中，AI 能很好地理解上下文。
  • 低门槛贡献 ：使用 Markdown 意味着任何开发者无需特殊工具或知识就能参与贡献、改进规则或添加示例，极大降低了协作成本。
  • 与现有工具链集成 ：Markdown 文件可以轻松地被纳入项目文档，也可以通过脚本进行简单的解析和处理，未来有集成到自动化流程的潜力。

3. 核心规则解析：从“整洁代码”开始实践

项目的第一部分，也是目前最完善的部分，是关于“整洁代码”的规则。这部分内容不是简单的规则罗列，而是结合了经典理论和 Dart/Flutter 特性的实战指南。

3.1 有意义的命名：让代码自我解释

命名是代码的基石。一条核心规则是： 名称应揭示意图，而非仅描述动作 。

规则示例与解析：

  • 糟糕的命名 ： List getData() 。 Data 是什么？是用户数据、配置数据还是缓存数据？
  • 良好的命名 ： List<User> fetchActiveUsers() 。立刻明确了获取的是“活跃用户”列表。
  • 针对Dart/Flutter的补充规则 ：
    • 布尔变量/方法 ：应以 is 、 has 、 can 、 should 等开头。例如， isLoading 、 hasPermission 。
    • 异步方法 ：强烈建议使用 fetch 、 load 、 fetch 等前缀，或使用 async 后缀（虽然后者非强制，但能提升可读性）。例如， Future<User> fetchUserById(int id) 比 Future<User> getUserById(int id) 更能暗示其异步性和可能存在的 I/O 操作。
    • Widget命名 ：应明确其用途，避免泛泛的 MyWidget 。例如， ProductCard 、 LoginForm 、 AppBarWithSearch 。

实操心得 ：在向 AI 描述需求时，你自己先使用准确的领域术语。如果你说“给我一个处理数据的函数”，AI 很可能给出 processData 。但如果你说“请编写一个函数，用于从 API 获取并解析用户订单列表”，AI 生成 Future<List<Order>> fetchAndParseUserOrders() 的概率就大得多。好的规则始于清晰的需求描述。

3.2 函数设计的黄金法则

函数是组织逻辑的基本单元。我们为 AI 制定了几个关键指标：

  1. 短小精悍 ：单个函数长度不应超过 20 行（理想情况下一屏内）。如果超了，AI 应被提示“此函数可能过长，考虑是否可将第 X-X 行逻辑抽取为独立函数 _calculateDiscount ？”
  2. 单一职责 ：一个函数只做一件事，并且要做好。规则会指导 AI 识别函数中的多个“抽象层级”。例如，一个函数里如果同时包含了“网络请求”、“JSON解析”、“数据转换”和“状态更新”，AI 应被建议拆分成 _fetchFromApi 、 _parseResponse 、 _convertToModel 、 _updateState 等小函数。
  3. 参数数量限制 ：函数参数不宜超过 3 个。超过 3 个时，AI 应被引导思考：
    • 这些参数是否属于同一个概念？能否封装成一个 DataClass （在 Dart 中非常简便）？
    • 是否有些参数是全局或类级别的配置，可以通过依赖注入或其他方式提供？

Dart/Flutter 特定场景：

  • Widget 构建方法 ： build 方法很容易膨胀。规则要求 AI 将复杂的 UI 逻辑拆分为多个 Widget 方法或独立的 StatelessWidget 。例如，将 ListView 的 itemBuilder 逻辑抽离成 _buildListItem 方法或 ProductListItem widget。
  • 异步错误处理 ：指导 AI 不要只生成 try-catch 包裹整个异步块，而是考虑错误的粒度。是网络错误、解析错误还是业务逻辑错误？应使用 Future.catchError 或更精细的 try-catch 块，并提供有意义的错误信息或回退 UI。

3.3 类与组织的整洁之道

对于类的组织，规则侧重于“高内聚、低耦合”。

  • 类的体积 ：如果一个类超过了 300 行（或感觉职责过多），AI 应被提示考虑拆分。
  • 依赖关系 ：在 Flutter 中，明确指导 AI 区分“表现组件”和“逻辑组件”。例如，一个 WeatherPage widget 不应该直接包含从 API 获取天气、解析、缓存的所有逻辑。这些逻辑应被抽取到一个 WeatherRepository 或 WeatherBloc （如果使用 BLoC）中。
  • 注释的智慧 ：规则强调 “用代码表达意图，而非注释” 。指导 AI 避免生成像 // 循环开始 这样的废话注释。注释应该解释“为什么这么做”，尤其是涉及复杂业务逻辑、算法选择或临时解决方案（ // TODO: 此处因后端API限制而采用此方案，待V2 API上线后重构 ）时。

4. 如何将规则集成到你的开发工作流？

规则写得再好，不落地也是白费。下面分享几种我实践过的、将 IDE-Agent-Rules 融入日常开发的方法。

4.1 方法一：作为Prompt的上下文（最灵活）

这是最简单直接的方式，尤其适合使用 Cursor 的 Chat 功能或类似插件的开发者。

  1. 创建规则片段库 ：将核心规则（如命名规范、函数设计要点）保存为文本片段（Snippet），或存放在一个容易访问的笔记文件中。
  2. 在对话中前置注入 ：当你需要 AI 编写或重构一段代码时，在问题描述前，先粘贴相关的规则。例如： 
    请遵循以下Dart整洁代码规则协助我：
1. 函数应短小，单一职责，参数不超过3个。
2. 布尔变量以is/has/can开头。
3. 异步方法使用fetch/load前缀。
4. 避免魔法数字，使用命名常量。

现在，请帮我重构下面这个函数：[你的代码片段]
  3. 效果 ：AI 会将这些规则作为本次对话的强上下文，生成的代码或重构建议会显著向规则靠拢。这种方法灵活度高，可以按需组合规则。

4.2 方法二：配置为AI的“系统指令”或自定义指令

一些高级的 AI 编程工具允许设置更持久的自定义指令。

  1. Cursor 的 .cursorrules 文件 ：你可以在项目根目录或用户目录创建 .cursorrules 文件。将 IDE-Agent-Rules 中 clean_code.md 的精华部分提炼成条款，写入这个文件。例如： 
    # 项目代码规范
- 命名：清晰揭示意图，布尔值用is/has，异步方法用fetch/load。
- 函数：长度<20行，单一职责，参数<=3个，否则建议封装为类。
- 错误处理：异步操作必须考虑错误状态，提供用户友好的回退。
- Flutter特定：大型build方法必须拆分子Widget，业务逻辑与UI分离。
  2. 效果 ：Cursor 会在整个项目的代码生成和编辑中，持续参考这些规则。这是一种“设置后即忘”的全局生效方式，非常适合为整个项目定下基调。

4.3 方法三：作为团队代码评审的检查清单

对于团队协作，可以将这些规则转化为代码评审（Code Review）的检查点。

  1. 提炼评审清单 ：从规则库中提取关键问题，形成清单：
    • [ ] 命名是否清晰，无需注释也能看懂？
    • [ ] 函数是否只做了一件事？是否太长？
    • [ ] 是否存在魔法数字/字符串？
    • [ ] 错误处理和边界情况是否考虑周全？
    • [ ] 新的类/Widget 职责是否单一？
  2. 在PR模板中引用 ：将这份清单加入到团队的 Pull Request 模板中。评审者在查看代码，尤其是 AI 生成或修改的代码时，可以对照清单进行快速检查。
  3. 效果 ：这不仅提升了代码质量，也是一个非常好的团队学习过程，能让所有成员（包括 AI）逐渐对齐对“好代码”的理解。

4.4 方法四：结合静态分析工具（进阶）

虽然规则库本身不是 linter，但你可以利用它的思想来配置或补充静态分析工具。

  1. Dart 的 analysis_options.yaml ：你可以配置更严格的 lint 规则。虽然不能直接实现“函数是否单一职责”这样的复杂判断，但可以在命名、格式、常见坏味道上设置规则，与 IDE-Agent-Rules 的设计原则相辅相成。
  2. 自定义Lint规则（高阶） ：对于有能力的团队，可以考虑以 IDE-Agent-Rules 为蓝本，开发一些自定义的 Lint 规则（例如，警告过长的函数、参数过多的函数），实现自动化检查。

5. 实战案例：用规则指导AI重构一段Flutter代码

让我们看一个具体的例子。假设我们有一段原始的、比较粗糙的 Flutter Widget 代码，是 AI 在没有规则指导时可能生成的：

// 原始代码 (问题较多)
class ProductPage extends StatelessWidget {
  final int id;

  ProductPage(this.id);

  @override
  Widget build(BuildContext context) {
    List<Product> products = []; // 魔法数字/列表初始化不明确
    bool loading = false; // 布尔命名不佳
    String error = '';

    Future<void> getData() async { // 函数名模糊，异步提示弱
      loading = true;
      try {
        var response = await http.get(Uri.parse('https://api.example.com/products/$id'));
        if (response.statusCode == 200) {
          var data = jsonDecode(response.body);
          products = (data['items'] as List).map((e) => Product.fromJson(e)).toList();
        } else {
          error = 'Failed to load';
        }
      } catch (e) {
        error = 'Network error';
      }
      loading = false;
      // 注意：这里缺少 setState 调用，UI不会更新！这是一个典型陷阱。
    }

    return Scaffold(
      appBar: AppBar(title: Text('Product $id')),
      body: loading
          ? Center(child: CircularProgressIndicator())
          : error.isNotEmpty
              ? Center(child: Text(error))
              : ListView.builder(
                  itemCount: products.length,
                  itemBuilder: (ctx, i) => ListTile(
                    title: Text(products[i].name),
                    subtitle: Text('\$${products[i].price}'),
                  ),
                ),
    );
  }
}

这段代码问题很多：状态管理混乱（在 StatelessWidget 中直接修改变量）、 getData 函数职责过多且命名不清、错误处理简陋、UI 逻辑全挤在 build 方法里。

现在，我们运用 IDE-Agent-Rules 的规则，通过清晰的指令引导 AI 进行重构：

给AI的指令： “请遵循以下Flutter整洁代码规则重构上述 ProductPage ：

  1. 使用有意义的命名（如 isLoading , fetchProductList ）。
  2. 将状态管理改为使用 StatefulWidget 或更佳方案（提示：考虑使用 FutureBuilder 避免手动状态管理）。
  3. 遵循单一职责原则：拆分数据获取逻辑。
  4. 妥善处理加载和错误状态。
  5. 将UI构建逻辑拆分为独立的小Widget。”

AI生成的重构后代码（示例）： 

// 重构后代码
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'dart:convert';
import 'product_model.dart'; // 假设Product类在此

class ProductPage extends StatelessWidget {
  final int productId;

  const ProductPage({Key? key, required this.productId}) : super(key: key);

  // 职责分离：数据获取逻辑抽离为独立函数
  Future<List<Product>> _fetchProducts(int id) async {
    const String baseUrl = 'https://api.example.com';
    final uri = Uri.parse('$baseUrl/products/$id');
    final response = await http.get(uri);

    if (response.statusCode == 200) {
      final Map<String, dynamic> data = jsonDecode(response.body);
      final List<dynamic> items = data['items'] as List;
      return items.map((json) => Product.fromJson(json)).toList();
    } else {
      throw Exception('Failed to load products (Status: ${response.statusCode})');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Product Details'),
      ),
      body: FutureBuilder<List<Product>>(
        future: _fetchProducts(productId),
        builder: (context, snapshot) {
          // 清晰的状态处理逻辑
          if (snapshot.connectionState == ConnectionState.waiting) {
            return const _LoadingIndicator();
          } else if (snapshot.hasError) {
            return _ErrorView(errorMessage: snapshot.error.toString());
          } else if (!snapshot.hasData || snapshot.data!.isEmpty) {
            return const _EmptyView();
          } else {
            return _ProductListView(products: snapshot.data!);
          }
        },
      ),
    );
  }
}

// 拆分的UI组件，职责单一
class _LoadingIndicator extends StatelessWidget {
  const _LoadingIndicator();

  @override
  Widget build(BuildContext context) {
    return const Center(child: CircularProgressIndicator());
  }
}

class _ErrorView extends StatelessWidget {
  final String errorMessage;
  const _ErrorView({required this.errorMessage});

  @override
  Widget build(BuildContext context) {
    return Center(child: Text('Error: $errorMessage'));
  }
}

class _EmptyView extends StatelessWidget {
  const _EmptyView();

  @override
  Widget build(BuildContext context) {
    return const Center(child: Text('No products found.'));
  }
}

class _ProductListView extends StatelessWidget {
  final List<Product> products;
  const _ProductListView({required this.products});

  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      itemCount: products.length,
      itemBuilder: (context, index) {
        final product = products[index];
        return _ProductListItem(product: product);
      },
    );
  }
}

class _ProductListItem extends StatelessWidget {
  final Product product;
  const _ProductListItem({required this.product});

  @override
  Widget build(BuildContext context) {
    return ListTile(
      leading: const Icon(Icons.shopping_bag), // 可替换为网络图片
      title: Text(product.name),
      subtitle: Text('\$${product.price.toStringAsFixed(2)}'),
      onTap: () {
        // 处理点击
      },
    );
  }
}

对比与提升：

  1. 命名 ： productId 比 id 更明确， _fetchProducts 清晰表达了异步获取。
  2. 状态管理 ：使用 FutureBuilder ，完全避免了手动管理 loading 、 error 状态的繁琐和易错。
  3. 单一职责 ：数据获取 ( _fetchProducts )、加载视图、错误视图、空视图、列表视图、列表项视图都被拆分为独立的、可复用的 Widget。
  4. 可维护性 ：每个部分都小而专注，修改或测试其中任何一部分都变得非常容易。
  5. 健壮性 ：错误被明确抛出并由 FutureBuilder 统一处理，逻辑更清晰。

这个案例生动展示了，当 AI 被赋予了明确的“行为准则”后，其产出质量能有质的飞跃。

6. 常见问题、挑战与应对策略

在推广和使用这套规则的过程中，我和我的团队遇到了一些典型问题，以下是我们的应对经验。

6.1 问题一：规则与AI的“创造性”冲突

有时，AI 可能会生成一些技术上巧妙但不符合规则的代码（例如，为了简洁而使用了一个超长的链式调用或复杂的表达式）。

  • 应对策略 ：明确告诉 AI “可读性优先于极致的简洁”。在指令中加入“请生成易于团队成员理解和维护的代码，即使它不是最短的写法。” 规则是辅助人的，如果一段 AI 生成的“聪明”代码需要别人花 5 分钟才能看懂，那它就不是好代码。

6.2 问题二：规则过多导致Prompt臃肿

如果把所有规则都塞进 Prompt，可能会影响 AI 对主要任务的理解。

  • 应对策略 ： 分层使用规则 。
    • 全局层 ：将最基础、最通用的规则（如命名规范、文件组织）放入 Cursor 的 .cursorrules 或类似全局配置。
    • 任务层 ：在具体对话中，只提及与当前任务最相关的规则。例如，在写网络请求代码时，强调错误处理和异步命名；在重构大函数时，强调单一职责和函数长度。
    • 建立规则索引 ：为团队维护一个规则索引表，方便快速查找和引用特定规则，而不是每次都复制全文。

6.3 问题三：规则无法覆盖所有场景或存在争议

软件开发没有银弹，某些规则在特定场景下可能不适用（例如，某些简单的工具函数参数略多于3个可能更合理）。

  • 应对策略 ： 将规则视为“默认选项”而非“绝对法律” 。在项目 README 或规则文档开头明确这一点。鼓励开发者在有充分理由时打破规则，但要求他们通过注释说明原因。例如： 
    // 例外：此处接受4个参数，因为它们是配置矩形的四个独立边距，封装为类反而显得冗余。
Widget createPaddedRect(double top, double right, double bottom, double left) { ... }
    同时，规则库本身应该是开放的，鼓励团队成员对存在争议的规则发起讨论和迭代。

6.4 问题四：如何衡量规则带来的效果？

很难直接量化代码质量提升带来的价值。

  • 应对策略 ：关注一些间接但可观察的指标：
    • 代码评审速度 ：符合规则的代码是否更容易、更快地被评审通过？
    • 新手上手速度 ：新成员阅读和修改由 AI 生成、符合规则的代码，是否感觉更顺畅？
    • 缺陷密度 ：在应用规则的模块中，由代码混乱引发的低级 Bug 是否有所减少？
    • 团队共识 ：团队成员在讨论代码时，是否更频繁地引用这些规则作为共同标准？这本身就是一种巨大的成功。

6.5 问题五：如何让团队接受并持续使用？

任何新流程的推行都会遇到阻力。

  • 应对策略 ：
    1. 自上而下示范 ：技术负责人或团队核心成员率先在重要项目或模块中使用，并展示其带来的好处（如更清晰的 PR）。
    2. 提供便捷工具 ：将常用规则制作成代码片段或 IDE 实时模板，降低使用门槛。
    3. 纳入 onboarding ：将规则库作为新成员入职培训的必读材料，帮助他们快速融入团队的代码文化。
    4. 定期回顾与优化 ：在团队技术会议上，定期回顾规则的使用情况，讨论遇到的困难，共同优化规则。让规则成为团队共同成长的产物，而非强加的约束。

7. 未来展望与扩展方向

IDE-Agent-Rules 项目目前只是一个起点。基于目前的实践，我认为有几个方向值得深入探索：

  1. 规则的情景化与智能化 ：未来的规则可能不再是静态的文本，而是能根据项目类型（是前端 UI 还是后端服务）、代码上下文（所在文件是模型层还是视图层）动态推荐最相关的子集。甚至，AI 助手可以学习团队的历史代码库，自动归纳和推荐适合本团队的定制化规则。
  2. 与开发工具的深度集成 ：想象一下，在 IDE 中，当你让 AI 生成代码时，它能自动加载当前项目配置的规则集；在代码评审界面，AI 能自动标注出可能违反团队规则的代码片段并给出修改建议。这需要规则有一种更结构化的表达方式（如 YAML/JSON Schema），便于工具解析。
  3. 多语言支持与领域特化 ：目前以 Dart/Flutter 为主，但整洁代码的原则是通用的。社区可以共同贡献 Java、Python、Go、Rust、JavaScript/TypeScript 等语言的实施细则。更进一步，可以为 Web 开发、移动端、数据科学等不同领域制定更具针对性的规则。
  4. 从“代码生成”到“架构守护” ：规则的范围可以从代码风格、设计模式，扩展到架构层面。例如，定义清晰的层边界（如 UI 层不能直接调用数据层）、依赖注入的规范、特定设计模式（如 Repository, BLoC）的实现模板等，引导 AI 生成更符合项目架构的代码。

这个项目的最终愿景，是成为连接人类开发者智慧与 AI 编码能力的一座桥梁。它不是要束缚创造力，而是通过建立共识和最佳实践，让 AI 生成的代码能无缝融入我们的工程体系，让开发者能更专注于创造性的逻辑和业务创新，而不是在混乱的代码中挣扎。

# 代码规范
Logo
亚马逊云科技技术品牌专区

更多推荐

cover

DeepSeek API涨价500%！Agent框架同步开源

avatar 亚马逊云科技技术品牌专区
cover

Agent Run 的状态机：别把智能体交给 LLM 自己管

avatar 亚马逊云科技技术品牌专区
cover

【python】【FastAPI 进阶】《FastAPI 异步内核剖析：中间件链与 SQLAlchemy 异步驱动的全链路非阻塞实践》

avatar 亚马逊云科技技术品牌专区