Flutter 项目 AI 友好工程规范：Claude Code 与 Codex 协作实践-开发者社区

1. 为什么 Flutter 项目需要一套“AI 友好”的工程规范

Flutter 项目有个很典型的特点：上手快，但规模一大就容易散。一个页面文件动辄上千行，状态管理各写各的，命名风格五花八门，build方法里塞满业务逻辑。这种项目如果交给 AI 去改，结果往往是灾难性的——它不知道你的分层约定，不知道哪些目录是自动生成的，不知道你团队对setState和状态管理库的取舍，于是它“很努力”地写出一堆能跑但完全不符合你项目风格的代码。

我最近在几个 Flutter 项目里做了一件挺有意思的事：把 Claude Code 和 Codex 这类 AI 编码工具当成团队里的“新同事”来对待，给它们准备一套和人类新人一样的工程规范文档。结果非常明显——AI 生成的代码从“能跑就行”变成了“基本可以直接合并”，返工率下降了一大截。

这套东西的核心不是某个神奇插件，而是三样东西的组合：

一份 AI 能读懂的工程规范文档（放在仓库里，AI 每次改代码前先读）
一套可执行的静态检查与格式化配置（让 AI 的产出自动被约束）
一套给 AI 的“任务提示模板”（明确告诉它边界在哪、该参考哪些文件）

说白了，就是把团队里口口相传的隐性规则，变成 AI 能消费的显性文本。这件事对 Flutter 项目尤其值得做，因为 Flutter 的目录结构、状态管理、Widget 拆分方式差异极大，没有统一约定的话，AI 每次生成都是“重新发明轮子”。

这篇文章我会把整套方案拆开讲：规范文档怎么写、静态检查怎么配、提示模板怎么设计、AI 改代码时怎么防止它乱动生成文件、遇到冲突怎么排查。适合正在用或准备用 AI 辅助开发 Flutter 项目的同学，也适合想把团队规范沉淀下来的技术负责人。

2. 整体设计思路：让 AI 在“轨道”里干活

2.1 核心矛盾：AI 很强，但它不知道你的“家规”

AI 编码工具的能力毋庸置疑，给它一个函数它能补全，给它一个报错它能定位。但它有个致命短板：它默认按“通用最佳实践”写代码，而不是按“你的项目实践”写代码。

举个我踩过的坑。我们项目里状态管理统一用某个状态管理方案，结果 AI 在某次改动里直接引入了setState来管理跨页面状态。代码能跑，测试也过，但 review 的时候被同事一眼看穿——这违反了项目的分层约定。问题不在 AI，在于我们从来没告诉过它这条规则。

所以整套方案的第一性原理是：AI 不会读心，你得把规则写下来，并且确保它每次都能读到。

2.2 三层约束模型：文档、工具、提示

我把这套方案设计成三层，从“软约束”到“硬约束”逐层收紧：

层级	形式	作用	约束力
第一层	工程规范文档	告诉 AI 项目结构、命名、分层约定	软约束，靠 AI 理解
第二层	静态检查 + 格式化	自动拦截违规代码	硬约束，机器执行
第三层	任务提示模板	明确单次任务的边界和参考文件	过程约束，减少跑偏

这三层的关系是：文档负责“讲道理”，工具负责“兜底”，提示模板负责“聚焦”。只有文档没有工具，AI 可能理解偏差；只有工具没有文档，AI 会反复试错浪费 token；只有提示没有前两者，AI 每次都要重新学习项目。

2.3 为什么选 Claude Code + Codex 组合

有同学会问，为什么不是单一工具？我的实际体验是，这两个工具在 Flutter 场景下各有擅长：

Claude Code更擅长理解大段上下文、跨文件重构、读懂规范文档后做符合约定的改动。它的强项是“读懂你的意图和项目背景”。
Codex 类工具更擅长在明确的函数级、文件级任务上快速产出，尤其是补全、单测生成、局部重构。

