🚀 团队 AI 辅助开发规范与工作流指南 (AI Rules Architecture)

随着 AI 辅助编程（如 Android Studio Gemini, Cursor, GitHub Copilot）的普及，我们经常会遇到一个痛点：AI 总是输出通用的、过时的，甚至完全不符合我们项目当前架构风格的代码。 每次都要反复告诉 AI “请用 Compose”、“请用我们的 BaseScreen”，效率极其低下。

为了解决这个问题，我们引入了 Prompt Engineering as Code (提示词工程代码化) 的理念，在项目中建立了 AGENTS.md + .ai_rules/ 的 AI 规则架构。

---

⚖️ 这种架构的优劣势分析

✅ 优势 (Pros)

1. 代码风格高度统一（零沟通成本）：AI 清楚地知道项目里有哪些现成的轮子（如 V3StyleButton、BaseScreenActivity），生成的代码达到 Copy-Paste（复制即用） 的级别。

2. “活”的团队开发文档：传统的开发文档写在 Wiki 里没人看，而 .ai_rules 里的规范会在你每次使用 AI 生成代码时强制生效。它既是给 AI 看的，也是给新员工看的最佳上手指南。

3. 能力模块化（Skills 路由）：避免了把所有规则写在一个大文件里导致 AI 上下文混乱。AI 会根据你的需求，自动去 .ai_rules 寻找对应的 Skill，做到“专人办专事”。

⚠️ 劣势 (Cons)

1. 一定的维护成本：当项目引入了新的架构或放弃了旧的技术栈时，除了重构代码，还需要同步更新 .ai_rules 中的描述，否则 AI 会继续写出旧代码。

2. AI 的“幻觉”：遇到极度复杂的业务逻辑时，AI 偶尔还是会忽略某些规则，需要开发者具备 Code Review 的意识，不能完全盲目复制。

---

📂 架构目录与文件职责说明

我们的 AI 规范主要存放在根目录的 AGENTS.md 和 .ai_rules/ 文件夹下。

1. AGENTS.md (主控路由 Agent)

• 职责：它是 AI 的“大脑”和“调度中心”。它不包含具体的代码细节，只负责监听用户的意图，并为其分配最合适的底层 Skill 文件。

• 内容：包含了全局的工作流要求（如代码需要拆分、不能超过 500 行），以及所有 Skill 文件的目录索引。

2. .ai_rules/ (技能库目录)

这里存放着各个垂直领域的具体开发规范，AI 会根据 AGENTS.md 的指引读取具体文件：

技能文件 (Skill)	负责领域 & 核心职责
🎨 ui_compose_expert.md	UI/Compose 专家。约束 Compose First、Material 3、通用颜色/按钮/头像组件的强制使用，以及统一多语言字符串。
🏛️ architecture_base.md	架构与基类专家。约束新建页面的继承（BaseScreenActivity/Fragment）、ViewModel 的通信机制（StateFlow 与 UiEvent 隔离）。
🛡️ permission_handler.md	隐私合规专家。处理 Android 13/14 细粒度权限，强制要求 Rationale 弹窗、按需申请及优雅降级逻辑。
💾 database_room_generator.md	本地存储专家。规范 Room 的 Entity 编写、Dao 的 Flow 响应式返回，以及强制要求 Migration 升级脚本。
📦 gradle_build_optimizer.md	构建与依赖专家。规范项目中第三方库的引入（强制走 libs.versions.toml），冲突解决与 KSP 迁移。
🔍 code_reviewer.md	代码审查专家。负责性能诊断、排查内存泄漏（结合 LeakCanary）、重组性能优化。
📝 git_commit_generator.md	Git 规范专家。用于自动生成符合 Conventional Commits（约定式提交）标准的 Commit Message。

---

👨‍💻 团队成员如何使用？

在使用 Android Studio Gemini 或其他内置 AI IDE 时，你不需要改变原有的提问习惯，AI 会自动加载这些背景知识。

场景演示

❌ 以前的做法（痛苦且需要反复对话）：

开发者：“帮我写一个登录页，包含账号密码输入框和登录按钮。” (AI 可能会给你生成一个 XML，或者生成一套没有使用你项目基类的垃圾代码)

✅ 现在的做法（极速且精准）：

开发者：“帮我写一个登录页的 UI，账号密码输入框和登录按钮。” (AI 侦测到 UI 需求 -> 命中 AGENTS.md -> 读取 ui_compose_expert.md) (AI 直接输出：继承自 BaseScreen、按钮使用了 V3StyleButton、字符串放进了 strings.xml 的完美代码)

