Android Dev Playbook

> 🌐 繁體中文（canonical） · English mirror

Android Development Judgment Handbook

Core Principles

1. A green light on a debug build does not count: R8, obfuscation, signing, and backend environment flags only take effect in release — changes on the release path must be verified with release-grade builds.
2. State flows down, events flow up: the UI layer makes no business decisions; a Composable holds no mutable business state.
3. The lifecycle is the default enemy: for any long-lived object holding a Context/View, first assume it will leak, then prove it won't.
4. Reflection is R8's blind spot: for every class constructed via reflection (Gson/Moshi/Retrofit models), change the keep rules in lockstep when the class changes — otherwise it's a release-only bomb.
5. No IO on the main thread, no GlobalScope for coroutines — there is no exceptional case worth discussing.

Kickoff Routing

| Situation | Path | Read first | |-----------|------|-----------| | New screen/feature | Define the state owner and data flow first, then write the UI | references/architecture-state.md | | UI jank, excessive recomposition | Don't touch the UI first — inspect the state design | references/compose-ui.md | | Async, Flow, lifecycle issues | Check collect location and scope choice | references/coroutines-lifecycle.md | | Add/change API model (Gson/Moshi/Retrofit) | Change implementation + keep rules together | references/release-checklist.md §R8 | | Ship release / change build config | Run every item on the mandatory checklist | references/release-checklist.md | | Crashes only in release, fine in debug | Assume minify/obfuscation/environment flags first, don't guess | references/release-checklist.md |

Red Lines (Absolutely Forbidden)

• Never declare release-related changes done after verifying only with a debug build — minify, keep rules, and BuildConfig flags all have zero effect in debug.
• Never GlobalScope.launch — the lifecycle is uncontrolled; it keeps running after the screen is destroyed, causing both leaks and crashes.
• Never make network/DB calls in the body of a Composable function — it fires again on every recomposition; use LaunchedEffect or push it down into the ViewModel.
• Never let a ViewModel hold a reference to an Activity/Fragment/View — rotating the screen leaks it immediately; if you need a Context, use the Application-level one.
• Never catch and only log without notifying the caller — the user sees a spinner that never stops; errors must become UI state.
• Never change test assertions to turn CI green — two red runs in a row is a wrong-direction signal; back up to the previous decision point.

Failure Signals (Back Up, Don't Retry)

| Symptom | Usually means | Back up to | |---------|---------------|-----------| | Fix recomposition in one place, another place janks | State placed at the wrong layer, granularity too coarse | Rethink the state-owner design | | Piling on more remember / derivedStateOf just to stop flicker | Upstream is passing an unstable object as state | Check the stability of the incoming parameters | | Fix one keep rule for a release crash and the next one pops | Patching class by class; keep the whole model directory instead | R8 rule layer | | More and more null checks inside lifecycle callbacks | Holding a reference you shouldn't | Ownership design | | Same ANR persists after three different rewrites | Hidden synchronous IO on the main thread | Find the real blocking point before touching anything |

references Index

• references/architecture-state.md — layering criteria, which layer state belongs in, UDF positive/negative examples. Read before touching architecture or adding a feature.
• references/compose-ui.md — when to extract a Composable, stability and recomposition, side-effect API choice. Read before writing UI.
• references/coroutines-lifecycle.md — scope/Dispatcher choice, Flow collect location, typical leaks. Read whenever you touch async.
• references/release-checklist.md — R8/keep, build variant, signing, permissions, item-by-item sign-off before publishing. Mandatory before shipping a release.
• references/test-scenarios.md — the judgment test set, to verify whether the model taking over actually follows the playbook. Do not give it to a model that is executing.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tienenwu
• Source: tienenwu/fables
• License: MIT

Install and usage instructions live in the source repository linked above.