组合用法是：用 Claude Code 做“理解规范 + 跨文件改动”，用 Codex 做“局部实现 + 快速补全”。两者共享同一套规范文档和静态检查配置，保证产出风格一致。

注意：这里说的组合不是让两个工具互相调用，而是让它们消费同一套工程约束。工具会换，规范文档和检查配置是长期资产。

2.4 目录结构设计：给 AI 划清“可动区”和“禁区”

Flutter 项目里有些目录是绝对不能手改的，比如自动生成的代码、构建产物、平台通道生成文件。AI 不知道这些，很容易“好心办坏事”。所以我在规范文档里明确划了三类区域：

可自由修改区：lib/features/、lib/core/下的业务代码
谨慎修改区：lib/core/下的基础设施、路由、依赖注入配置
禁止修改区：*.g.dart、*.freezed.dart、build/、平台目录下的生成文件

这个划分写进文档后，AI 改代码时会主动避开禁区，我实测下来误改生成文件的概率几乎降到零。

3. 工程规范文档怎么写才“AI 友好”

3.1 文档结构：从“给人看”改成“给 AI 看”

传统工程规范文档是写给人看的，讲究排版美观、语气委婉。但给 AI 看的文档要反过来：结构清晰、规则明确、每条规则都能被验证。

我用的结构是这样的：

# 项目工程规范（AI 协作版） ## 1. 项目概览 - 技术栈：Flutter 3.x + Dart 3.x - 状态管理：xxx - 路由：xxx - 网络：xxx ## 2. 目录结构约定 （每个目录的职责说明） ## 3. 命名规范 （文件、类、变量、常量的命名规则） ## 4. 分层与依赖规则 （哪些层可以依赖哪些层） ## 5. 禁止事项 （明确列出不能做的事） ## 6. 代码示例 （正确示例 + 错误示例对照）

关键点是第 5 节“禁止事项”和第 6 节“代码示例”。AI 对“不要做什么”和“正反例对照”特别敏感，写清楚了它基本不会犯。

3.2 命名规范：把“约定”变成“可判定规则”

命名是最容易出问题的地方。人类新人会问，AI 不会问，它直接按自己的习惯来。所以命名规范必须写成可判定的规则，而不是模糊描述。

我文档里是这样写的：

文件名：小写下划线，如user_profile_page.dart
页面 Widget 类名：大驼峰 +Page后缀，如UserProfilePage
业务组件：大驼峰 +Widget后缀，如UserAvatarWidget
状态类：大驼峰 +State后缀
常量：小驼峰，放在xxx_constants.dart中
私有成员：下划线开头

对比一下模糊描述和可判定规则：

模糊描述	可判定规则
命名要清晰	页面类必须以 Page 结尾
常量统一管理	常量必须放在 constants 文件
避免魔法数字	数字必须定义为命名常量

AI 对可判定规则的遵守率远高于模糊描述。这是我在多个项目里反复验证过的。

3.3 分层规则：明确“谁能依赖谁”

Flutter 项目最容易乱的就是分层。我用的分层是：

presentation 层：页面、Widget、状态管理，只能依赖 domain 层
domain 层：业务逻辑、实体、用例，不依赖任何外层
data 层：数据源、仓库实现、DTO，依赖 domain 层
core 层：工具、常量、扩展，被所有层依赖

文档里要明确写出依赖方向，并且给出反例。比如：

禁止：presentation 层直接调用 data 层的仓库实现正确：presentation 层通过 domain 层的用例间接访问数据

这条规则写清楚后，AI 生成代码时会自动走正确的调用链，不会再出现“页面里直接 new 一个网络请求”的情况。

3.4 代码示例：正反例对照是最高效的约束

我发现给 AI 看一个错误示例，比给它看十条规则都管用。所以文档里每个关键规则我都配了正反例。

比如状态管理的规则：

