企业官网建设流程全解析

kotlin-footguns 是一份由真实生产环境反推的Kotlin 陷阱清单：224 条经过实战检验的 agent skills，覆盖 Kotlin、Compose Multiplatform 与桌面 JVM 开发的坑，全部挖矿自一款运营多年、跨 4 端上线的音乐应用 SimpMusic——不是照着官方文档写的，而是照着事故报告写的。

为什么"照着文档写"还会翻车

大多数 Kotlin / Android 技能合集都是从官方文档出发的：它们告诉你 API"应该"做什么。而 kotlin-footguns 记录的是另一类知识——当你真的拿这些 API 发货多年之后，会发生什么：

• 报告成功、却悄悄丢掉你数据的 API
• 在不同平台上含义完全不同的构建标志
• 在坏代码上也能"通过"的验证步骤
• 先把不该删的东西删掉的迁移脚本

每一条经验都比描述它的文档更老：在写下来之前，它们已经用崩溃报告、失败的发版、评审轮次和用户 issue 付过一遍学费。

3 个真实战报，感受一下坑有多深

以下案例全部出自 skills/ 目录，每一条都附带可在你代码树上复现的验证命令。

① SQL 里"删了个寂寞"—— skills/sql-not-in-nullable-trap/SKILL.md：一条播放列表清理语句用了NOT IN (子查询)，由于子查询列存在NULL，三值逻辑让整张外表零行匹配。删了 0 行、零报错、零日志——直到有人发现清理一直没生效。修复只要加一个IS NOT NULL，但前提是你知道该去怀疑它。

② "应用已损坏，无法打开"—— skills/macos-codesign-sidecar-strip/SKILL.md：macOS 归档会把扩展属性写成._*伴随文件。它们在签名之前落进 app bundle，签名器就会把它们一并封入清单；用户解压时系统又删掉了这些文件——于是签名校验报"密封资源缺失"，应用被判损坏。构建机永远复现不了，因为构建机跳过了触发删除的那一步。

③ 一个字符字面量编译不过—— skills/combining-chars-break-char-literals/SKILL.md：Kotlin 的Char精确地等于"16 位 Unicode 码元"。带组合记号的字符在编辑器里看起来是一个字母，实际是 2 个Char，'x'字面量直接编译失败；任何以Char为 key 的查表都会撞上这堵墙。

还有更隐蔽的：StateFlow 合并语义让写入顺序变成正确性问题（skills/stateflow-conflation-inverts-state/SKILL.md），activityViewModels与activityViewModel差一个字符就是两个实例（skills/koin-viewmodel-scoping-traps/SKILL.md）。它们的共同点是失败无声：不报错、不崩、不崩日志，只有数据和状态悄悄错位。

224 条 skill 的完整目录：14 个分组速览

全部条目的一行索引在 CATALOG.md，按主题分为 14 组（A–N）外加 2 个增量批次（Δ6、Δ7）：

💡 新手建议从D（播放引擎）和E（数据库 / SQL）两组读起——那是最尖锐、市面上最少见的材料，也是作者团队自己写的第一批。

解剖一条 skill：为什么"陷阱"才是正文

每条 skill 都是独立的一个 skills/<name>/SKILL.md 文件（全库 224 个文件、27000+ 行，单文件控制在 60–140 行——两分钟读不完的内容，代理不会加载进上下文），统一遵循 4 段纪律：

1. Frontmatter——description同时写清覆盖范围、触发场景和错误症状，代理靠它判断何时该加载这条 skill；
2. 简短的方向说明—— 正确的做法（working pattern），代码比文字清楚时就用代码；
3. Traps—— 文件的主体：具体的失效方式、机械成因、以及该怎么做才对；
4. Verifying it—— 一组可以在你自己的代码树上直接运行的验证命令，用来证实或排除文件里的每个论断。

拿"changelog 当战报写"这条（skills/changelog-as-war-story/SKILL.md）来说：它教的不是格式，而是四要素——症状、机制、被排除的方案清单、退出条件，并给出 6 条 grep / git 验证命令，其中一条专门用来检查"谁在拿计划当既成事实记录"。

质量保障：每条结论都被"对抗性"推翻过

这份语料不是"写一遍就发"。提取跑的是五批流水线，没有任何文件以初稿状态发布：

• 每个批次由独立的对抗性验证通道评审——评审者只拿到文件和源码树，永远拿不到作者的推理过程，且被要求反驳而不是确认；
• 后期标准进一步收紧：每条"Verifying it"里的命令都必须逐字在源码树上执行，无法复现的结论本身就是缺陷；机制性论断要用字节码反编译、stdlib 源码、git 历史重放重新推导；
• 仅最后两个批次，对抗评审就累计提出约 30 个阻塞级发现——包括"在缺陷代码上也能通过的验证步骤"和"治不了它所点名案例的修复方案"，全部修复或反驳后才发布。

完整的挖掘计划与验证交接记录见 pipeline-handoffs/（如 team-plan.md、team-verify.md），原始挖掘素材在 raw-docs.md、raw-git.md、raw-core.md 等文件中。

一键安装：给 AI 代理或人类都适用

仓库是只读的，以下两种方式选一个即可（两个都装会出现 224 条 skill ×2）：

方式一：Claude Code 插件（订阅式，自动更新）

/plugin marketplace add maxrave-dev/kotlin-footguns /plugin install kotlin-footguns@maxrave

更新跟仓库走：/plugin marketplace update maxrave。

方式二：任意代理，可编辑的 markdown 文件

npx skills@latest add maxrave-dev/kotlin-footguns

安装器让你从 224 条里勾选要哪几条、给哪些代理（Claude Code、Cursor、Codex、Copilot、Windsurf、Gemini 等）装。文件以普通 markdown 落进你的仓库，归你所有、随手可改；想更新时再跑npx skills update。

更省事的用法是什么都不装——每条 skill 的description已写明触发条件，skill 只在任务匹配时才进入上下文，所以装得再多也不占日常开销。而因为文件本身就是 markdown，直接当工程参考读也完全没问题。

文件地图与许可

• 完整索引：CATALOG.md —— 每条 skill 一行，附主要证据来源
• 项目说明：README.md
• 挖掘交接文档：HANDOFF.md 与 pipeline-handoffs/
• 原始素材：raw-docs.md · raw-git.md · raw-core.md · raw-handlers.md · raw-ui.md
• 许可：GPL-3.0（与来源项目一致）；其中custom-shuffle-order一条改编自 Auxio 的 GPL-3.0 洗牌实现，文件内附出处说明

官方文档教你 API"应该"做什么，kotlin-footguns 告诉你它"实际"做过什么。如果你正准备开工 Kotlin 或 Compose Multiplatform 项目，把这份生产事故战报清单放在手边，比读完一遍官方文档更不容易踩坑。