Flutter AI编程规范：构建可验证的三层代码契约体系

1. 项目概述：为什么“让AI写代码不翻车”成了Flutter团队的刚需

最近三个月，我陆续给三家不同规模的团队做过Flutter工程规范咨询，从初创公司到中型技术部门，几乎每场沟通开场都会听到一句：“我们试过让Claude和Codex直接生成页面逻辑，结果三天改了七版，比手写还累。”这不是段子，是真实发生的工程事故。核心问题从来不是AI写得不够快，而是它根本不知道你的项目里lib/src/widgets/下面那个base_stateful_widget.dart到底继承自哪个抽象基类、api_client实例是单例还是按需构造、甚至theme_mode切换时状态管理器该不该触发重建——这些细节，恰恰是Flutter项目在200+页面、30+模块、5人以上协作时最容易引发“雪崩式重构”的雷区。

“让AI写代码不翻车”这个标题，表面看是讲工具链，实则直指一个被严重低估的现实：AI代码生成不是替代开发者，而是放大开发者的决策体系。你喂给它的上下文越模糊，它输出的代码就越像一份充满隐性假设的“待确认草案”。而Flutter生态的特殊性在于，它的灵活性（比如Widget树深度定制、State生命周期钩子自由组合）和约束性（比如BuildContext不可跨帧复用、InheritedWidget数据流必须严格遵循树结构）并存，稍有不慎，AI生成的代码就会在热重载时看似正常，上线后却在低端安卓机上因Build耗时超标触发ANR，或者在深色模式切换时因未监听MediaQuery变化导致主题错乱。

所以本项目真正的落点，不是“怎么调用Claude API”，而是构建一套可被AI理解、可被团队执行、可被CI验证的三层规范体系：第一层是机器可读的代码契约（比如Dart Analyzer规则、自定义linter插件），第二层是人类可维护的提示词模板（prompt engineering for Flutter），第三层是工程可落地的自动化守门人（pre-commit hook + CI pipeline）。这三者缺一不可。比如，当AI生成一个FutureBuilder时，规范会强制它必须包含errorBuilder且不能返回nullwidget；当它创建一个ChangeNotifier时，必须显式声明@override void dispose()并调用父类方法——这些不是靠开发者肉眼Review能100%守住的底线，而是必须由工具链自动拦截的硬性红线。

这套方案特别适合两类人：一类是正在从纯手写转向AI辅助开发的Flutter老手，你们需要把多年踩坑经验转化成机器能执行的规则；另一类是刚组建Flutter团队的技术负责人，你们急需在代码风格、状态管理选型、网络层封装等关键决策上建立统一认知，避免新人用AI生成五花八门的Repository实现方式。它不承诺“零Bug”，但能确保每次AI生成的代码，都落在团队共同约定的“安全操作域”内。接下来，我会拆解这套体系如何从设计思路、核心细节到实操落地一步步构建起来。

2. 整体设计与思路拆解：为什么是Claude Code + Codex，而不是Copilot或Cursor？

选择Claude Code和Codex组合，不是跟风，而是基于Flutter项目特有的“高语义密度+强上下文依赖”特征做的针对性取舍。先说结论：Claude Code负责理解复杂业务逻辑和工程约束，Codex负责生成符合Dart语言惯用法的高质量片段，二者分工明确，互为补足。这和单纯用GitHub Copilot“补全单行代码”的思路有本质区别。

为什么不用Copilot？Copilot的核心优势在于海量公开代码库的统计建模，但它对私有代码库的理解深度有限。我实测过，在一个封装了自定义BlocDelegate和HydratedBloc的Flutter项目里，Copilot生成的BlocBuilder示例，90%会忽略buildWhen参数的必要性，直接返回true，导致不必要的Widget重建。更致命的是，它无法识别项目中已弃用的Provider.of<T>(context, listen: false)写法，仍会高频推荐——这种“过时但流行”的惯性，恰恰是团队规范最需要切断的路径依赖。

Claude Code的优势在于其长上下文窗口（200K tokens）和强推理能力。当我把整个lib/core/目录结构、analysis_options.yaml配置、以及README.md里关于“所有API错误必须转为Failure类型”的约定一次性喂给它，并要求“生成一个登录页的BLoC实现”，它输出的LoginBloc不仅自动实现了Equatable，还在mapEventToState里为每个LoginRequested事件添加了debounce防抖逻辑，并在onError回调中调用了项目约定的logger.e()方法——这些细节，Copilot在没有显式提示的情况下几乎不会主动补充。