// 错误示例：在页面里直接 setState 管理跨页面状态 class UserPage extends StatefulWidget { // ... void _loadUser() async { final user = await api.fetchUser(); setState(() => _user = user); // 跨页面状态不该用 setState } } // 正确示例：通过状态管理方案统一管理 class UserPage extends ConsumerWidget { @override Widget build(BuildContext context, WidgetRef ref) { final userState = ref.watch(userProvider); // ... } }

这种对照写进文档后，AI 在类似场景下会主动选择正确写法。我统计过，加了正反例之后，状态管理相关的返工减少了大概七成。

3.5 把文档放进仓库，让 AI 每次都能读到

文档写好了，怎么让 AI 读到？我的做法是：

在仓库根目录放ENGINEERING_GUIDE.md
在CLAUDE.md或类似的 AI 配置文件里引用它
在每次任务提示里明确要求“先读工程规范”

这样无论用哪个 AI 工具，只要它支持读取仓库文件，就能消费这套规范。文档是资产，工具是消耗品，这个思路很重要。

4. 静态检查与格式化：给 AI 产出上“硬约束”

4.1 为什么光有文档不够

文档是软约束，AI 可能理解偏差，也可能在长上下文里“忘记”。所以必须有机器执行的硬约束兜底。Flutter 生态里这套东西很成熟：analysis_options.yaml配 lint 规则，dart format管格式，再加一层自定义检查。

我的经验是：文档负责让 AI 写对，静态检查负责让 AI 写错时立刻被发现。两者缺一不可。

4.2 analysis_options.yaml 的关键配置

大部分 Flutter 项目默认的 lint 规则太宽松，AI 生成的代码很容易绕过。我一般会开启更严格的规则集，重点包括：

include: package:flutter_lints/flutter.yaml linter: rules: # 强制类型 always_specify_types: true # 禁止 print avoid_print: true # 强制 const prefer_const_constructors: true prefer_const_declarations: true # 禁止隐式 dynamic avoid_dynamic_calls: true # 强制 public API 文档 public_member_api_docs: true # 禁止空 catch empty_catches: true # 强制 await 处理 unawaited_futures: true

这里有个坑要提醒：always_specify_types和public_member_api_docs这两个规则比较严格，老项目直接开会导致大量报错。建议新项目直接开，老项目分批开，先开最影响 AI 产出的几条（比如avoid_print、prefer_const_constructors），再逐步加严。

4.3 自定义 lint：拦截项目特有的违规

内置规则覆盖不了项目特有的约定，这时候可以用自定义 lint。比如我们项目禁止在 presentation 层直接 import data 层，就可以写一条自定义规则。

自定义 lint 的写法稍微复杂，需要单独建一个 lint 包。如果团队规模不大，也可以用脚本检查替代：写一个 Dart 脚本扫描 import 语句，发现违规就报错，挂到 CI 上。

我实际用的是脚本方案，因为维护成本低。脚本逻辑很简单：

// 伪代码：扫描 presentation 层的 import void checkLayerImports() { final files = Directory('lib/presentation').listSync(recursive: true); for (final file in files) { final content = File(file.path).readAsStringSync(); if (content.contains("import 'package:app/data/")) { throw Exception('presentation 层禁止直接依赖 data 层: ${file.path}'); } } }

这条脚本挂到 CI 后，AI 生成的越界代码会在提交前被拦下。

4.4 格式化：统一风格，减少无意义 diff

dart format是标配，但有个细节要注意：行宽设置。默认 80 字符，很多团队改成 100 或 120。这个值要写进文档，并且和 AI 提示里保持一致，否则 AI 按 80 写、格式化按 120 跑，diff 会很难看。

我的做法是在analysis_options.yaml旁边放一个.dart_format配置（或直接在 CI 脚本里指定行宽），并在工程规范文档里写明：

代码行宽统一为 100 字符，提交前必须执行 dart format。

4.5 把检查挂到 AI 工作流里

静态检查配好了，还要让 AI 在改完代码后自动跑一遍。我的做法是在任务提示模板里加一条：

