← The playbook

AI engineering

An AI harness for mobile engineering, from first principles

Point a coding agent at a production mobile codebase with no preparation and you get code that looks fine and isn't. It imports from the wrong module. It does work on the main thread. It falls over on the first rotation. I don't blame the model for any of that. It has never seen your module boundaries, your state pattern or your Gradle tasks, and nothing around it tells it when it's wrong.

The thing around it is what I call the harness: the context it reads, the tools it can call, the checks that run, and the rules the build refuses to bend. When I introduced AI-assisted workflows to my team, switching models barely moved anything. Neither did longer prompts. What moved things was fixing the local feedback loop so the agent could compile, test, render a preview and inspect a device in seconds.

The examples here use Android, Kotlin and Gradle because that's where I've applied this most. The same ideas carry over to iOS: Swift packages and access control for boundaries, SwiftLint and build-phase checks for rules, and Xcode test plans for a fast loop.

Why a backend harness doesn't transfer

Most agents are tuned on web and backend repositories, where saving a file usually kicks off a quick, focused test run and stdout tells you most of what you need. Mobile breaks nearly every one of those assumptions.

ConstraintWeb / Backend repoMobile repoWhat the mobile harness must do
Build & test latencyUsually quick: incremental compiles and focused test runs give feedback fastSlow by default: Gradle configuration, Kotlin compilation, resource processing and dexing add up, and a full APK build on a large app can take many minutesScope Gradle tasks to a single feature slice (:feature-x-ui) with build and configuration caches
Visual & UI feedbackDOM inspection or fast headless browserRequires compiling resources and rendering Compose/ViewsRun JVM screenshot tests (Roborazzi / Paparazzi) on @Preview functions without booting an emulator
Runtime lifecycleStateless request/responseConfiguration changes, background kill, runtime permissionsProvide scripted ADB hooks to simulate rotation, process death, and deep links
Compiler & log outputShort stack tracesThousands of lines of Gradle task logs and unfiltered logcatFilter build output to only compiler errors (e:) and failed JUnit assertions

The verification ladder

If the agent has to build a full debug APK and boot an emulator to find a missing import, one small task eats twenty minutes. So I order the checks from cheapest to most expensive, and each one gates the next.

What the agent sees after a changecheapest check first
./scripts/agent-verify.sh :feature-search
✓ compile :feature-search-ui~4s
✓ unit tests + architecture tests~6s
✓ lint + screenshot previews: light, dark, 1.5x font~12s
○ device flow over ADB (skipped: no navigation or permission change)~40s
PASS: All checks succeeded for :feature-search.
The first three rungs run on the host JVM. The device rung runs only when a change touches navigation, permissions or platform services.

1. One entry point for verification

Left alone, an agent guesses. It runs ./gradlew build or ./gradlew test, kicks off tasks in dozens of modules it never touched, and fills its own context with progress output. I give it exactly one script. It takes a module, runs only what matters for that module, and prints very little.

$agent-verify.shscripts
#!/usr/bin/env bash# Usage: ./scripts/agent-verify.sh :feature-searchset -euo pipefailFEATURE="${1:-}"if [[ -z "$FEATURE" ]]; then  echo "Usage: ./scripts/agent-verify.sh :feature-<name>"  exit 1fiGRADLE_FLAGS=(  "--configuration-cache"  "--build-cache"  "--console=plain"  "--quiet")echo "==> [1/3] Compiling and testing ${FEATURE}-domain and ${FEATURE}-data..."./gradlew "${FEATURE}-domain:test" "${FEATURE}-data:testDebugUnitTest" "${GRADLE_FLAGS[@]}"echo "==> [2/3] Compiling, testing, and verifying previews for ${FEATURE}-ui..."./gradlew \  "${FEATURE}-ui:testDebugUnitTest" \  "${FEATURE}-ui:verifyRoborazziDebug" \  "${GRADLE_FLAGS[@]}"echo "==> [3/3] Running lint and architecture guardrails..."./gradlew "${FEATURE}-ui:lintDebug" ":architecture-tests:test" "${GRADLE_FLAGS[@]}"echo "PASS: All checks succeeded for ${FEATURE}."

