kotlin-footguns

By maxrave-dev — creator and maintainer of SimpMusic, the 10.8k-star cross-platform music app every lesson in this repository was mined from.

228 battle-tested traps mapping the footguns of Kotlin, Compose Multiplatform and desktop JVM development, packaged as ten agent skills plus a scanner that checks a change against them. Mined from a production codebase, not written from documentation.

The traps are grouped into ten area skills in the open agent-skills format, readable by Claude Code and any coding agent that understands the format — and just as readable by a human. Each area skill is an index of its traps; each trap is a standalone markdown file the agent opens when the work in front of it matches. The corpus is 28,000+ lines across 228 files, and in most of them the largest section is Traps: the specific ways a technique fails in practice, each paired with a way to verify the failure and the fix on your own tree.

Why this repository exists

Most agent-skill collections for Kotlin and Android are written from official documentation. They tell an agent what the API is supposed to do. This repository records what happened when its author shipped against those APIs for years: the API that reports success while discarding your data, the build flag that means something different on one platform, the verification step that passes on broken code, the migration that deleted the wrong thing first.

None of it is theory. Every lesson here is older than the document that describes it — each one had already been paid for in crash reports, failed releases, review rounds and user-filed issues before it was written down.

Where the lessons come from

The source is SimpMusic, a cross-platform music client built with Kotlin and Compose Multiplatform, in continuous production since April 2023. As of this writing it has earned more than 10,800 GitHub stars and 550 forks, and ships to real users on Android, Windows, macOS and Linux through GitHub releases, F-Droid, IzzyOnDroid and OpenAPK.

That codebase spans territory most sample projects never touch: a native media engine bound over JNA, dual-player crossfade and DSP chains, a Room database at real-user scale, desktop packaging and code-signing for three operating systems, CI that builds all of it, and a UI written entirely in Compose. The traps are the distillation of that surface area.

The corpus itself is deliberately service-neutral. The traps teach architecture and failure modes, never the mechanics of any third-party service; no service names or vendor field names appear in any trap file. What was learned integrating specific services survives here as the generic core that applies to whichever API you are consuming.

What is inside

Area skill	Traps	Focus
desktop-and-build-footguns	24	Native code on the desktop JVM; desktop packaging, code signing, CI and build
kmp-architecture-footguns	25	Multiplatform module structure, dependency injection, architecture; Kotlin language traps
media-playback-footguns	33	Players and crossfade, audio processing and DSP, queues, shared listening sessions
data-layer-footguns	26	Room and SQL at scale, migrations, repositories, caching and paging
compose-visuals-footguns	36	Theming and colour, gradients and scrims, effects and animation, charts
compose-screens-footguns	32	Screens, navigation, adaptive layout, components and interaction
state-and-background-footguns	23	Flow, StateFlow and ViewModel lifecycles; background work, services, platform runtime
webview-footguns	3	WebView on low-RAM phones and provider-less devices: startup, renderer death, AndroidView lifecycle, cookies
remote-api-footguns	17	Clients and parsing, auth and retries, realtime sessions and wire protocols
engineering-method-footguns	9	Experiments, build logs, commit history, changelogs, removing a feature

Each area skill lists its traps under headings, each with the description that tells an agent when to open it. The whole index on one page is CATALOG.md. An eleventh skill, footgun-scan, checks code against the traps (below).

Why ten skills and not 228

Until version 2.0 every trap was its own skill, and the set crowded out everything else in the agent's skill listing. Claude Code lists every installed skill's name and description on every turn, inside a budget of 1% of the context window (8,000 characters for a 200K-token window), and lists whatever does not fit by name alone, least-used first. The 224 descriptions came to about 124,000 characters and the names alone to 7,500, so at that budget every trap reached the agent as a bare name, and so did every other skill the user had installed, their own included.

As ten area skills plus the scanner the listing is about 2,900 characters. The agent loads an area's index when the work touches that area, sees every trap in it at once with the symptom that should send it to each one, and opens only the files that apply.

Scanning a change

footgun-scan turns the traps into a check. It matches 32 patterns against the lines a change adds; each pattern is tied to one trap, and the agent opens that trap to confirm or dismiss every hit. Ask for it in plain words ("check my uncommitted Kotlin changes for footguns"), or run the script yourself, fo