完成改动后，执行dart analyze和dart format，确保无报错、无格式问题。

Claude Code 这类工具支持执行命令，它会自动跑检查并根据报错修正。这一步能拦下大量低级问题，实测能减少一半以上的 review 返工。

5. 任务提示模板：让 AI 每次任务都“聚焦”

5.1 提示模板的核心要素

AI 跑偏往往是因为提示太模糊。一个好的任务提示模板应该包含：

任务目标：一句话说清要做什么
参考文件：明确让它先读哪些文件
约束条件：本次任务要遵守哪些规范
验收标准：怎么算完成
禁止事项：本次任务不能碰什么

我用的模板长这样：

## 任务 [一句话描述] ## 必读文件 - ENGINEERING_GUIDE.md - [相关业务文件] ## 约束 - 遵守工程规范文档中的所有规则 - 状态管理使用 xxx 方案 - 不修改任何 *.g.dart 文件 ## 验收标准 - dart analyze 无报错 - 新增代码有对应测试 - 不引入新的依赖 ## 禁止 - 不修改 build/ 目录 - 不修改平台目录

5.2 参考文件怎么选：少而精

参考文件不是越多越好。给太多文件，AI 的上下文会被稀释，反而抓不住重点。我的经验是每次任务给 3 到 5 个最相关的文件：

工程规范文档（必给）
要修改的文件本身
同目录下的一个“标杆文件”（写得最规范的）
相关的测试文件

“标杆文件”这个技巧特别有用。AI 会模仿参考文件的风格，给它一个写得好的同类文件，它产出的代码风格会自然对齐。

5.3 约束条件：把“隐性知识”显性化

约束条件是把团队隐性知识显性化的地方。比如：

“新增的网络请求必须走统一的请求封装，不要直接调 http 库”
“错误处理统一用 Result 类型，不要抛异常”
“所有用户可见文案必须走国际化，不要硬编码中文”

这些规则平时靠 code review 口头传递，写进提示模板后，AI 一次就能遵守。

5.4 验收标准：让 AI 自己检查

验收标准要写成 AI 能自己验证的形式。比如“dart analyze 无报错”是 AI 能跑的，“代码质量高”是 AI 没法验证的。把验收标准写成可执行的形式，AI 会在完成前自己跑一遍，减少人工检查成本。

5.5 禁止事项：防止 AI“顺手”改坏东西

禁止事项是最后一道防线。我一般会明确列出：

不修改生成文件
不修改平台目录
不升级依赖版本
不删除现有测试

这几条写清楚后，AI 的改动范围会被严格限制在业务代码内，安全性大幅提升。

6. 实操过程：从零搭一套完整流程

6.1 第一步：梳理现有项目约定

先别急着写文档，先梳理项目现有的约定。我的做法是：

打开项目，列出所有目录及其职责
找出写得最规范的几个文件作为“标杆”
记录团队在 review 里反复强调的规则
记录 AI 之前犯过的典型错误

这一步大概花半天到一天，产出一份“约定清单”。这份清单就是工程规范文档的素材。

6.2 第二步：写工程规范文档

按第 3 节的结构写文档。重点是把规则写成可判定的形式，配上正反例。文档不用一次写完美，先覆盖最核心的几条（命名、分层、状态管理、禁止事项），后续遇到新问题再补充。

我第一版文档大概 2000 字，覆盖了 80% 的常见场景。后续每次 AI 犯错，就把对应规则补进去，文档会越来越完善。

6.3 第三步：配置静态检查

在analysis_options.yaml里开启严格规则，先跑一遍dart analyze看有多少报错。老项目报错多的话，分批开启规则，每批修完再开下一批。

同时写好自定义检查脚本，挂到 CI 上。脚本不用复杂，能拦截最关键的几条越界规则就行。

6.4 第四步：设计提示模板

