Claude Code is a terminal-based coding agent that works well with Kotlin and Android when you give it a precise CLAUDE.md and a tight review loop. This guide covers setup, prompts, common tasks, testing, and running multiple agents for Jetpack Compose, Gradle, coroutines, JUnit, and Espresso projects.
Where Claude Code earns its keep in Android codebases
Claude Code reads the whole Gradle project including build.gradle.kts, libs.versions.toml, and source set directories. It can run gradlew tasks and parse compiler, test, and lint output. Android code has many conventions: Compose state hoisting, ViewModel scopes, coroutines, Hilt, data binding, and version catalogs. Claude Code handles cross-file refactors that would take hours manually, such as renaming a repository interface across all modules, updating test fixtures, or converting a screen from XML to Compose. It is not a replacement for Android Studio, but it is a fast pair programmer in the terminal when you use plan mode and small diffs. However, it needs explicit instructions because Gradle tasks are slow, instrumented tests require an emulator, and Compose previews sometimes fail without a device context.
Handing Claude Code a useful CLAUDE.md
Create a CLAUDE.md in the project root. The file is read when you start claude. It should list build, test, lint commands, module layout, dependency versioning, and Kotlin- or Android-specific rules. Keep it short and actionable; long files dilute the agent’s attention.
# CLAUDE.md
## Build and test
- Build: ./gradlew assembleDebug
- Unit tests: ./gradlew testDebugUnitTest
- Instrumented tests: ./gradlew connectedDebugAndroidTest
- Lint: ./gradlew lintDebug
## Project layout
- Single app module `app`, feature modules in `features/`
- UI in `app/src/main/java/.../ui/` with Compose
- ViewModel in `.../viewmodel/`
- Coroutines use `viewModelScope` and `Dispatchers.IO` for data sources
- Tests: unit tests in `src/test`, instrumented Compose tests in `src/androidTest`
## Rules
- Target SDK 35, minSdk 24, Kotlin 2.0, Compose BOM 2024.09.03
- Use version catalog `libs.versions.toml` for dependencies; do not add versions in build.gradle.kts
- Follow official Kotlin style: trailing commas, named arguments for Compose previews
- Never modify generated files in `build/`
- For Compose UI tests, use `createAndroidComposeRule<MainActivity>()` and `onNodeWithTag`; avoid hardcoded sleep
- When changing coroutine code, always add or update a unit test with `runTest`
## Common tasks
- To add a feature screen, create UI, ViewModel, and tests following existing patterns in `features/home/`
- Refactor with `git diff` before and after; keep changes smallStart the agent with claude in the project root. If you have multiple modules, add a one-line note about each module’s responsibility. Avoid putting generated boilerplate in CLAUDE.md; the agent can read build files itself. Update the file when you add a module or change lint rules.
A repeatable review loop for Kotlin changes
The loop that works best is: plan, small steps, run tests, review the diff. Use plan mode so the agent proposes files and commands before editing. Then make one change at a time, run the unit tests, and check the git diff. For Android, run unit tests first because instrumented tests need a device. Then run Gradle lint.
Example prompts:
- Add a Compose screen that shows a list of users from a repository using StateFlow and collectAsStateWithLifecycle. Include a ViewModel and unit tests.
- Refactor this ViewModel to use viewModelScope instead of GlobalScope, and add runTest tests for the two main state transitions.
- Fix the failing Espresso test in HomeScreenTest. Analyze the failure from the connectedDebugAndroidTest report and suggest a minimal change.
- Migrate this module from XML layouts to Compose for the detail screen only. Keep the existing ViewModel and data layer unchanged.
- Review the current diff for Kotlin and Android issues, run unit tests, and report before changing anything.
After the agent responds, do not accept blindly. Check for common mistakes: using Dispatchers.Main in tests without a rule, forgetting to import Compose preview annotations, or adding dependencies outside the version catalog. Use git diff to review only what changed.
Strong Kotlin tasks and the pitfalls to audit
Claude Code is strong at mechanical Kotlin refactors, updating Compose UI, writing test data builders, and converting XML to Compose. It can also diagnose Gradle sync issues if you paste the error.
| Task | What to ask | Watch for |
|---|---|---|
| Refactor ViewModel state | Partition into a UiState data class and expose a single StateFlow | Avoid introducing unnecessary flows or losing one-shot events |
| Compose screen from spec | Create composables with previews and stable parameters | The agent may use unstable params, causing recomposition; check with layout inspector |
| Test migration | Convert JUnit4 tests to Kotlin and runTest with a MainDispatcherRule | Do not let it use GlobalScope or real dispatchers in tests |
| Gradle dependency update | Bump a version in libs.versions.toml and run lint | It may update multiple dependencies at once and break transitive compatibility |
| Fix lint errors | Apply suggestions for UnusedMaterial3ScaffoldPaddingParameter or similar | Avoid adding global suppressions; fix the actual issue |
Watch closely when the agent edits Gradle version catalogs, because it may bump multiple dependencies at once and break transitive compatibility. Compose code needs structure: stable values, immutable models, and state hoisting; the agent may generate code that compiles but recomposes excessively. For coroutines, ensure it does not use GlobalScope or blocking calls in composables. Android-specific generated files like R class or BuildConfig are off-limits; tell the agent never to edit them. Instrumented tests can be flaky; do not let the agent add sleeps to fix races.
Running JUnit, Espresso, and lint through the agent
Use the agent to run tests after each change. Unit tests run with ./gradlew testDebugUnitTest; for coroutine code, use runTest and a MainDispatcherRule. Instrumented tests run with ./gradlew connectedDebugAndroidTest and require a running emulator or device; check adb devices. For Compose UI tests, use createAndroidComposeRule and onNodeWithTag or semantics matchers, not sleeps. Have the agent inspect reports under app/build/reports/ and fix failures. Lint: ./gradlew lintDebug before commit. The agent can also add CI-like verification by running the same commands. But be explicit: do not run connected tests if no device. Use unit tests for ViewModel and repository logic; reserve Espresso for critical navigation and UI flows. If the agent claims a test passed, ask it to paste the command output or the report path.
Parallel agents with AgentVera for Android repos
AgentVera runs Claude Code and other CLI agents side by side in real terminals. For Kotlin and Android work, the most useful features are git worktrees so one agent can refactor Compose while another migrates tests without overwriting each other; automatic code review after each turn, which catches coroutine and recomposition mistakes with file:line links; and token budgets that stop runaway Gradle iterations before they burn quota. Checkpoints also allow undoing a bad ViewModel change with one click. For details on running multiple Claude Code agents, see How to run multiple Claude Code agents in parallel.
Bottom line for Kotlin and Android teams
Claude Code becomes a reliable Kotlin and Android pair programmer when you invest in a good CLAUDE.md, keep changes small, and verify with Gradle tests and lint. Use plan mode for risky refactors, and consider AgentVera for parallel worktrees and automatic review. The terminal agent cannot replace Android Studio for visual previews or device debug, but it saves time on repetitive code and test writing.