一份 AGENTS.md，让 Android AI 代码规范率飙升

一份 AGENTS.md，让 Android AI 代码规范率从 60% 飙升到 95%

一、从一个所有 Android 开发者都在踩的坑说起

现在用 Cursor、Trae 或 Copilot 写 Android 代码，你一定遇到过这种高血压场景：

项目明明全用 Jetpack Compose 梭哈了，AI 却突然给你手写了一个 findViewById；或者在 Kotlin 协程 里，它顺手写了个 Thread.sleep() 甚至疯狂用 !! 强解空指针。

AI 的编程能力很强，但它不知道你团队的规矩。它就像一个技术精湛、却没看过你们公司任何开发文档的"天才实习生"。

在 Web 前端，大家用 .eslintrc 管代码风格。而在现代 Android 提效流派中，我们只需要在项目根目录加一个文件：AGENTS.md。

5 分钟配置它，让 AI 彻底按你的规矩写 Android 代码。

---

二、核心机理：AI 接收上下文的决策链路

为什么引入一个 Markdown 文件就能带来质变？我们来看一下 AI 在没有和有约束情况下的决策差异：

代码段

graph TD
    A[用户输入: 帮我写一个用户卡片] --> B{检查根目录}
    
    B -->|无 AGENTS.md| C[依赖大模型公共训练集库]
    C --> D[混合了Java/XML/Compose等各种旧语法]
    D --> E[输出大杂烩代码 规范率 ~60%]
    
    B -->|存在 AGENTS.md| F[强制将规范载入 System Prompt 顶层]
    F --> G[严格限定: Kotlin + Compose + Hilt 规则]
    G --> H[输出符合团队规范的现代代码 规范率 ~95%]
    
    style E fill:#ffcccc,stroke:#333,stroke-width:2px
    style H fill:#ccffcc,stroke:#333,stroke-width:2px

---

三、没有 AGENTS.md vs 有 AGENTS.md

我们用 Android 开发中最经典的真实场景，看看有无规范的降维打击。

场景：写一个用户信息展示卡片

• ❌ 没有 AGENTS.md 时，AI 写的"大杂烩"代码：

  Kotlin

  @Composable
  fun userCard(userId: String) { // 错误 1：函数名未大驼峰
      var user: User? by remember { mutableStateOf(null) }
  
      // 错误 2：在重组（Recomposition）路径中裸写异步请求，导致无限循环死拉数据
      Thread { 
          val response = ApiClient.getUser(userId)
          user = response
      }.start()
  
      Column(modifier = Modifier.padding(16.dp)) {
          Text(text = user!!.name, color = Color.Blue) // 错误 3：硬编码颜色，强解空指针引发崩溃
      }
  }

• ✅ 有了 AGENTS.md 后，AI 写的现代规范代码：

  Kotlin

  // ui/profile/UserCard.kt
  @Composable
  fun UserCard(
      userId: String,
      viewModel: ProfileViewModel = hiltViewModel(),
      modifier: Modifier = Modifier // 规范 1：首位接收可选 Modifier
  ) {
      // 规范 2：通过感知生命周期的 Flow 收集状态
      val uiState by viewModel.uiState.collectAsStateWithLifecycle()
  
      LaunchedEffect(userId) { // 规范 3：副作用逻辑正确隔离
          viewModel.loadUserProfile(userId)
      }
  
      when (val state = uiState) {
          is UiState.Success -> {
              Column(modifier = modifier.padding(MaterialTheme.dimens.paddingMedium)) {
                  Text(
                      text = state.user.name,
                      color = MaterialTheme.colorScheme.onBackground // 规范 4：使用主题色
                  )
              }
          }
          // ... handle Loading & Error
      }
  }

---

四、手把手教你编写 Android 的 AGENTS.md

一份合格的 Android AI 规范文件，必须包含以下 5 个核心章节 。直接复制以下内容，保存为 AGENTS.md 放入你的 Android 项目根目录（与根目录的 build.gradle.kts 同级）即可：

Markdown

# AGENTS.md - Android Development Guide

## 第一章：技术栈声明
- 本项目为现代 Android 应用（100% Kotlin）
- 最小支持版本：MinSDK 26 (Android 8.0)，目标版本：TargetSDK 34
- 异步与流处理：Kotlin Coroutines + Flow
- UI 方案：Jetpack Compose (拒绝 XML 布局)
- 架构规范：MVVM (ViewModel + Repository)
- 依赖注入：Hilt

## 第二章：目录结构规范
app/src/main/java/com/company/project/
├── data/               # 数据层（model/、remote/、local/、repository/）
├── ui/                 # UI 层（按业务功能模块分包，如 home/、profile/）
│   └── theme/          # 全局 Compose 主题、颜色、字体配置
└── di/                 # Hilt 依赖注入 Module 目录

## 第三章：编码硬性约定
- 所有 Composable 函数必须以大驼峰命名（PascalCase）。
- 暴露给 UI 的 ViewModel 状态必须是不可变的：
  private val _uiState = MutableStateFlow(UiState())
  val uiState = _uiState.asStateFlow()
- 列表展示必须使用 LazyColumn/LazyRow，且必须显式提供唯一的 key。

