maxrave-dev / kotlin-footguns

# 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 in