那Codex又扮演什么角色？Codex是OpenAI在CodeX模型基础上专为代码生成优化的版本，它对Dart语法糖（比如?..级联操作符、late final语义、const构造函数推导）的掌握更精准。比如，当Claude Code给出“需要一个不可变的用户配置类”的高层指令后，Codex能稳定输出：

@immutable class UserConfig { final String baseUrl; final Duration timeout; final bool enableLogging; const UserConfig({ required this.baseUrl, required this.timeout, required this.enableLogging, }); factory UserConfig.fromJson(Map<String, dynamic> json) => UserConfig( baseUrl: json['base_url'] as String, timeout: Duration(milliseconds: json['timeout_ms'] as int), enableLogging: json['enable_logging'] as bool, ); }

注意它自动使用了@immutable注解、const工厂构造、类型断言而非as强转——这些正是Dart官方推荐的最佳实践，也是Flutter团队代码审查中最常被挑刺的点。

二者组合的工作流是：Claude Code做“架构师”，负责理解需求、拆解任务、生成伪代码和接口契约；Codex做“高级工程师”，负责将契约转化为符合Dart语言特性的、零警告的生产级代码。中间通过一个轻量级的“提示词编排器”（Prompt Orchestrator）衔接：它把Claude的输出解析为结构化JSON（含required_imports、expected_methods、must_avoid_patterns等字段），再注入Codex的输入上下文。这个设计绕开了“让一个模型同时搞定理解和生成”的性能瓶颈，实测下来，生成代码的analyzer警告率从平均4.7个/文件降到0.3个/文件，且首次提交通过CI lint检查的比例达92%。

提示：不要试图用单一模型解决所有问题。就像Flutter里StatefulWidget和StatelessWidget分工明确一样，AI工具链也需要“职责分离”。Claude处理“为什么”，Codex处理“怎么做”，而你作为工程师，专注定义“应该是什么”。

3. 核心细节解析与实操要点：三层规范体系如何落地

这套规范体系的真正价值，不在于它多炫酷，而在于每一层都直击Flutter团队日常协作的痛点。我把它拆解为三个可独立部署、又能无缝集成的模块：机器可读的代码契约层、人类可维护的提示词模板层、工程可落地的自动化守门人层。下面逐层详解每个模块的核心设计、关键配置和避坑经验。

3.1 机器可读的代码契约层：让Dart Analyzer成为AI的“语法老师”

很多人以为analysis_options.yaml只是关掉几个烦人的警告，其实它是Flutter项目最基础的“AI训练教材”。当Claude或Codex生成代码时，它们会隐式参考Dart SDK和Pub包的类型定义，但对你的项目私有规则一无所知。契约层要做的，就是把这些规则变成Analyzer能识别的、带错误级别的硬性约束。

核心配置分三块：

第一块：强化Dart语言基础规范

analyzer: errors: # 强制所有Widget构造函数必须为const（除非有明确理由） prefer_const_constructors: error # 禁止使用dynamic，必须显式声明类型 avoid_dynamic_calls: error # 所有Future必须显式指定泛型，禁止Future<dynamic> always_specify_types: error language: strict-raw-types: true strict-inference: true

这里的关键是strict-raw-types: true。它会让List这种写法直接报错，强制写成List<String>。为什么重要？因为AI生成的代码里，dynamic和裸List是高频错误源。Claude在生成网络请求响应处理逻辑时，常会写final data = response.data;，而data类型是dynamic，后续.map()调用就失去类型安全。这个配置能让它在本地保存时立刻暴露问题，而不是等到CI阶段才失败。

第二块：注入Flutter专属规则

linter: rules: # 必须使用const构造函数创建Widget（提升性能） - prefer_const_constructors_in_immutables # State类中必须重写dispose()，且必须调用super.dispose() - must_call_super # 所有InheritedWidget必须实现updateShouldNotify() - must_implement_update_should_notify # 禁止在build()方法中创建新对象（如{}、[]、() => {}） - avoid_unnecessary_containers

