Oct 29, 2026
用 kotlin-footguns 把 228 个生产环境 Kotlin 陷阱交给你的 Agent
十个领域 skill 加一个扫描器，从一个 10.8k 星的 Compose Multiplatform 音乐应用里挖出来：Kotlin、Compose、Room 和桌面 JVM 在实践中失败的 228 种方式，每一种都配有在你自己代码树上验证的命令。
大多数 Kotlin skill 合集是照官方文档写的，所以它们告诉 agent 的是 API 应该怎么工作。kotlin-footguns 是一个 2k 星的语料库，228 个陷阱从相反的方向写成——作者把 SimpMusic 这个 Compose Multiplatform 音乐应用交付给真实用户多年后，实际发生了什么。
为什么这个 Skill 重要
README 的定位：这里的每一课都比描述它的文档更早存在，先在崩溃报告、失败的发布、评审轮次和用户提的 issue 里付过代价。来源是 SimpMusic，一个自 2023 年 4 月起持续在生产环境运行的跨平台音乐客户端，星数超过 10,800，发布到 Android、Windows、macOS 和 Linux。
陷阱按开放的 agent-skills 格式归入十个领域 skill，再加第十一个 footgun-scan，用来对照陷阱检查一次改动。语料库刻意保持服务中立：任何陷阱文件里都不出现服务名或厂商字段名。
安装
两条路，README 说只选一条——两条都装会让每个 skill 出现两份。作为随仓库更新的托管 Claude Code 插件：
/plugin marketplace add maxrave-dev/kotlin-footguns
/plugin install kotlin-footguns@maxrave
更新通过 /plugin marketplace update maxrave 到达。或者作为任意 agent 可编辑的文件：
npx skills@latest add maxrave-dev/kotlin-footguns
安装器让你挑选要装十一个 skill 里的哪几个、装给哪些 agent——Claude Code、Cursor、Codex、Copilot、Windsurf、Gemini 等。文件以普通 markdown 落在你的仓库里，归你所有；用 npx skills update 拉取新版本。
实战：合并前扫描一次 Compose 改动
来自 README 的十个领域 skill 及其陷阱数：
| 领域 skill | 陷阱数 | 关注点 |
|---|---|---|
desktop-and-build-footguns | 24 | 桌面 JVM 上的原生代码；桌面打包、代码签名、CI 与构建 |
kmp-architecture-footguns | 25 | 多平台模块结构、依赖注入、架构；Kotlin 语言陷阱 |
media-playback-footguns | 33 | 播放器与交叉淡入淡出、音频处理与 DSP、队列、共享收听会话 |
data-layer-footguns | 26 | 规模化的 Room 与 SQL、迁移、仓储层、缓存与分页 |
compose-visuals-footguns | 36 | 主题与颜色、渐变与遮罩、效果与动画、图表 |
compose-screens-footguns | 32 | 页面、导航、自适应布局、组件与交互 |
state-and-background-footguns | 23 | Flow、StateFlow 与 ViewModel 生命周期；后台工作、服务、平台运行时 |
webview-footguns | 3 | 低内存手机和无 WebView 提供者设备上的 WebView：启动、渲染进程死亡、AndroidView 生命周期、cookie |
remote-api-footguns | 17 | 客户端与解析、认证与重试、实时会话与线协议（wire protocol） |
engineering-method-footguns | 9 | 实验、构建日志、提交历史、变更日志、移除一个功能 |
- 照常开发一个 Compose 页面。当任务触及某个领域，agent 加载该领域的索引，看到每个陷阱以及应当把它引向该陷阱的症状，然后只打开适用的文件。
- 提交前用大白话问一句：「检查我未提交的 Kotlin 改动里有没有 footgun。」
footgun-scan用 32 个模式匹配你的改动新增的行；每个模式对应一个陷阱，agent 打开该陷阱来确认或排除每一处命中。 - 读判定。命中标为
likely表示写法有误，除非该陷阱指明的例外成立；标为look表示它标记了一个陷阱要求检查的位置。look命中是要读的地方，不是结论。 - 把同样的扫描接进 CI：
python3 .claude/skills/footgun-scan/scripts/scan.py --base origin/main --fail
在整个 SimpMusic 及其核心模块上，README 报告扫描器给出 26 处 likely 命中，26 处经检查全部与对应陷阱吻合：22 处垂直滑动过渡停留在默认的半高、2 处从 Color.Transparent 淡入到某个颜色、2 处把值直接拼进迁移 SQL。
技巧
- 每个陷阱文件遵循同一套纪律：frontmatter、一段简短的导读、占主体的「陷阱」部分，以及一个「验证」部分——其中的数量以你要运行的命令表达，而不是会过时的数字。文件保持在 60 到 140 行之间。
- 十个 skill 的布局是为上下文预算而设。README 解释，Claude Code 每一轮都会在上下文窗口 1% 的预算内列出每个已装 skill 的名字和描述，2.0 之前每个陷阱各为一个 skill 的布局把预算撑爆了；现在的列表约 2,900 个字符。
- 全部索引汇成一页的是
CATALOG.md，由scripts/build_index.py生成；如果有文件未列入、重复列入或缺失，或者交叉引用指向不存在的陷阱，脚本会报错。 - README 的
evals/里有十三个claude plugin eval用例。装了插件时陷阱题每次运行全部通过；不装时模型平均 0.56，并在四道题上自信地答错——它描述了一条 Room 连接路由规则和一个资源格式化器，而两者都不存在。
何时不用这个 Skill
这个语料库专属于 Kotlin、Compose Multiplatform 和桌面 JVM；它教的是架构和失败模式，从不涉及任何第三方服务的具体机制，所以它不会解释某个厂商 SDK。整个仓库是 GPL-3.0，与源项目一致——把这些文件以 vendored 方式收进许可证不同的代码库之前先核对。README 自己也提醒 look 命中不是结论；把扫描器当作一份阅读清单，而不是替代评审的检查。
查看 排行榜 了解更多 skill。