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.

224 battle-tested traps mapping the footguns of Kotlin, Compose Multiplatform and desktop JVM development, packaged as nine 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 nine 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 27,000+ lines across 224 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