这些规则不是凭空而来。must_call_super直接对应Flutter文档里关于State.dispose()的强制要求；avoid_unnecessary_containers则针对AI高频错误——它喜欢在Column里嵌套一个Container再放Text，而实际只需Text加padding属性。这些规则让Analyzer从“语法检查器”升级为“Flutter最佳实践教练”。

第三块：自定义规则——把团队经验变成机器指令这是最关键的一步。我们用custom_lint包创建了一个no_legacy_provider规则，专门拦截已弃用的Provider.of<T>(context)写法：

// lib/lint_rules/no_legacy_provider.dart class NoLegacyProviderRule extends DartLintRule { @override final String name = 'no_legacy_provider'; @override final String description = '禁止使用已弃用的Provider.of<T>(context)'; @override final String details = '必须使用Provider<T>.watch(context)或Provider<T>.read(context)'; @override Visitor generateAstVisitor(Context context) { return _Visitor(context); } } class _Visitor extends SimpleAstVisitor<void> { final Context _context; _Visitor(this._context); @override void visitMethodInvocation(MethodInvocation node) { final target = node.methodName?.name; if (target == 'of' && node.realTarget?.toString().contains('Provider')) { // 检查是否缺少第二个参数（listen: false） final hasListenParam = node.argumentList.arguments .any((arg) => arg is NamedExpression && arg.name.label.name == 'listen'); if (!hasListenParam) { _context.reportLint(NoLegacyProviderRule(), node); } } } }

编译后，只要AI生成Provider.of<UserModel>(context)，Analyzer立刻标红并提示“请改用Provider<UserModel>.watch(context)”。这比Code Review时口头提醒“记得用新API”有效十倍。

注意：自定义规则必须经过充分测试。我建议用test包写单元测试，模拟AI生成的各种边界情况（如嵌套调用、泛型嵌套），确保规则不会误伤合法代码。曾有个团队的自定义规则因未处理Provider.of<T>(context, listen: false)的合法场景，导致所有initState里的Provider调用全部报错，耽误了两天。

3.2 人类可维护的提示词模板层：给AI一本Flutter“开发手册”

再强大的模型，没有清晰的指令也会胡说八道。提示词模板层的目标，是把团队的工程规范、架构决策、甚至历史教训，转化成AI能精准理解的“自然语言指令集”。它不是一堆晦涩的术语堆砌，而是一本活的、可迭代的Flutter开发手册。

模板设计遵循“三层指令”原则：

第一层：角色定义（Role Definition）

你是一位资深Flutter架构师，拥有5年以上大型跨平台应用开发经验。 你熟悉Riverpod 2.4+、Flutter 3.19+、Dart 3.3+的所有特性。 你坚持以下原则： - 所有Widget必须是const且不可变（除非明确需要State） - 所有网络请求必须通过统一的ApiClient封装，禁止直接使用http.Client - 所有错误必须转为Failure类型，并通过统一的ErrorHandler处理 - 所有状态管理必须使用Riverpod，禁止使用setState或BLoC

关键点在于“具体版本号”和“禁止项”。AI对“最新版”这种模糊表述容易产生歧义（它可能认为3.16是最新），而明确写出Riverpod 2.4+能锁定它的知识边界；列出禁止使用setState比说“推荐Riverpod”更有效，因为AI更擅长遵守禁令而非理解推荐。

第二层：任务拆解（Task Decomposition）

请按以下步骤完成： 1. 分析需求：识别核心Widget、所需State、依赖的Repository和服务 2. 生成接口契约：定义Repository接口、Failure枚举、State类（使用freezed） 3. 生成UI层：构建Widget树，使用Riverpod ProviderConsumer，包含loading/error/success状态 4. 生成业务逻辑层：实现Repository，使用ApiClient，添加超时和重试逻辑 5. 生成测试：为State类和Repository编写单元测试，覆盖success/failure场景

这个结构强制AI按Flutter标准分层架构（Presentation/Business/Data）思考，避免它直接生成一个“大而全”的LoginPage类，把网络请求、状态更新、UI渲染全塞进去。实测显示，按此结构生成的代码，后续人工重构工作量减少60%以上。

第三层：格式约束（Format Constraints）

输出必须严格遵循以下格式： - 使用Markdown代码块，语言标记为dart - 每个代码块前用## 标题说明用途（如## Repository Interface） - 所有import语句必须完整，禁止省略 - 所有类名、方法名必须符合Dart命名规范（驼峰式） - 禁止使用TODO、FIXME等占位符 - 所有字符串必须使用单引号，数字字面量禁止使用科学计数法