把第 5 节的模板存成文件，比如AI_TASK_TEMPLATE.md。每次给 AI 派任务时，复制模板填内容。用久了可以针对不同任务类型做几个变体：新功能开发、bug 修复、重构、测试补充。

6.5 第五步：跑通一个完整任务

选一个中等复杂度的任务试跑，比如“给用户列表页加一个下拉刷新”。完整走一遍流程：

填提示模板
让 AI 读规范文档和相关文件
AI 产出代码
跑dart analyze和dart format
跑测试
review 产出

第一次跑大概率会有问题，把问题记录下来，回头补进规范文档或提示模板。跑通三五个任务后，整套流程就顺了。

6.6 第六步：持续迭代

这套东西不是一次性的，要持续迭代。我的做法是：

每次 AI 犯错，问自己“是文档没写清楚，还是检查没覆盖到”
把答案补进对应的地方
每月回顾一次文档，删掉过时规则，补充新规则

迭代两三个月后，AI 的产出质量会稳定在一个很高的水平。

7. 常见问题与排查技巧实录

7.1 AI 不遵守规范文档怎么办

这是最常见的问题。排查思路：

文档是否被读到：确认 AI 工具确实读取了规范文档，有些工具需要显式指定
规则是否可判定：模糊描述 AI 遵守率低，改成可判定规则
是否有正反例：加正反例对照，遵守率会明显提升
是否在提示里重申：长任务里 AI 可能“忘记”，在提示模板里重申关键规则

我遇到过一次，AI 反复在 presentation 层直接调 data 层。后来发现是文档里这条规则写得太靠后，AI 没注意到。把它提到文档开头，问题就解决了。

7.2 AI 改动了生成文件怎么办

生成文件被误改是高频问题。排查和解决：

在规范文档的“禁止事项”里明确列出所有生成文件模式
在提示模板的“禁止”里重申
在 CI 里加检查，发现生成文件被改就报错
用.gitignore或工具配置把生成文件标记为只读

我现在的做法是在 CI 里加一条检查：如果*.g.dart文件的 diff 不是由代码生成命令产生的，就报错。这条检查拦下过好几次误改。

7.3 AI 生成的代码风格不一致

风格不一致通常是参考文件没给对。解决：

每次任务给一个“标杆文件”作为风格参考
确保dart format配置一致
在提示里明确行宽、命名等关键风格参数

7.4 静态检查报错太多，AI 改不过来

老项目开严格 lint 后报错多，AI 一次改不完。解决：

分批开启规则，每批控制在 AI 一次能改完的量
优先开影响 AI 产出的规则
对暂时不想改的规则用// ignore注释，但要记录待办

7.5 常见问题速查表

问题	可能原因	解决方向
AI 不遵守规范	文档没读到/规则模糊	确认读取、改可判定规则、加正反例
误改生成文件	禁止事项没写清	文档+提示+CI 三重拦截
风格不一致	参考文件没给对	给标杆文件、统一格式化配置
检查报错太多	规则一次开太猛	分批开启、优先关键规则
AI 改动范围过大	禁止事项缺失	明确列出不能碰的目录和文件
状态管理用错	规则没写清	文档加正反例、提示里重申

7.6 几个独家避坑技巧

最后分享几个我踩坑总结的技巧：

文档开头放“三条铁律”：把最重要的三条规则放最前面，AI 对开头内容记得最牢
提示模板里加“先复述任务”：让 AI 先复述一遍任务目标再动手，能减少理解偏差
用“标杆文件”代替长篇描述：一个写得好的同类文件，比十段描述都管用
每次任务只做一件事：任务越聚焦，AI 产出质量越高，别让它一次改五个文件
把 AI 犯错记录成“错题本”：定期回顾，把高频错误补进文档

这套方案我在几个 Flutter 项目里跑下来，AI 生成代码的可用率从大概五成提升到八成以上，review 时间明显缩短。核心不是工具多强，而是把项目规范变成了 AI 能消费的资产。工具会换，这套文档和配置是长期沉淀，值得投入。