夜雨聆风本文作者
作者：小仙女喂得猪
链接：
https://juejin.cn/post/7637134822705463334
本文由作者投稿发布。
我们团队在一个大型 Android 组件化应用中落地 AI 辅助开发已经不少时间，踩过不少坑，也攒下了一套可复用的规则体系。这篇文章把我们的设计思路和实战经验整理出来，供同样在推 AI Coding 的 Android 团队参考。
1. 为什么需要规则体系
刚把 AI 助手引入项目时，我们遇到三类问题：
上下文遗忘。 项目有 20+ 模块，复杂的依赖方向（libapi → libcore → 业务模块），特定的继承体系（新增 Activity 必须继承 ChannelPlayActivity），这些约束 AI 并不天然知道。每次对话都要重新交代一遍，交代漏了就出问题。
幻觉编造。 AI 会"发明"项目中不存在的类名、方法名、资源名。比如随口编一个 ImageUtils.load() ，实际上项目用的是 ImageLoader.with() 。等你发现时，已经 review 完好几段代码了。
多规则混乱。 项目同时有通用编码规范、TV 焦点规则、埋点规范、性能规范，每次都全量加载，上下文窗口很快撑爆不说，AI 还容易把不同规则的约束搅在一起。
⚡ 核心认知
**AI 的能力取决于你喂给它的上下文质量，但上下文窗口是一个稀缺资源。** 规则体系要解决的就是"在正确的时刻，把正确的约束，以正确的粒度喂给 AI"。
2. 工具链：Qoder IDE Plugin + Qoder CLI
我们的规则体系运行在 Qoder 工具链上：
post-commit 时自动记录 AI 参与的提交，用于后续的效果度量和知识沉淀。工具链的定位是"规则的执行引擎"——它不生产规则，只负责按调度策略加载规则、按触发条件激活技能。真正有含金量的工作，是规则本身的设计。
3. 新人入手：AGENTS.md 作为第一入口
一个新成员加入项目，或者 AI 第一次被接入项目时，面对 20+ 模块、十几份 reference 文档、多个规则和技能，最大的困惑是"我应该从哪看起"。
我们的做法是用一个 AGENTS.md 作为统一入口。这份文件放在项目根目录，包含：
AGENTS.md 不写具体规则内容，只做两件事： 告诉 AI 这个项目长什么样 ，以及 告诉 AI 什么情况下应该去读哪份规则 。它是整个规则体系的"调度器"。
有了 AGENTS.md，AI 在每次对话开始时就有了关于项目的最基本信息，也知道在遇到具体开发任务时该去哪找详细规则。新成员也可以通过读这一份文件快速建立对项目规范体系的全景认知。
4. 架构设计：三层体系
我们把规则拆成三个层次，每一层解决不同的问题：
调度层（AGENTS.md） ├── 约束层（rules/） │ ├── car_project_rule.md # 项目开发主规则 │ └── tv_focus_rule.md # TV 焦点专项规则 ├── 参考层（references/ + skills/） │ ├── references/ # 模块文档 · 依赖关系 · 约定 · Crash模式 │ └── skills/ # 埋点技能 · 性能优化技能等技能4.1 调度层：AGENTS.md
AGENTS.md 扮演的是"路由"角色。它不包含具体的开发约束，而是定义了一组 触发条件 和 跳过条件 。
每一条规则或技能在 AGENTS.md 中都有一个对应的节，写明：
这种设计的好处是： 按需加载 。AI 不会一次性塞进几万字的规则文档，而是根据当前任务动态决定读什么。既节省了上下文窗口，又保证了相关约束不丢失。
4.2 约束层：rules/
约束层是整个体系的核心，定义了"什么能做、什么不能做"。
car_project_rule.md（项目开发主规则） 覆盖了 13 个维度的约束：
tv_focus_rule.md（TV 焦点专项规则） 则是针对 Android TV 遥控器焦点系统的专项约束，覆盖了焦点三层架构、编译期插件替换机制、DialogFragment 焦点处理、按键事件分发、无障碍适配等复杂场景。这类专项规则的特点是： 领域知识非常深，但只有少数场景需要 ——完美匹配按需加载的策略。
4.3 参考层：references/ + skills/
references/ 是"事实层"——记录项目真实存在的类名、方法名、路径、依赖关系。每个模块一份文档，以模块的实际目录结构为骨架展开。此外还有：
dependencies.md ：模块依赖图与第三方库版本conventions.md ：代码生成步骤（新增接口/页面/服务/渠道的标准流程）与反模式示例crash_patterns.md ：历史 Crash/ANR 模式的特征识别、根因分析、修复方案skills/ 是"流程层"——为特定领域的复杂任务提供分步骤的操作指导。例如 amber_skill 覆盖了从初始化、页面埋点、播放器控件埋点、广告埋点、搜索埋点、支付埋点到登录全链路的详细约束和调用模板；performance_skill 则提供了内存泄漏、启动速度、ANR、网络、渲染、车机特有性能的关注点和检测流程。
每一份 skill 文档都具备独立交付能力——AI 加载后不需要再追问，直接可以执行。
5. 否定词保护：5 种否定模式的触发过滤
这是我们在实践中踩坑最多、迭代次数也最多的一个设计。
一开始我们只做简单的关键词匹配——用户消息中出现了"焦点"就加载焦点规则，出现了"埋点"就加载埋点技能。很快发现问题： 关键词匹配的准确率远低于预期 。
比如用户说"这个页面的生命周期类似 page_start，但跟埋点无关"，机械匹配会因为"page_start"而触发 amber_skill，但用户显然不想讨论埋点。
我们总结出 5 种需要过滤的否定场景：
| 已关闭/已完成 | ||
| 类比/对比 | ||
| 通用概念讨论 | ||
| 明确排除 | ||
| 间接引用 |
实现方式上，我们要求 AI 进行 语义二次判断 ：关键词匹配只是初筛，必须结合用户意图做二次判断。判断原则是三句话——"关键词出现在否定语境、类比语境、已关闭语境中时，不触发"。
这个设计让误触发率显著下降。更重要的是，它让用户感受到 AI 在"理解"他们而不是机械响应。
6. References 体系："先查后写"如何抑制幻觉
AI 编造不存在的类名/方法名是我们遇到的最常见问题之一。根本上，这是因为 AI 的训练数据中没有我们的项目代码。
我们的应对策略是建立一个完整的 references 体系，并强制要求 AI 先查后写 。
每模块一份文档
项目的每个模块在 .qoder/references/ 下都有一份对应的 markdown 文档。文档内容包括：
以核心基础库模块为例，它的 reference 文档会列出 application/ 、 arouter/ 、 data/ 、 amber/ 、 widget/ 、 utils/ 等所有子目录，以及每个目录下的关键类名和职责。
三层约束保证"不编造"
在 car_project_rule.md 的行为准则章节，我们写了三条硬约束：
这三条约束配合完整的 references 文档，把 AI 从"凭记忆猜测"变成了"按文档查询"。幻觉率明显下降。
conventions.md 的反模式教学
除了正向文档，我们还有一份 conventions.md ，用"错误示例 vs 正确示例"的对照方式，展示常见的违规写法。比如：
Gson().fromJson() → ✅ GsonUtil.jsonToBean() + try-catch这种"反面教材"式的呈现，对 AI 的效果比纯正向陈述更好——AI 更容易记住"不要这样做"的明确边界。
7. 自查清单：AI 生成代码后的质量自检闭环
规则写得再多，AI 也不一定每次都遵守。我们的经验是： 规则定义"应该怎么做"，自查清单保证"确实做到了" 。
car_project_rule.md 的末尾有一份 23 项自查清单，每项都是一个可验证的检查点：
配合 TV 焦点规则，还有额外的 12 项专项检查（T1~T12）；配合性能技能，有 17 项性能检查（P1~P17）。
自查清单的设计有几个原则：
Gson() 检查是否有违规使用）在实践中，自查清单还有一个额外的好处：它可以作为团队 Code Review 的辅助 checklist，人机共用。
8. Git Hook 集成：提交追踪的知识沉淀
我们在 .git/hooks/post-commit 中集成了 Qoder CLI：
#!/bin/sh# BEGIN Qoder AI tracker"qodercli" commit --hook 2>/dev/null || true# END Qoder AI tracker每次 git commit 后，这个 hook 会调用 Qoder CLI 记录本次提交的信息。这样做的目的有三：
这个设计目前还比较轻量，但方向是对的——规则体系本身也需要迭代，而迭代需要数据。
9. 待优化点
坦诚地说，当前的规则体系还有很多可以改进的地方：
References 自动生成。 目前每份模块文档都是手动维护的。理想情况下，应该有一个脚本扫描模块的目录结构和 build.gradle ，自动生成基础骨架，人工只补充核心类的详解。否则随着模块增加，维护成本会线性增长。
规则冲突检测。 当 car_project_rule 和 tv_focus_rule 对同一件事有不同约束时（比如 Handler 的使用方式），目前靠 AI 自行判断优先级。一旦规则多了，冲突不可避免，需要一套显式的优先级或合并机制。
自动化测试。 很多自查清单里的检查项其实是可以通过静态分析工具自动检查的。比如"是否使用了 Gson() 而非 GsonUtil"、"是否硬编码了 dp/sp 值"。把这些检查做成 lint 规则或自定义脚本，可以在 AI 生成代码后立即给出反馈，不依赖 AI 的"自觉"。
规则版本管理。 规则文件在 git 中随项目代码一起版本管理，但当多个团队成员同时调整规则时，还没有合并冲突的解决规范。规则变更的影响面评估（改了这条规则会影响哪些模块的 AI 生成质量）也缺乏工具支撑。
效果度量体系。 目前只有 Git Hook 在做基础的提交追踪，还缺少系统性的效果度量——比如 AI 生成代码的一次通过率、修改轮次分布、不同规则加载方案的效果对比等。
这些点的优先级取决于团队规模和 AI 使用深度。小团队可以先忽略，几十人的团队可能需要认真考虑。
10. 总结
回顾最近的实践，我们认为一个核心认知是： AI 辅助开发的效果，上限不是模型的能力，而是你给它的上下文设计。
模型本身的推理能力和代码生成能力已经够强了。真正拉开差距的，是你能不能把项目的隐性知识（架构约束、命名约定、反模式、历史踩坑）结构化地组织起来，让 AI 在正确的时刻、以正确的方式获取到正确的信息。
我们的三层体系（调度层 → 约束层 → 参考层）+ 否定词保护 + References 反幻觉 + 自查清单闭环，是这个思路的一个具体实践。它不是银弹，但确实让 AI 在复杂 Android 项目中的可用性提升了一个台阶。
如果你也在做类似的事情，希望这些经验能帮到你。如果你们有更好的做法，也欢迎交流。
本文基于一个真实 Android 车载项目的 AI 辅助开发实践撰写，涉及的具体包名基于代码安全性问题已做泛化处理。
每周分享3篇技术文 欢迎关注
如果你想要跟大家分享你的文章，欢迎投稿
（发送文章到623565791@qq.com即可）~
┏(＾0＾)┛明天见！