这些看似琐碎的约束，实则是降低后续人工整合成本的关键。AI生成的代码如果混用单双引号、随意缩进、漏掉import，开发者需要花大量时间做格式清洗，反而拖慢整体效率。而标准化格式让AI输出能直接复制粘贴进项目，经Analyzer扫描后即可进入开发流程。

实操心得：提示词模板必须和团队代码审查清单同步更新。我们每周五下午固定30分钟，由主程牵头，把本周Code Review中发现的3个高频问题（如“忘记在dispose中取消StreamSubscription”、“未对Nullable类型做空值检查”）提炼成新的提示词约束，加入模板。坚持三个月后，这些问题在AI生成代码中的出现率归零。

3.3 工程可落地的自动化守门人层：让CI/CD成为最后防线

再完善的提示词和Analyzer规则，也无法100%杜绝AI生成的“合法但危险”代码。比如，Analyzer不会报错Future.delayed(Duration.zero, () => setState(() {}))，但这行代码在Flutter里是典型的“微任务陷阱”，会导致UI线程卡顿。守门人层的作用，就是用自动化手段，在代码合并前做最后一道“行为级”审查。

我们构建了三级守门人：

第一级：Pre-commit Hook（本地守门人）使用husky+lint-staged，在git commit前自动运行：

// package.json "husky": { "hooks": { "pre-commit": "lint-staged" } }, "lint-staged": { "**/*.{dart}": [ "dart format", "dart analyze --fatal-infos --fatal-warnings", "dart run custom_lint:custom_lint --reporter=github" ] }

关键点在于--fatal-warnings：它把所有Analyzer警告（而不仅是错误）视为失败，强制开发者修复。很多团队只设--fatal-errors，结果AI生成的// ignore: unnecessary_null_comparison注释满天飞，久而久之，警告就失去了警示意义。

第二级：CI Pipeline（分支守门人）在GitHub Actions中，为develop和main分支设置严格检查：

# .github/workflows/ci.yml - name: Run Custom Lint run: dart run custom_lint:custom_lint --reporter=github --rules="no_legacy_provider,no_unsafe_build_context" - name: Run Integration Tests run: flutter test --platform chrome --tags "ai_generated"

这里有个精妙设计：我们给所有AI生成的Widget测试文件打上@Tags(['ai_generated'])标签，并在CI中单独运行。一旦这些测试失败，立即阻断合并，因为这意味着AI生成的代码存在运行时缺陷，而非静态分析能发现的问题。

第三级：Post-merge Audit（线上守门人）在main分支合并后，触发一个后台任务，扫描本次提交中所有新增的.dart文件，提取其中的FutureBuilder、StreamBuilder、ProviderConsumer等高风险Widget，生成一份“AI生成代码健康报告”，发送给技术负责人：

本次合并新增AI生成代码12处： - 8处 FutureBuilder：全部包含errorBuilder，达标 ✅ - 3处 StreamBuilder：2处未调用cancel()，需人工复查 ⚠️ - 1处 ProviderConsumer：正确使用ref.watch()，达标 ✅

这份报告不用于阻断发布，而是作为团队技术债的量化指标。连续两周“未调用cancel()”问题超过3次，就触发专项培训——用数据驱动改进，而非靠主观感觉。

注意：守门人必须“可绕过但难忽略”。我们允许开发者用git commit --no-verify跳过pre-commit，但CI会严格拦截；也允许在紧急情况下手动合并，但Audit报告会永久记录。这种设计既保证了流程严肃性，又保留了应对突发状况的弹性。

4. 实操过程与核心环节实现：从零搭建完整工作流

现在，让我们把前面所有设计，变成一份可立即执行的实操指南。整个过程分为四个阶段：环境初始化、规范配置、提示词编排、CI集成。每个阶段我都附上真实命令、配置文件内容和关键参数说明，确保你能照着步骤，30分钟内跑通全流程。

4.1 阶段一：环境初始化——安装必要工具链

首先确保你的开发机已安装以下基础环境（Flutter 3.19+，Dart 3.3+）：

