claude-android-ninja

Android Kotlin Compose 开发

上下文层级（先加载较少内容；完整参考资料保持完整）：

1. 此文件（SKILL.md）- 路由、停止规则、示例。
2. 下方列出的 references/*-quick.md - 必需/禁止事项 + 章节链接（约 40 行）。
3. 完整 references/*.md 中的一个目标章节 - 仅代码示例和检查清单。
4. INDEX-sections.md - 仅当快速路由不足时才查看锚点列表。

禁止：当一个章节或快速文件已能满足任务时，不要加载 INDEX-sections.md 或整份数千行的参考资料。

通过快速参考表为任务选择路由。没有匹配项，或任务需要从零搭建时：查看 workflows.md。完整文件列表：INDEX.md。

必需操作：

• **现有项目：**从 assets/ 复制内容前，先阅读 settings.gradle.kts、gradle/libs.versions.toml 和 app 模块构建文件 - dependencies.md、modularization.md。技术栈迁移： migration.md。
• 从零搭建：workflows.md → “Creating a new project?”
• 更改模块、DI、导航、Room 架构或 AGP/Kotlin/KSP 后：运行 ./gradlew help，然后运行 :app:assembleDebug（使用实际的 app 模块名称）- gradle-setup.md。

**仓库外停止规则（不要用仓库编辑来替代）：**Play 上传、轨道、分阶段发布、versionCode - android-ci-cd.md；Play Integrity 前置条件（Console/Cloud 设置）- android-security-quick.md；生产环境中的 adb install / pm clear - testing.md。

快速参考

此处未列出的罕见或小众主题见 INDEX.md（完整文件列表）。

任务	参考
表格中未列出的任务、全新项目初始化、多主题设置	workflows.md
可选的 Android CLI 项目发现、Studio 检查、预览和测试设备检查	workflows.md（“Using the optional Android CLI for agent workflows?”）
所有参考文件的完整索引	INDEX.md
版本目录、固定版本、alpha 策略、存量项目对齐	dependencies.md
添加或更新依赖项（目录别名）	dependencies.md
多模块依赖项	dependencies.md
项目结构和模块	modularization.md
MVVM 层、存储库、DI	architecture.md
Retrofit / OkHttp、NetworkModule、可空 DTO、AuthInterceptor	architecture.md; dependencies.md
DataStore（偏好设置、类型化）、Room 与 DataStore 的使用规则	architecture.md
代码格式化（Spotless、spotlessCheck / spotlessApply）	assets/convention/QUICK_REFERENCE.md; gradle-setup.md
Compose 模式、动态效果、动画、修饰符、稳定性	compose-patterns-quick.md
Paging 3 + Room + 网络（RemoteMediator、远程键、initialize）	compose-patterns.md
无障碍功能、TalkBack、标签文案、实时区域、Espresso 无障碍	android-accessibility-quick.md
通知、前台服务、MediaStyle、画中画、分享面板	android-notifications.md
媒体：API 37 后台播放、Media3、选择器、FileProvider、分享面板	android-media.md
数据同步和离线优先模式	android-data-sync-quick.md
Material 3 主题、间距令牌、动态颜色	android-theming-quick.md
Navigation3、深层链接、应用链接、自适应布局	android-navigation-quick.md
Kotlin 模式、View 生命周期互操作	kotlin-patterns.md
协程模式（StateFlow、Channel、callbackFlow）	coroutines-patterns-quick.md
Gradle、产品变体、BuildConfig、构建性能、R8	gradle-setup.md
代码质量（Detekt 约定插件、CI）	code-quality.md
测试方法（单元测试、插桩测试、Compose UI）	testing-quick.md
国际化和本地化	android-i18n.md
运行时权限、Photo Picker、API 37 位置隐私	android-permissions.md
Kotlin 委托模式	kotlin-delegation.md
崩溃报告（Firebase / Sentry 接口、PII 清理）	crashlytics.md
设计模式（GoF 风格、Room FTS）	design-patterns-quick.md
性能、Play Vitals、启动、重组、卡顿、APA、Perfetto	android-performance.md
受限设备上的 Android 17 QPR2 内存预算（可选）	android-performance.md
调试、Logcat、ANR、Gradle 错误、R8 映射、内存泄漏	android-debugging.md
迁移（XML、RxJava、Navigation、Compose、Room 2→3、API 37、16 KB 原生代码、Compose-XML 互操作）	migration.md; 16 KB 页面大小; Compose-XML 互操作

示例

使用约定插件创建全新的 Android 应用

用户目标：创建一个符合技能技术栈的新仓库。

操作：根据 assets/convention/QUICK_REFERENCE.md，将 assets/settings.gradle.kts.template、assets/libs.versions.toml.template、assets/convention/ 复制到 build-logic/；配置 includeBuild("build-logic")；阅读 modularization.md 和 gradle-setup.md。

结果：根模块、app 模块和核心模块均已创建，并应用了版本目录和约定插件。

新增功能界面（Compose + ViewModel）

用户目标：在功能模块中新增一个流程。

操作：参考 modularization.md 了解模块命名和依赖方向；参考 compose-patterns-quick.md 了解 Screen、状态和副作用；参考 kotlin-patterns.md 和 coroutines-patterns-quick.md 了解 StateFlow 和事件；参考 architecture.md 了解领域层与数据层的边界。

结果：功能模块包含 Screen 可组合项、ViewModel、UiState，且依赖注入与现有图保持一致。

使用 Room 3 和远程 API 构建离线优先列表

用户目标：提供缓存列表并支持网络刷新。

操作：参考 compose-patterns.md 了解 Paging 3 和 RemoteMediator；参考 architecture.md 了解仓库的放置位置；根据 workflows.md（使用数据库），使用 Room 3 和 SQLiteDriver；如需升级，则参考 migration.md。

结果：Room 是唯一数据源，UI 由 PagingData 驱动，或采用指南中的等效模式。

提升目标 SDK / 编译 SDK（例如 API 37）

用户目标：迁移工具链和平台要求。

操作：按照 migration.md 执行迁移；使用 gradle-setup.md 和 dependencies.md 固定 AGP/Kotlin/KSP 版本；根据 workflows.md（迁移到目标 SDK 37）交叉检查 edge-to-edge、媒体和安全性。

结果：提升 compileSdk / targetSdk，并按照迁移文档调整清单、Gradle 配置和功能代码。

故障排除

症状	可能原因	修复
Gradle 同步失败、找不到插件，或版本目录出错	缺少 google() / mavenCentral()、插件 ID 错误，或目录别名不一致	gradle-setup.md；引导初始化时与 assets/libs.versions.toml.template 保持一致
Room 出现 KSP 错误，或 Room 3 构建器因缺少驱动而报错	Room 3（模板版本 3.0.3）要求使用 setDriver(BundledSQLiteDriver())（或项目中的等效实现）	migration.md；modularization.md；architecture.md
@TypeConverter 无法解析，或 DAO 返回类型被拒绝	Room 3 将其重命名为 @ColumnTypeConverter；非 Flow / suspend 返回类型需要 @DaoReturnTypeConverters	migration.md
仅在 Release 版本中崩溃，但类确实列在 seeds.txt 中	AGP 9 的 strictFullModeForKeepRules：-keep class A 不再保留其构造函数	android-debugging.md；gradle-setup.md
升级 Compose、nav3 或 androidx.hilt 后，Gradle 同步立即失败	这些库使用 compileSdk 37 编译，并要求 AGP >= 9.2.0	migration.md；gradle-setup.md
目标版本为 37 时，局域网设备发现或本地 HTTP 调用无提示地失败	需要 ACCESS_LOCAL_NETWORK，或使用无需权限的 NsdManager 选择器	android-permissions.md；migration.md
后台音频无声，且没有异常	API 37 音频加固——缺少 MediaSession 或 mediaPlayback FGS	android-media.md
Compose 运行时警告存在不稳定 / 可跳过的重组	参数类型不稳定，或状态持有方式不正确	compose-patterns-quick.md；android-performance.md；kotlin-patterns.md
Release 构建崩溃、出现 ClassNotFoundException，或缺少 R8 规则	代码缩减移除了反射或 JNI 入口点	android-debugging.md；gradle-setup.md
没有证据却声称存在 ANR 或卡顿	对主线程或测量结果的假设	在更改架构之前，先查看 android-performance.md 或 Perfetto