android-agent-guidelines

Android Agent Discovery & Implementation Guidelines

CRITICAL: All Android agents MUST execute a discovery scan before making ANY implementation decisions. No assumptions. No guessing. Align to what already exists.

---

1. Discovery-First Approach

Before writing code or proposing solutions, run a "Project Fingerprint" scan.

Phase A — Dependency Scan

Scan version catalogs and build files to identify the core tech stack:

# Preferred: check version catalog first

grep -rE "koin|hilt|dagger|room|realm|sqldelight|ktor|retrofit|coil|glide|compose|rxjava|coroutines" gradle/libs.versions.toml

# Fallback: scan build files directly

grep -rE "koin|hilt|dagger|room|realm|sqldelight|ktor|retrofit|coil|glide|compose|rxjava|coroutines" ./build.gradle*

Phase B — Architecture & Pattern Fingerprinting

Identify whether the project is standard Android or KMP, then find existing patterns:

# KMP vs Standard Android

find . -maxdepth 3 -name "shared" -o -name "commonMain"

# Architectural patterns

find . -name "*ViewModel*.kt" -o -name "*Repository*.kt" -o -name "*UseCase*.kt" | head -n 5

# DI modules / components

find . -name "*Module*.kt" -o -name "*Component*.kt" | xargs grep -lE "module|inject|provides"

Phase C — Announce What You Found

After scanning, state your findings to the user before writing any code:

"I've detected this is a KMP project using Compose UI and Koin for DI. I will follow these patterns for the new feature."

Then wait for confirmation before proceeding.

---

2. Library Detection Matrix

Category	Check For	Implementation Strategy
DI	hilt-android, koin-android, dagger	Use @HiltViewModel, by inject(), or @Inject — match what is already in the codebase
UI	androidx.compose, material	Prioritize Compose. Use XML/ViewBinding only if Compose is absent
Async	kotlinx-coroutines, rxjava	Use Flow/suspend for Coroutines; Observable/Single for RxJava
Network	ktor-client, retrofit2, okhttp	Use HttpClient for Ktor; interface + annotations for Retrofit
Persistence	room, realm, sqldelight, datastore	Use @Database/@Entity for Room; Realm.write for Realm; Database for SQLDelight
Image Loading	coil, glide	Use AsyncImage for Coil; GlideImage / Glide.with for Glide
Testing	mockk, mockito	Use mockk<> / every for MockK; mock() / verify for Mockito
KMP	commonMain, expect/actual	Place core business logic and network layers in commonMain