# 检查Flutter版本 flutter --version # 应输出类似：Flutter 3.19.5 • channel stable • https://github.com/flutter/flutter.git # 安装husky（用于pre-commit hook） dart pub global activate husky # 安装custom_lint（用于自定义规则） dart pub global activate custom_lint # 创建项目（如已有项目，跳过此步） flutter create --org com.example my_flutter_app cd my_flutter_app

关键点在于dart pub global activate而非flutter pub add。global activate让工具在系统级可用，确保pre-commit hook和CI脚本能全局调用；而pub add只在当前项目生效，CI环境中可能找不到命令。

接着初始化husky：

# 在项目根目录执行 dart pub global run husky:init # 这会创建.husky/目录和pre-commit脚本

此时，.husky/pre-commit文件内容应为：

#!/bin/sh . "$(dirname "$0")/_/husky.sh" # 运行lint-staged npx lint-staged

提示：如果遇到npx: command not found错误，说明你的系统未安装Node.js。Flutter项目虽不依赖Node，但husky需要它来执行脚本。此时可改用纯Dart方案：在.husky/pre-commit中直接写dart run lint_staged:lint_staged，前提是已通过dart pub global activate lint_staged安装。

4.2 阶段二：规范配置——编写analysis_options.yaml和自定义规则

在项目根目录创建analysis_options.yaml，内容如下（已按前述三层规范整合）：

# analysis_options.yaml include: package:flutter_lints/flutter.yaml analyzer: errors: prefer_const_constructors: error avoid_dynamic_calls: error always_specify_types: error language: strict-raw-types: true strict-inference: true linter: rules: - prefer_const_constructors_in_immutables - must_call_super - must_implement_update_should_notify - avoid_unnecessary_containers - lines_longer_than_80_chars - public_member_api_docs # 启用自定义规则 custom_lint: rules: - no_legacy_provider - no_unsafe_build_context

然后创建自定义规则目录：

mkdir -p lib/lint_rules touch lib/lint_rules/no_legacy_provider.dart

lib/lint_rules/no_legacy_provider.dart完整代码（已精简为可直接运行版本）：

// lib/lint_rules/no_legacy_provider.dart import 'package:analyzer/dart/ast/ast.dart'; import 'package:analyzer/dart/ast/visitor.dart'; import 'package:analyzer/source/source_range.dart'; import 'package:custom_lint/custom_lint.dart'; class NoLegacyProviderRule extends DartLintRule { @override final String name = 'no_legacy_provider'; @override final String description = '禁止使用已弃用的Provider.of<T>(context)'; @override final String details = '必须使用Provider<T>.watch(context)或Provider<T>.read(context)'; @override Visitor generateAstVisitor(Context context) { return _Visitor(context); } } class _Visitor extends SimpleAstVisitor<void> { final Context _context; _Visitor(this._context); @override void visitMethodInvocation(MethodInvocation node) { final target = node.methodName?.name; final typeName = node.realTarget?.toString(); if (target == 'of' && typeName != null && typeName.contains('Provider')) { final hasListenParam = node.argumentList.arguments .any((arg) => arg is NamedExpression && arg.name.label.name == 'listen'); if (!hasListenParam) { _context.reportLint( NoLegacyProviderRule(), node, message: '使用Provider.of<T>(context)已弃用，请改用Provider<T>.watch(context)', ); } } } }

最后，在pubspec.yaml中注册规则：

dev_dependencies: flutter_test: sdk: flutter flutter_lints: ^3.0.0 custom_lint: ^0.5.0 # 添加这行，指向你的规则文件 custom_lint_rules: path: ./lib/lint_rules

运行dart pub get后，执行dart analyze，你应该能看到Analyzer开始检查自定义规则。如果报错Could not find package 'custom_lint_rules'，检查path是否为相对路径且指向正确目录。

4.3 阶段三：提示词编排——构建Claude+Codex协同工作流

我们不依赖任何第三方IDE插件，而是用最简单的curl+jq组合，构建一个可复用的提示词编排脚本。在项目根目录创建scripts/prompt_orchestrator.sh：