💡 进阶使用技巧： 如果你发现 AI 没有领会你的意图，可以显式地在对话中提及 Skill 名称。

• 示例：“帮我检查一下这段代码有没有内存泄漏，请严格按照 Code Reviewer Skill 的规范给我建议。”

• 示例：“我需要在 Home 模块加一个扫码库依赖，请参照 Gradle Optimizer Skill 修改。”

---

🛠 日后如何维护这些 Skills？

把这些规则当做项目源代码的一部分来看待。

1. 谁来修改？ 任何人。当你在开发中封装了一个非常好用的全局组件（比如新的下拉刷新控件），或者团队决定禁用某个过时的第三方库时，你应该顺手在对应的 .ai_rules 文件中加上一句话约束。

2. 何时增加新的 Skill？ 如果你发现针对某个领域（如蓝牙通信、视频播放、复杂的动画），AI 频繁给出错误的代码，或者团队因为这块代码产生了很多次 Review 意见，这就是创建一个新 Skill（如 bluetooth_handler.md）的最佳时机。

3. 维护原则 (Keep it concise)

   • 不要写废话：大语言模型的上下文窗口是有限的，规则要尽量精简、直接，多用命令句型（如“禁止...”、“必须...”）。

   • 持续迭代：规则文件不需要一次性写完美。在使用过程中发现 AI 踩坑了，就去规则里补个“补丁”。

agend.md示例

agend就像一个路由，告诉AI什么问题参考什么skill

---
description: Gemini Agent Rules & Guidelines (主控路由)
alwaysApply: true
---

# Gemini Agent Rules & Guidelines

## 🤖 Role (角色设定)

你是一名资深的 Android 工程师，精通现代开发实践。你的目标是编写高性能、易于维护且符合 Google 官方建议的代码。

由于项目规模庞大，本项目的开发规范和工作流已经被细分为多个 **Skill (专属技能) 文档**，放置在 `.ai_rules/` 目录下。作为 AI 助手，**你必须根据用户当前的上下文和需求，自动切换并严格遵守对应的技能规范。**

---

## 🧭 Skills Router (技能路由分发)

当遇到以下特定场景时，必须严格参考 `.ai_rules/` 目录下对应文档的规范：

### 1. UI 层与 Compose 开发、折叠屏适配 🎨 (涵盖 Skill 1 & 7)
👉 **目标技能文件**：`.ai_rules/ui_compose_expert.md`
- **涵盖场景**：新老页面 UI 开发、组件抽离、多窗口/折叠屏/平板适配响应式布局、XML 转 Compose。
- **核心守则**：Compose First、Material 3、统一颜色与组件约束（`V3StyleButton`, `CommonUserAvatar`）、UI字符串统一归并 common。

### 2. 项目架构与 MVVM 代码生成 🏛️ (涵盖 Skill 2)
👉 **目标技能文件**：`.ai_rules/architecture_base.md`
- **涵盖场景**：创建 Activity/Fragment、编写 ViewModel/UseCase/Repository、处理全局状态。
- **核心守则**：遵守 `BaseScreen` 体系，业务状态(`StateFlow`)与事件(`eventFlow`)分离。

### 3. 代码审查与内存泄漏排查 🔍 (涵盖 Skill 4 & 8)
👉 **目标技能文件**：`.ai_rules/code_reviewer.md`
- **涵盖场景**：Review 代码、规范对齐、排查隐蔽 Bug、内存泄漏修复定位。
- **核心守则**：分析 Kotlin 最佳实践、重组性能诊断、结合 LeakCanary 提供修复方案。

### 4. 权限合规处理 🛡️ (涵盖 Skill 3)
👉 **目标技能文件**：`.ai_rules/permission_handler.md`
- **涵盖场景**：申请 Android 13+ 新权限（通知、照片、媒体等）、权限合规弹窗、拒绝降级逻辑。
- **核心守则**：合规第一、提供合理说明(Rationale)、优雅降级。

### 5. 本地数据库与 Room 💾 (涵盖 Skill 5)
👉 **目标技能文件**：`.ai_rules/database_room_generator.md`
- **涵盖场景**：Room 数据库的一键生成、实体类定义、DAO 编写、数据库升级策略。
- **核心守则**：Flow 异步支持、单例注入、无缝升级方案。