## 第四章：Never 规则（最高禁令，具备最高解释权）
- Never 在 Activity/Fragment 中编写任何业务逻辑。
- Never 使用双感叹号 `!!` 强解空指针，必须使用 `?.let` 或 `?:`。
- Never 在 Compose 样式中使用硬编码的 Color 值（如 Color(0xFF123456)），必须使用 MaterialTheme.colorScheme。
- Never 混用 XML 视图和 Compose，除非在重构旧组件时明确说明。
- Never 修改自动生成的 build/ 目录及 Hilt 编译生成的类。

## 第五章：协作与 Git 规范
- Commit 格式规范：type(module): description (例如: fix(home): 修复首页商品列表下拉刷新崩溃问题)
- 类型限于：feat, fix, refactor, chore, style

---

五、进阶：基于踩坑驱动的"Never 规则"状态演进

AGENTS.md 不是一成不变的文档，而是一个随着 AI 犯错而持续进化的活体协议。它的生命周期表现为以下状态机：

代码段

stateDiagram-v2
    [*] --> 初始基础规范: 建立核心架构/技术栈
    初始基础规范 --> AI执行编写: 喂给 Cursor/Trae 运行
    AI执行编写 --> 完美通过: 代码合规，直接合入
    AI执行编写 --> 触发新幻觉: 写出Bug或不合规代码(如硬编码)
    触发新幻觉 --> 修复代码并总结: 人工介入纠偏
    修复代码并总结 --> 追写Never规则: 将禁止项追加至 AGENTS.md
    追写Never规则 --> AI执行编写: 规则升级，再次拦截同类错误

通过这种"踩坑 -> 喂养规则 -> 免疫"的闭环，AI 将越来越懂你的项目。

---

六、📈 团队落地效果数据

这套规范在 Android 团队实际抽样运行 3 周后，数据反馈非常直观：

指标	没有 AGENTS.md	有 AGENTS.md	趋势变化
AI 代码架构遵循率	~55%	92%+	⬆️ 提升 37%
因硬编码/强解引发的编译失败率	~35%	< 5%	⬇️ 降低 30%
单次功能 Review 及修正时间	~10 分钟	~1.5 分钟	⏱️ 缩短 85%

---

七、❓ 常见问题（FAQ）

Q1：AGENTS.md 应该放在哪个目录下？

必须放在项目的根目录 （和根目录的 build.gradle.kts、settings.gradle.kts 平级）。Cursor、Trae、Claude Code 等 AI 工具在索引项目时，会自动扫描根目录并常驻这一份上下文。

Q2：Android Studio 自带的 Copilot 能识别吗？

可以。现在的各大主流 AI 插件不仅会读取 .github 或 .prompts，也会默认扫描根目录下的 Markdown 规范。如果想 100% 确保生效，在使用对话框（Chat）时，可以手动输入 @AGENTS.md 作为上下文引用。

Q3：如果我们项目还在用 XML 和 纯 Java，这个模板怎么改？

完全适用，你只需要改掉"技术栈"和"编码规范"。

例如在 Never 规则里写上：- Never 使用 Kotlin 特性、- 所有 View 绑定必须使用 ViewBinding，禁止使用 findViewById。AI 就会立刻退回到老兵模式为你写出极规范的 Java 代码。

Q4：团队里每个人习惯不一样，要强行统一吗？

团队共享的底线规范（如架构、Never 规则）提交到 Git。如果你自己有特定的编码小癖好（比如喜欢用特定的注释风格），可以在根目录创建一个 AGENTS.local.md 并加入 .gitignore。AI 会同时读取公有规范 and 你的私有偏好。

Q5：这份文件需要写多长？后面怎么维护？

初版控制在 50~80 行 效果最好，太长了 AI 会抓不住重点。

最好的维护方式是"踩坑驱动" ：每次 AI 写出一段让你高血压的代码，你改完后，顺手往 AGENTS.md 的 Never 规则里加上一条。两三次迭代后，这个 Agent 就会被你训得服服帖帖。

---

八、💡 总结与对照

为了方便快速对齐核心逻辑，我们可以用这张表格看清引入前后的核心变化：

关注维度	传统野生 AI 开发模式	拥有 AGENTS.md 的现代模式
AI 角色定位	懂技术的"野生实习生"	熟读项目 WIKI 的"常驻主力"
代码风格控制	靠人类用 Prompt 每次重复提醒	靠根目录常驻文件建立全栈免疫
异常拦截机制	编译报错或 Code Review 时人工纠偏	"Never 规则"从源头直接熔断幻觉
团队协作成本	每个人都要去纠正 AI 的输出习惯	一人踩坑追加规则，全队 AI 自动升级

与其每次在 AI 生成错误代码后去痛苦地重构和纠偏，不如提前花 5 分钟给它制定好不可逾越的"法律"规矩。

在 Android 开发中，由于历史包袱重、技术更迭快，AI 极易迷失在旧时代的语法泥潭里。一份 AGENTS.md 带来的轻量化自然语言约束，就像一个高效的过滤网 和指挥棒。它不增加任何编译成本，却把一个"野生大模型"驯化成了"最懂你项目架构的资深 Android 专家"。5 分钟配置，换来的是整个团队开发效率的成倍攀升。