#!/bin/bash # scripts/prompt_orchestrator.sh # 从命令行参数获取需求描述 DESCRIPTOR=$1 if [ -z "$DESCRIPTOR" ]; then echo "Usage: $0 <feature_description>" exit 1 fi # 构建Claude请求体（简化版，实际使用需替换API Key） CLAUDE_PROMPT=$(cat <<EOF 你是一位资深Flutter架构师。请为以下需求生成详细设计文档： 需求：${DESCRIPTOR} 要求： - 输出JSON格式，包含：interface_contract（Repository接口）、state_class（Freezed State）、widget_tree（Widget树结构） - 所有类名使用PascalCase，方法名使用camelCase - 网络请求必须通过ApiClient，错误必须转为Failure - 不要生成实际代码，只输出结构化设计 EOF ) # 模拟调用Claude API（此处用echo代替，实际替换为curl） echo "${CLAUDE_PROMPT}" > /tmp/claudes_output.json # 解析Claude输出，提取interface_contract INTERFACE=$(jq -r '.interface_contract' /tmp/claudes_output.json 2>/dev/null) if [ -z "$INTERFACE" ]; then INTERFACE="class UserRepository { Future<User> fetchUser(int id); }" fi # 构建Codex请求体 CODEX_PROMPT=$(cat <<EOF 请根据以下接口契约，生成完整的Dart实现： ${INTERFACE} 要求： - 使用Dart 3.3语法，启用sealed classes - 所有import语句必须完整 - 方法必须有完整文档注释 - 返回Future的方法必须添加超时和错误处理 - 输出纯Dart代码，无额外说明 EOF ) # 调用Codex（此处用echo模拟） echo "```dart" echo "$CODEX_PROMPT" | sed 's/^/ /' echo "```"

赋予执行权限：

chmod +x scripts/prompt_orchestrator.sh

现在，你可以这样使用：

# 生成用户详情页的Repository ./scripts/prompt_orchestrator.sh "用户点击头像进入详情页，显示用户基本信息和最近3条动态"

输出会是一个格式化的Dart代码块，可直接复制到lib/data/repositories/user_repository.dart。这个脚本的价值在于，它把复杂的多步提示词工程，封装成一个原子化命令，让团队成员无需理解底层模型差异，就能获得一致的高质量输出。

实操心得：第一次运行时，Claude可能返回非JSON格式。此时不要修改脚本，而是优化提示词——在Claude Prompt末尾加上“请严格输出JSON，不要任何额外文字”。AI对“严格”“必须”“禁止”等绝对化词汇响应更准确，这是经过上百次测试验证的经验。

4.4 阶段四：CI集成——配置GitHub Actions自动化流水线

在.github/workflows/ci.yml中，配置完整的CI流水线：

name: Flutter CI on: push: branches: [develop, main] pull_request: branches: [develop, main] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Flutter uses: subosito/flutter-action@v2 with: flutter-version: '3.19.x' - name: Install Dependencies run: flutter pub get - name: Run Dart Analyzer run: dart analyze --fatal-infos --fatal-warnings - name: Run Custom Lint run: dart run custom_lint:custom_lint --reporter=github - name: Run Tests run: flutter test --coverage - name: Upload Coverage to Codecov uses: codecov/codecov-action@v3 with: file: ./coverage/lcov.info

关键参数说明：

• flutter-version: '3.19.x'：使用x通配符，确保CI始终使用3.19系列最新补丁版，避免因小版本差异导致Analyzer行为不一致。
• --fatal-infos：连Info级提示都视为失败。例如，Analyzer会提示“const构造函数可提升性能”，这类提示对AI生成代码质量有直接影响，不应忽略。
• --reporter=github：让custom_lint的错误直接显示在GitHub PR界面，开发者无需切换到Actions日志就能看到问题。

为了验证CI是否生效，可以故意在代码中引入一个no_legacy_provider违规：

// lib/presentation/login/login_page.dart class LoginPage extends StatelessWidget { @override Widget build(BuildContext context) { // 这行会触发custom_lint报错 final user = Provider.of<UserModel>(context); return Text(user.name); } }

提交PR后，CI会立即失败，并在Checks标签页显示红色错误：“使用Provider.of (context)已弃用...”。这就是守门人起效的标志。

注意：CI配置必须和本地pre-commit保持一致。我们要求所有团队成员在git push前必须git pull origin develop，确保本地Analyzer版本与CI完全同步。曾有个团队因本地Dart SDK是3.18，CI是3.19，导致sealed class语法在本地不报错，CI却失败，浪费了大量排查时间。

5. 常见问题与排查技巧实录：那些只有亲手搭过才懂的坑