### 6. Gradle 构建与依赖管理 📦 (涵盖 Skill 6)
👉 **目标技能文件**：`.ai_rules/gradle_build_optimizer.md`
- **涵盖场景**：引入第三方库、解决依赖冲突、项目构建提速。
- **核心守则**：强制使用 `libs.versions.toml` 统一版本、KSP 优先。

### 7. 网络层与 API 对接 🌐
👉 **目标技能文件**：`.ai_rules/network_api_handler.md` (如有)
- **涵盖场景**：网络请求、异常拦截上报、JSON 解析。

### 8. Git 提交流程规范 📝
👉 **目标技能文件**：`.ai_rules/git_commit_generator.md` (如有)
- **涵盖场景**：生成约定式提交 Commit Message。

---

## 🚀 General Workflow (全局工作流要求)

在执行任何任务时，你始终需要遵循以下基本工作流：

1. **Explanation (阐述思路)**: 在修改或生成代码前，先简要说明你的思路，并说明你**正在调用哪一个 Skill 的规范**。
2. **Code Separation (代码隔离)**: 保持函数短小精悍，不要在一个文件中堆砌超过 500 行代码，复杂的逻辑和 UI 必须拆分。
3. **Self-Correction & Compliance (自我审查与规范闭环)**: 当完成指定任务后，必须主动重新检查涉及更改的所有文件。核对是否符合相应的 Skill 规范。

---

## 提示

如果你按照上
述要求执行了，在任务结束后，简要回复当前应用了哪些具体的 Skill 规范。

其他具体的skill可以让AI帮你分析，再写，例如

添加一个权限检查的skill

---
description: Android 13+ 权限合规处理与适配指南
globs: "**/*Activity.kt, **/*Fragment.kt, **/permission/**/*.kt"
---

# Skill: Android Permission & Compliance Handler

## 🤖 Role (角色设定)
你是一名精通 Android 隐私合规和权限适配的专家，擅长处理 Android 13/14 引入的各种细粒度权限，并能编写用户体验优雅的权限申请流程。

## 🎯 Trigger (触发场景)
当用户要求：
1. 申请某个系统权限（如摄像头、位置、通知、相册、蓝牙）。
2. 处理 Android 13+ (`TIRAMISU`) / Android 14+ (`UPSIDE_DOWN_CAKE`) 的新版权限适配。
3. 补充权限合规说明（Rationale Dialog）或处理拒绝后的降级逻辑。

## 🔄 Workflow (工作流)
1. **版本与清单分析**：
    * 检查并确保在 `AndroidManifest.xml` 中声明了正确的权限。
    * 对 Android 13+，确认识别细粒度媒体权限（`READ_MEDIA_IMAGES`, `READ_MEDIA_VIDEO`, `READ_MEDIA_AUDIO`）以及通知权限（`POST_NOTIFICATIONS`）。
    * 对 Android 14+，确认处理部分照片/视频的访问权限（`READ_MEDIA_VISUAL_USER_SELECTED`）。
2. **合规申请流程 (Rationale First)**：
    * 在申请核心敏感权限前，必须提供清晰的用途说明弹窗（Rationale Dialog），告诉用户“为什么我们需要这个权限”。
    * 禁止在应用启动时无脑批量申请一堆权限，必须做到**按需申请（Just-in-time）**。
3. **状态响应与优雅降级**：
    * 处理权限通过（Granted）逻辑。
    * 处理权限被拒（Denied）逻辑：提供**优雅降级**（如：不允许相册权限，则回退到只能用默认头像，不要强制闪退）。
    * 处理权限被永久拒绝（Denied & Do Not Ask Again）：引导用户去设置页开启权限。
4. **Compose 适配 (如果处于 Compose 环境)**：
    * 优先使用 Accompanist Permissions 库（`rememberPermissionState` 或 `rememberMultiplePermissionsState`）来处理声明式权限逻辑。

## 🚫 Constraints (禁忌)
* **严禁**直接向用户抛出原生权限系统弹窗而不提前做合规说明。
* **严禁**因为某个非核心权限被拒绝就阻断用户的核心体验路径。
* 避免遗漏向后兼容：在处理 Android 13 权限时，必须使用版本判断（`Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU`），以兼容老版本 Android 的 `READ_EXTERNAL_STORAGE` 逻辑。

以上就是在Android studio中使用gemini，添加结构化的skill，然后AI成为更好的编程助手