Flutter项目AI工程规范实战：驯服Claude Code与Codex-北京尧图网络

前阵子团队把一个中型Flutter项目整体交给AI编程助手来维护Claude Code和Codex轮着用结果翻车翻得我一度怀疑人生。最离谱的一次AI在一个下单页面里直接塞了三百行业务逻辑连网络请求都写在build方法里编译没问题跑起来也不崩但代码评审真的一眼都看不下去。折腾了大半个月我总结出一条核心经验想让AI写代码不翻车关键不在换更强的模型而是先给项目搭一套AI能读懂的工程规范。这篇文章就完整记录一下我是怎么用Claude Code和Codex给Flutter项目搭建工程规范的包括规范文件怎么写、工具怎么配置、CI怎么把关以及调试过程中踩过的那些坑。如果你也在用AI写Flutter或者正准备让团队里的AI编程助手真正提升效率这篇文章应该能帮你少走很多弯路。1. AI写Flutter代码为什么会“翻车”三个经典现场1.1 现场一目录结构完全失控Flutter项目对目录结构的要求其实挺讲究的至少团队内部要有统一约定。但AI在没有明确指引的时候完全凭模型内部的代码分布做判断。我遇过的情况是这样的它建议新增一个登录页面结果在lib/pages/下建了login_page.dart在lib/screens/下又建了一个LoginScreen.dart两个文件功能几乎一样只是命名风格不同。我追问它为什么这么建它的原话是“为了保持结构清晰”。更烦的是它会根据prompt里的一句话自动创建目录比如lib/modules/、lib/features/、lib/ui/混着来。新文件摆在哪个目录完全取决于对话历史里最后出现过的那个路径。这样的结果就是代码库结构被严重污染手工合并的时候非常难受。1.2 现场二状态管理写法“大杂烩”Flutter生态有个特点状态管理方案非常多provider、riverpod、bloc、getx、setState各有各的适用场景。团队内部只要选定了方案就应该在整个项目里保持一致。但AI不这么想它在一个文件里用ChangeNotifier换一个文件又用setState再换一个场景直接上StreamBuilder。我印象最深的是有一次它生成一个列表页用了FutureBuilder加载数据同时又在页面里自己维护了一个TextEditingController来管理搜索框结果搜索状态根本同步不上页面反复重建性能问题一个接一个。我跟它说“项目统一用Riverpod”它的确会改但只要对话窗口长一点它又忘了上下文重新回到自己的“万能模板”。说实话单独来看这些写法都能跑但混在一起就是代码库灾难。维护的人得同时懂三套状态管理模式才能改得动这恰恰是工程规范要解决的最核心问题之一。1.3 现场三看似能跑评审却要命AI生成的代码最迷惑人的地方在于它给出来的方案表面完整函数命名合理注释也写得像模像样很容易蒙混过review。实际上里面埋了不少雷把API返回的原始Map直接存到Model里UI层到处硬编码图片路径和颜色值错误处理被吞掉甚至连路由都没注册就敢在代码里用Navigator.push。我让AI写一个订单详情页它自己发明了一个OrderRepository但项目里根本没这个类。编译报错之后它马上又“编”了一次这次居然在main.dart里快速生成了一整套伪实现。全程给人的感觉就是它一直在讲故事而不是在写真实项目中的代码。它的依据不是项目里的真实结构而是模型见过的“海量历史项目平均值”。1.4 根因AI不读文档你也没给它文档总结下来这些问题最底层的共同点不是模型蠢而是它真的不知道你的项目长什么样。AI编程助手本身具备很强的代码生成能力但它对单个项目的理解完全依赖上下文。你给它多少有效信息它就产出多少符合预期的代码。你什么都不给它就只能“平均发挥”而这往往跟团队规范背道而驰。所以我们需要的不是让AI变得更聪明而是建立一套机制把项目的结构约定、写法规范、禁止事项、行业标准都塞进它的上下文里让它每次动手前先看一遍规则。这也是这篇文章要讲的核心工程规范不只是给人看的文档更是给AI看的“项目宪法”。2. 整体设计思路给项目建立“AI可读的工程宪法”2.1 规范体系的三个层级我一开始犯过一个错误把规范全写在一个超长的Markdown文件里塞到项目根目录指望AI每次都能完整读取。实测下来根本不现实上下文窗口有限规则文件一长AI就开始选择性失明只遵守前面几条后面的全部当作不存在。后来我把规范拆成三层第一层是全局规则放在根目录的AGENTS.md或CLAUDE.md里内容只写团队最核心的公约比如状态管理方案、目录结构总览、禁止在Model里写网络请求这类红线控制在40行以内。第二层是模块规则放在每个feature目录下比如lib/features/login/里放一个README.md或SPEC.md说明这个模块特有的约束、依赖关系、数据流方向。第三层是单文件要求通过代码模板和lint规则隐式约束比如analysis_options.yaml里的自定义规则、.editorconfig、以及统一的代码片段模板。这样分层的好处是AI在处理具体模块时只需要加载少量高相关的规则而不是把所有内容一股脑读一遍。你让它改登录模块的代码它先看登录目录下的SPEC再翻全局规则上下文占用小执行力反而更强。2.2 两个工具的加载机制差异Claude Code和Codex虽然都是AI编程助手但对项目上下文的管理方式有些区别。Claude Code对项目根目录下的CLAUDE.md非常敏感每次对话开始时基本会自动加载而且它对Markdown结构的理解相当好标题层级、表格、列表都能正确解析。Codex这边的习惯不太一样它在项目根目录优先找AGENTS.md这也是目前业界逐渐形成的通用约定。如果你两个工具混用最好在项目里同时保留这两个文件内容保持一致避免AI“换个入口”就换了一套行为。表格式对比配置项Claude CodeCodex默认读取的规则文件CLAUDE.mdAGENTS.md规则文件格式偏好Markdown层级清晰支持较长列表更倾向于简洁、条目式指令对上下文相关文件的自动感知较强能做仓库级搜索较依赖命令行指定的上下文对增量修改的稳定性对话较长时偶尔跑偏独立任务模式下更稳定适合的任务大型重构、跨文件修改、方案讨论局部功能实现、单文件代码生成这个差异是我实际对比用了两三周才摸清楚的。现在的工作流是大方向上的重构和代码库探索用Claude Code单文件实现和小步迭代交给Codex两者共享同一套规范文件。2.3 为什么同时用Claude Code和Codex而不是只选一个有人问我既然要建规范为什么不锁定一个工具我的真实体会是现阶段没有任何一个AI编程助手能全覆盖所有场景。Claude Code在复杂语义理解上更强给它一个模糊的“订单模块状态管理乱了帮我梳理”它给出的方案通常有全局视角Codex则在代码补全和单文件生成上更快更直接你给它一个明确的函数签名它产出的实现质量很高。同时用两个工具还有一个组织层面的好处团队里不同人偏好不同强制统一工具会降低大家的使用意愿。但规范文件是统一工具只要规范一致你用哪个工具产出都在同一套标准内。省下来的沟通成本相当可观。3. Flutter工程规范具体怎么拆3.1 目录结构选用Feature-first为主、Layer为辅助Flutter工程的目录组织方式大体分两派按层组织lib/models/、lib/views/、lib/services/和按功能组织lib/features/auth/、lib/features/order/。我们团队最终选择主推Feature-first因为它更适配AI生成代码的模式。AI在实现一个功能时能自然地在一个模块目录内完成数据、页面、逻辑的闭环减少跨目录定位文件的频率。具体到每个feature内部再固定一层细分lib/features/order/ data/ # 仓库、数据源 domain/ # 实体、用例 presentation/ # 页面、状态、widget order_spec.md # 模块规范这条规则我写在全局规范里AI每次新建文件时都会参照这个结构。实测下来新建文件的落点准确率从原来的三成左右提升到八成以上。3.2 状态管理、路由、依赖注入的写法约束状态管理方面我们锁定了Riverpod原因在于它天然支持编译期安全并且对AI生成代码的友好度非常高。它的Provider声明方式直白依赖关系清晰AI不容易写出“伪代码”。规范里我明确写了页面级状态一律用StateNotifierProvider或FutureProvider禁止在build方法里直接发请求禁止在ConsumerWidget里实例化Controller。路由这块我们抛弃了在每个页面里直接Navigator.push(MaterialPageRoute(...))的写法统一走go_router的路由表。规范里会给AI举一个例子告诉它新增页面时必须先注册路由再使用。依赖注入没有上太重量的框架Riverpod本身就承担了这层职责。规范强调所有可测试的外部依赖API client、本地存储、时间函数必须通过Provider注入禁止在业务代码里直接import全局单例。这条规则极大提升了单元测试的可写性。3.3 import、命名、错误处理这些细节不能省命名规范是AI最容易翻车的地方尤其是文件命名。Flutter社区常用的下划线命名法order_detail_page.dart和Dart类名的大驼峰命名法OrderDetailPageAI有时会混着用。规范里我会给一个对照表格让它照着办比如“文件命名一律snake_case类名一律PascalCase常量一律kebab-case写法的枚举或static const”。import方面最烦的是相对路径和包路径混用AI因为见到过太多不同风格的代码经常会生成import ../../order/order_entity.dart然后又写import package:app/core/network/api_client.dart。统一方案是项目内部全部用package路径导入禁止相对路径。这样重构时移动文件不会引发大范围import报错。错误处理我专门加了一节所有网络请求必须捕获异常并映射成业务异常UI层不允许出现裸catch (e)打印错误一律用统一的logger封装禁止print。3.4 测试规范AI最容易偷懒的地方AI生成代码时能不写测试就不写测试这是所有AI助手的通病。所以测试规范必须写得像强制命令而不能只是“建议”。我在规范里写明新增或修改的每个领域模型必须配套单元测试每个页面必须至少有一个widget smoke test所有涉及异步数据的Provider必须测试loading和error两个分支。另外我要求AI在每次生成代码完成后主动列出“你没有覆盖到的测试场景”通过这种追问机制反向给它压力。虽然不能完全保证它每次照做但比完全不管好得多测试补齐率明显上升。4. 从零实操把规范真正砸进项目里4.1 第一步写全局规则文件AGENTS.md这一步是整个体系的地基内容不需要长但每一条都必须可执行。我给出的初始版本是这样的# AGENTS.md ## 项目技术栈 - Flutter 3.x / Dart 3.x - 状态管理Riverpodflutter_riverpod / hooks_riverpod - 路由go_router - 网络dio 统一ApiClient ## 目录规范 - 功能代码按feature组织禁止在lib根目录散落新文件 - feature内部固定分层data/domain/presentation - 新文件必须放入对应feature对应层级禁止随意创建新目录 ## 代码规范 - 文件命名snake_case.dart - 类名PascalCase - 项目内部import一律使用package路径 - 禁止在Widget build方法中执行网络请求 - 禁止在Model中存放API原始Map必须有toJson/fromJson - 所有外部依赖通过Riverpod Provider注入 ## 测试要求 - 每个domain实体必配单元测试 - 每个页面必配Widget测试 - 异步Provider必须覆盖loading/error分支 ## 红线 - 严禁修改 pubspec.yaml 中已有依赖版本 - 严禁生成文件后不注册路由 - 严禁在业务代码中直接使用print别小看只有几十行这套全局规范配上下面的analysis_options和CI检查已经能拦住大部分原则性错误。规范文件写好后一定要提交到git并让团队周知。4.2 第二步用analysis_options.yaml把规则变成强制检查光有文档还不够人都会选择性忽略文档AI也一样。所以我用Dart的静态检查规则把一部分规范固化到analysis_options.yaml里。这样即使AI写错了CI阶段也会直接报错而不是靠人工review去抓。include: package:flutter_lints/flutter.yaml linter: rules: always_declare_return_types: true avoid_print: true prefer_single_quotes: true sort_child_properties_last: true directives_ordering: true prefer_const_constructors: true avoid_relative_lib_imports: true analyzer: errors: avoid_print: warning sort_child_properties_last: warningavoid_relative_lib_imports这个规则特别重要它直接把“禁止相对路径import”从口头规范变成了强制检查项。avoid_print和directives_ordering则分别堵住了print满天飞和import乱序的问题。如果嫌内置规则不够细致还可以引入custom_lint写自己的lint比如检查Provider命名是否以Provider结尾、检查Model是否都实现了fromJson。这一步对老项目改造比较费劲但新项目从一开始就把规则挂上后面很轻松。4.3 第三步让Claude Code和Codex按规则干活这一步的核心是把规范文件与AI工具的加载机制对齐。Claude Code会自动读取项目根目录下的CLAUDE.md我在里面写一句简介然后指向AGENTS.md作为完整规范# CLAUDE.md 项目工程规范请严格遵循根目录 AGENTS.md。重点提醒 - 新增页面必须先注册 go_router 路由 - 禁止在 Widget build 中发起网络请求 - 状态管理统一使用 Riverpod不要使用 setState 做全局状态 - 涉及多文件改动时先查看对应 feature 目录下的 SPEC 文档Codex这边我们沿用AGENTS.md因为现在很多项目都通用这个文件。它读取规范的能力不如Claude Code那么“懂格式”所以我把AGENTS.md设计成短条目式、每条独立一句话而不是长篇大论的段落。另外在命令行里手动指定规则文件也是一个稳妥做法codex --project-rule-file AGENTS.md如果你用的是IDE插件版本就在项目设置里把AGENTS.md和CLAUDE.md同时设为项目指令。这样无论队友在IDE里用哪个工具都能加载同一套约定。4.4 第四步在CI里加一道“AI代码审查闸门”规范本地执行得再好也挡不住有人把AI生成的代码直接push。我在CI流水线里加了一个“代码规范检查”阶段跑三件事flutter analyze、dart format --set-exit-if-changed、关键目录结构校验脚本。flutter analyze --fatal-infos dart format --outputnone --set-exit-if-changed lib test同时用一个简单的shell脚本检查文件和目录约定比如检测lib根目录下是否出现未经约定直接新建的Dart文件for file in lib/*.dart; do if [ -f $file ]; then echo ERROR: 禁止在 lib 根目录直接创建文件$file exit 1 fi done这套检查不是要把AI的创造力锁死而是保证就算AI跑偏了也进不了主干。以前靠人工review提醒现在机器直接拦。团队里有人私下说这个闸门有点“暴力”但一个月后代码库的整洁度肉眼可见地提升没人再反对。5. 这轮实操踩过的坑和排查心得5.1 规范文件太大会被AI无视我第一次写的全局规范大概有150行产品背景、开发流程、发布节点全写进去了结果Claude Code确实读了但每次只能记住前面30行后面很多重要规则像没看见一样。后来我学到的做法是把“背景故事”全部删掉只留跟代码生成直接相关的指令。每一条规则都尽量控制在20字以内用祈使句。如果规则确实多就按主题拆成多个小文件比如AGENTS.md只写高频约束CONVENTIONS_DETAIL.md放低频细节AI在需要的时候再让它去查。少即是多这句话在给AI写规范时格外适用。5.2 规则之间互相矛盾AI选择困难有一版规范里既写了“所有Repository必须实现接口”又在另一个文件里说“简化设计不要过度抽象”结果AI生成代码时开始自行取舍有时生成接口包装有时直接裸用实现类两套风格并存。问题出在规则之间没有优先级。排查后我加了一条总原则“当本文件规则与其他文件冲突时以AGENTS.md为准AGENTS.md内部冲突时以靠后的条款为准。”并刻意删掉了一些弹性表达把“不要过度抽象”改成“禁止创建单实现接口除非你有两个以上实现类”。规则一旦有歧义AI就会按它自己的偏好理解所以规范化语言必须像法律条文一样不留余地。5.3 AI不遵守测试规范怎么办这个问题纠缠了我好久。明明AGENTS.md里写了“必须补测试”Codex生成的代码还是常常不带测试文件。后来我换了一种问法不直接让它“写测试”而是给它演示一个任务分解模板任务新增订单列表页 1. 先写 order_entity.dart并配套 order_entity_test.dart 2. 再写 order_list_provider.dart并配套 provider 测试loading/error/success 3. 最后写 order_list_page.dart并配套 widget test 输出前自查是否每个文件都有对应测试把测试步骤前置到任务拆解里比在规范末尾写一句“记得测试”有效得多。因为AI是按任务一步步执行的它在第一步就看到了测试文件要求后面自然会把测试当“任务的一部分”。另外我也写了一个lint脚本检查lib/features/xxx/domain/下新增的.dart文件在test/目录里是否存在对应的_test.dart不存在就直接CI失败。这条之后测试缺失率大幅下降。5.4 规范应该跟着项目演进而不是一成不变规范文件最忌讳写完就再也不动。项目从单一模块扩展到十几个feature之后原本适合的规范可能就不合适了。比如早期我们禁止使用BuildContext跨异步操作后来为了配合某个特定场景又不得不允许在受控条件下使用。如果不更新规范AI就会持续生成与当前架构冲突的代码。我们现在的做法是每次代码评审中如果发现某条规则被违反三次以上就停下来开会讨论看是规则本身不合理还是执行机制有问题。规则本身的问题就改规则执行机制的问题就加lint或CI约束。规范文件也要版本化管理每次修改都写入commit message让整个团队知道AI的行为基线在随着项目一起进化。最后分享一点实操体会整套方案跑通之后最明显的变化不是AI生成的代码质量瞬间拉满而是“稳定性”上来了。以前它今天生成90分的代码、明天可能生成50分的代码全看对话状态和上下文运气。现在规范固定、工具固定、CI检查固定它的产出基本稳定在75到80分再由人补上最后的架构判断和业务细节整体效率是真的高。如果你也想这么搭我建议不要一上来就把规范做得特别大先写一份二十行的AGENTS.md配一个强制flutter analyze的CI跑两周看看AI还犯哪些错再针对性地补充规则。规范工程是一个持续迭代的过程不是一次性交付物。最后再提醒一句所有规范文件都放进git仓库跟代码一起走否则AI换一台机器就“失忆”了而工程规范恰恰是最不该失忆的东西。

Flutter项目AI工程规范实战：驯服Claude Code与Codex

相关推荐

投机解码实战：把本地大模型推理速度从 14 tok/s 提到 159 tok/s

C++网络编程入门：从socket到实现基础TCP服务端客户端

2026年工业智能体落地实录：从车间排产到设备维护的实战指南

更多资讯

Agent Client Protocol：智能体客户端通信协议设计与实践

MySQL学生成绩管理系统数据库设计：需求分析、建表、视图与存储过程完整方案

Unity运行时导入3D模型：基于TriLib源码的模型加载与替换实践

数据库关系代数与SQL实战入门：从课本习题到可执行查询

Unity3D数字孪生案例：从模型导入到数据驱动的完整落地路径

VSCode中Claude Code插件报API Error 400：message[1] has invalid role: system——把settings改到TaoToken的排查路径

今日更新

NetSpot 实战：用信道分析与频宽优化解决 Wi-Fi 卡顿

C++ split() 字符串分割的五种实现与性能实测

R语言坐标轴范围设置：从xlim/ylim到coord_cartesian的完整指南

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？