在给多个团队落地这套方案的过程中，我整理了一份“血泪清单”，记录了所有真实发生过的、文档里绝不会写的典型问题。这些问题往往不在技术原理层面，而藏在环境、权限、版本耦合等灰色地带。分享出来，帮你少走至少两周弯路。

5.1 问题一：Analyzer规则在CI中不生效，本地却正常

现象：本地运行dart analyze能检测出自定义规则，但CI中dart run custom_lint:custom_lint命令执行后无任何输出，也不报错。

排查路径：

1. 首先检查CI日志中dart pub get的输出，确认custom_lint_rules包是否被正确解析。常见错误是pubspec.yaml中path: ./lib/lint_rules写成了path: lib/lint_rules（少了.），导致pub无法识别为本地路径。
2. 运行ls -la lib/lint_rules/，确认目录下确实存在.dart文件，且文件名与custom_lint配置中的规则名完全匹配（大小写敏感）。
3. 最关键一步：在CI脚本中添加调试命令：

   - name: Debug Custom Lint run: | dart run custom_lint:custom_lint --list-rules dart run custom_lint:custom_lint --reporter=json

   --list-rules会输出所有已加载的规则列表，如果no_legacy_provider不在其中，说明路径配置错误；--reporter=json会强制输出JSON格式，即使无错误也会打印空数组，便于确认命令是否真正执行。

根本原因：custom_lint在CI环境中默认不扫描lib/以外的目录，而我们的规则放在lib/lint_rules/，属于lib/子目录，按理应被扫描。但某些Dart SDK版本存在路径解析bug，必须显式指定--rules-dir参数：

- name: Run Custom Lint run: dart run custom_lint:custom_lint --rules-dir=lib/lint_rules --reporter=github

5.2 问题二：Pre-commit Hook被绕过，开发者习惯性用git commit -m

现象：团队成员反馈“pre-commit没起作用”，检查发现他们常用git commit -m "xxx"，而husky的hook只对git commit（无参数）生效。

解决方案：

1. 在项目根目录创建.husky/commit-msg脚本，强制校验commit message格式：

   #!/bin/sh . "$(dirname "$0")/_/husky.sh" if ! grep -qE '^(feat|fix|docs|style|refactor|test|chore|revert):' "$1"; then echo "Commit message must start with type: (e.g., feat:, fix:)" exit 1 fi

2. 更彻底的方案：在.husky/pre-commit中添加强制检查：

   #!/bin/sh . "$(dirname "$0")/_/husky.sh" # 检查是否绕过hook if [ -z "$HUSKY" ]; then echo "❌ Husky not loaded. Please run 'git commit' without -m flag, or set HUSKY=1" exit 1 fi npx lint-staged

深层逻辑：这不是技术问题，而是协作习惯问题。我们要求所有commit必须关联Jira ID（如feat(LOGIN-123): add biometric login），而-m参数无法支持这种结构化message。通过强制格式，倒逼开发者使用IDE的图形化commit界面，那里husky hook天然生效。

5.3 问题三：Claude生成的代码包含// ignore:注释，绕过Analyzer检查

现象：AI生成的代码里高频出现// ignore: unnecessary_null_comparison，导致Analyzer警告被人为抑制，失去规范意义。

根治方法：

1. 在analysis_options.yaml中，禁用所有// ignore：

   analyzer: errors: # 禁止使用ignore注释 invalid_ignore: error

   这条规则会让任何// ignore:注释本身变成错误，AI无法再用它“作弊”。

2. 在提示词模板中，增加硬性约束：

   禁止使用任何// ignore: 注释 如果Analyzer报错，请修改代码逻辑而非添加ignore

3. 在CI中添加二次扫描：

   - name: Check for Ignore Comments run: | if grep -r "// ignore:" lib/; then echo "❌ Found // ignore: comments. Remove them and fix the underlying issue." exit 1 fi

为什么有效：invalid_ignore: error是Dart Analyzer内置规则，它比任何自定义规则都底层。一旦启用，连// ignore: undefined_identifier这种明显错误都无法用注释绕过，彻底堵死AI的“捷径”。

5.4 问题四：Codex生成的代码在Flutter Web上运行报错，但Android/iOS正常

现象：AI生成的FutureBuilder在Web端触发Uncaught Error: Unsupported operation: Platform._operatingSystem，而在手机端一切正常。

原因定位：

1. 检查Codex生成的代码，发现它调用了`Platform