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.
| Constraint | Web / Backend repo | Mobile repo | What the mobile harness must do |
|---|---|---|---|
| Build & test latency | Usually quick: incremental compiles and focused test runs give feedback fast | Slow by default: Gradle configuration, Kotlin compilation, resource processing and dexing add up, and a full APK build on a large app can take many minutes | Scope Gradle tasks to a single feature slice (:feature-x-ui) with build and configuration caches |
| Visual & UI feedback | DOM inspection or fast headless browser | Requires compiling resources and rendering Compose/Views | Run JVM screenshot tests (Roborazzi / Paparazzi) on @Preview functions without booting an emulator |
| Runtime lifecycle | Stateless request/response | Configuration changes, background kill, runtime permissions | Provide scripted ADB hooks to simulate rotation, process death, and deep links |
| Compiler & log output | Short stack traces | Thousands of lines of Gradle task logs and unfiltered logcat | Filter 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.
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.
#!/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.
# 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:
@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.
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.