This is where modularization pays you back a second time. Because the search feature is split into :feature-search-domain, -data and -ui, the agent never compiles an unrelated feature. With the configuration cache and build cache on, the whole script comes back in under 20 seconds on a warm build.

2. Shrink the logs before the model reads them

A failed Gradle build prints hundreds of lines: task graphs, deprecation warnings, stack frames from inside Gradle. All of it costs tokens and none of it helps. A small filter that keeps only the compiler error lines and the test failure diffs puts the agent's attention on the line that broke.

$filter-gradle-output.shscripts
# Keep only actionable Kotlin compiler errors and test failuresTASK="${1:-:feature-search-ui:testDebugUnitTest}"./gradlew "$TASK" --console=plain 2>&1 | awk '  /^e: /                   { print; next }  /FAILED$/                { print; flag=1; count=0; next }  flag && count < 15       { print; count++; next }  /^FAILURE: Build failed/ { print; flag=1; count=0 }'exit "${PIPESTATUS[0]}"

3. Let it see the UI without an emulator

The hardest part of this on mobile is that the agent is blind. A composable can compile, pass every ViewModel test, and still clip its text, break in dark mode, or overlap a button on a small screen. Booting an emulator for every tweak is far too slow.

Screenshot libraries like Roborazzi and Paparazzi render composables to PNG files on the host machine in seconds:

KSearchScreenPreviewTest.ktfeature/search/ui/src/test/kotlin
@RunWith(AndroidJUnit4::class)@GraphicsMode(GraphicsMode.Mode.NATIVE)@Config(sdk = [34], qualifiers = RobolectricDeviceQualifiers.Pixel7)class SearchScreenPreviewTest {    @get:Rule    val composeRule = createComposeRule()    @Test    fun captureSearchScreenStates() {        val populatedState = SearchUiState(            query = "kotlin multiplatform",            results = listOf(SearchResult("1", "Sharing core logic across Android and iOS")),        )        composeRule.setContent {            AppTheme(darkTheme = false) {                SearchScreen(state = populatedState, onQueryChanged = {}, onRetryClick = {})            }        }        composeRule.onRoot().captureRoboImage("screenshots/search_populated_light.png")    }}

That gives the agent two signals. One is a pixel diff against a golden image. The other is the PNG itself, which a multimodal model can open and check for alignment, contrast and wrapping.

4. Scoped tools for the device

Unit tests and JVM previews cover most day-to-day feature work. The rest needs a running device: deep links, permission flows, camera lifecycle, process death. I don't hand the agent a raw shell and let it guess adb flags. I expose a handful of small, predictable tools through a local MCP server or a helper script.

Device tools exposed to the agenttool names are examples
ui_tree()Dumps the accessibility tree with uiautomator and returns compact JSON: visible text, content descriptions, clickable bounds.
kill_and_relaunch()Sends the app home, kills the process, relaunches. Proves SavedStateHandle restoration works.
app_errors()Reads logcat for your process only, errors only. No system noise.
open_link(url)Fires a deep link and reports launch time and the screen it landed on.
Reading the accessibility tree is faster, cheaper in tokens and more reliable than taking a screenshot after every tap.

5. What stays with the engineer

A harness automates checking. It doesn't automate judgment. Even with a loop under 20 seconds, four things stay with me:

  • Where the module and domain boundaries go. That depends on the roadmap and on how the teams are organized.
  • The threat model. Which data needs hardware-backed encryption, what stays out of backups, how tokens are scoped.
  • How it feels in the hand. Whether a gesture, a transition or a coaching cue is right is something you find out by using it.
  • The harness itself. AGENTS.md, the verify script and the convention plugins are production code, and they change every time an agent trips on something new.