企业官网建设流程全解析

kotlin-footguns 是一套由224 个 Agent Skills组成的Kotlin 实战陷阱知识库，内容全部提炼自 10.8k 星开源音乐 AppSimpMusic的生产级代码——不是来自文档的理论，而是作者在多年发版中真金白银"踩过"的坑：会报成功却丢数据的 API、在某个平台含义完全不同的构建标志、在坏代码上照样通过的验证步骤……每条经验都已附上失败机制与自检方法。

⚠️上方横幅为源项目 SimpMusic 的 GitHub 仓库页头，仅作出处示意。

为什么需要 kotlin-footguns？Kotlin 陷阱为何文档里找不到

大多数 Kotlin / Android 的 Agent Skills 集合是照着官方文档写的，它们告诉你的 AI 助手"API应该做什么"。而 kotlin-footguns 记录的是"真实跑起来时实际发生了什么"：

• 接口返回 200 OK，请求其实已被静默拒绝
• NOT IN子查询遇到一个 NULL，整条 DELETE 悄悄删除 0 行且不报任何错
• 同一个加载标志位，在 Windows 上是"立即解析符号"，在另一平台上变成"把文件当纯数据映射"
• 状态持有器每次事件写 N 次，StateFlow 的合并语义把最终状态颠倒了

这些坑的共同点是：没有报错、测试通过、只在真机或干净机器上暴露。kotlin-footguns 把每条坑的"失败机制 + 替代做法 + 验证命令"沉淀成技能文件，让 AI 编码助手（或人类）在动手前先"免疫"。

224 个 Skills 的完整地图：14 大主题分类

全部技能由 CATALOG.md 逐条索引，覆盖以下分组（A–N 为主批次，Δ6/Δ7 为后续增量挖掘）：

📌 每个条目在目录中都带有一行摘要、主要证据文件和来源通道，方便按需检索。

一个 Agent Skill 的内部结构：Traps 才是主角

每个技能都是一个独立的 SKILL.md（开源 agent-skills 格式，Claude Code 及任何支持该格式的编码助手都能读取，人类也完全可读），遵循统一的纪律：

1. Frontmatter—name+description，描述中直接写明"什么症状出现时该加载这个技能"
2. 简短导向— 正确的工作模式，代码比文字清晰时才给代码
3. Traps（陷阱）— 每个文件的主体章节：具体失败模式、机制成因、替代做法
4. Verifying it（验证）— 可以在你自己代码树上直接运行的命令，逐条证实或排除每个论断

文件刻意控制在60–140 行——两分钟读不完的技能，Agent 就不会加载。几个典型的"名场面"：

• StateFlow 合并颠倒状态：一次事件写多次状态，收集方只看到"最后一次写入"，结果屏幕显示的是上一步的加载态。见 skills/stateflow-conflation-inverts-state/SKILL.md
• NOT IN + NULL 陷阱：子查询里任何一个 NULL 就能让整条语句匹配 0 行且"报告成功"。见 skills/sql-not-in-nullable-trap/SKILL.md
• JNA 原生绑定陷阱：同一个标志数字在 POSIX 与 Windows 上含义完全不同，干净机器上的首次符号查找就会失败。见 skills/jna-native-binding-traps/SKILL.md

这些经验是如何被验证的？五批次对抗式审查

kotlin-footguns 不是一批"写完即发布"的笔记。README.md 披露了它的生产流程：

• 五批次挖掘管道：约 282 个原始候选去重为 224 条，来源包括代码、完整 git 历史、工程文档、博客与网站（原始材料见 raw-core.md、raw-git.md、raw-handlers.md、raw-ui.md 等）
• 对抗式验证：每个批次由独立评审通道接收"只有文件 + 源码树"，任务是反驳而非确认；修复必须附复现证据才被接受
• 命令逐字执行：最终批次中，"Verifying it" 里的每条命令都必须对着源码树原样跑通；字节码反编译、标准库源码、git 历史重放都作为机制证据
• 收尾清扫：全部文件复查标识符泄漏、结构一致性与交叉引用，目录与文件夹双向一一对应

过程记录可在 HANDOFF.md 与 pipeline-handoffs/team-verify.md 中追溯。

如何安装 kotlin-footguns？两种接入方式任选

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

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

仓库更新时插件跟着更新，你"订阅"而不是"复制"。

方式二：任意 Agent 的可编辑文件

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

安装器让你挑选要哪几个技能、给哪些助手安装（Claude Code、Cursor、Codex、Copilot、Windsurf、Gemini 等）。文件以普通 markdown 落入你的仓库，可随意裁剪改写；需要新版时运行npx skills update。

💡 两种哲学：二选一即可——同时装两套会让每个技能出现两遍。另外，每个技能的description决定了它何时进入上下文，所以装 224 个也不贵：只有触发条件匹配时才加载。

如果只是想通读这份工程参考手册，直接克隆仓库浏览即可：

git clone https://gitcode.com/gh_mirrors/ko/kotlin-footguns

kotlin-footguns 适合谁？使用建议清单

上手三步：

1. 打开 CATALOG.md，按症状关键词定位分组
2. 点开对应 skill，先读 Traps 段落，再跑 Verifying it 里的命令核对自己的项目
3. 把相关技能装入你的 AI 助手，下次写同类功能前它会主动"避坑"

总结：一份值得收藏的 Kotlin 实战陷阱清单

kotlin-footguns 的价值在于三点：生产级出处（10.8k 星、2023 年 4 月至今持续发版的四平台音乐 App）、对抗式验证（每条论断可复现，可被反驳的都被修掉了）、人机双可读（既是 Agent Skills 也是工程手册）。整个仓库采用GPL-3.0许可（见 LICENSE）。如果你正被某个"测试全绿却行为诡异"的 Kotlin 问题卡住，先从 CATALOG.md 里按症状找一条技能试试。