Kotlin Footguns 技能库
把生产音乐 App 中踩过的 228 个 Kotlin、Compose Multiplatform 与桌面 JVM 陷阱，做成可被编码 Agent 直接加载的技能。
- Star 数
- ★ 1.9k
- 最近更新
- 7 天前
- License
- GPL-3.0
- 主语言
- Python
- FA 评分
- 50/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 兼容但需适配Codex · Claude CodeChatGPT · Claude.ai（部分支持）
- 费用
- 免费，无需付费服务
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 使用 Claude Code 或 Cursor 写 Compose Multiplatform 界面，想避免渐变、scrim、动画参数等视觉细节踩坑的个人开发者。
- 不适合
- 不使用 Kotlin / Compose / JVM 桌面技术栈的团队
- 期待开箱覆盖任意语言或框架的通用代码审查者
- 需要厂商长期 SLA 与托管服务的团队
- 源码审查
- 50/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
这个仓库是一个面向编码 Agent 的纯 Markdown 技能库，主题是 Kotlin、Compose Multiplatform 与桌面 JVM 开发中的真实陷阱。语料共 228 个陷阱文件、超过 28,000 行，按领域拆成十个区域技能（desktop-and-build、kmp-architecture、media-playback、data-layer、compose-visuals、compose-screens、state-and-background、webview、remote-api、engineering-method），外加第十一个扫描技能 footgun-scan。每个区域技能是一份索引，列出该领域陷阱及其触发描述；Agent 只在当前工作触及该领域时加载索引，再打开真正相关的单个陷阱文件，从而把常驻上下文压到约 2,900 字符。每个陷阱文件结构固定：frontmatter、简短说明、篇幅最大的 Traps 段落（具体失败方式、成因、替代做法），以及一节「Verifying it」给出可在你自己代码库上执行的验证命令。footgun-scan 自带 scan.py，用 32 条模式匹配一次变更新增的行，命中项分为 likely 与 look 两类，并可接入 CI。安装有两条路径：Claude Code 插件市场安装只读受管套件，或用 npx skills 把可编辑的 Markdown 复制进你自己的项目，供 Claude Code、Cursor、Codex、Copilot、Windsurf、Gemini 等使用。
仓库主体是 skills/ 目录下的十一个技能，每个区域技能都是 SKILL.md 索引加若干独立陷阱 Markdown 文件。Agent 在每一轮只看到十一个简短描述；当任务落入某个领域时加载该区域的 SKILL.md，看到其中每个陷阱的触发症状，再按需打开对应文件。陷阱文件给出机械成因、修复方式，以及一节「Verifying it」，内含直接针对你代码库运行的命令（例如统计迁移或资源用法），而不是会过期的数字。footgun-scan 技能随附 .claude/skills/footgun-scan/scripts/scan.py，脚本用 32 条模式（每条绑定一个陷阱）扫描变更新增行，可在 CI 中用 python3 .claude/skills/footgun-scan/scripts/scan.py --base origin/main --fail 运行，命中后由 Agent 打开相应陷阱确认或排除。scripts/build_index.py 负责从每个陷阱自身的 description 重建区域索引和 CATALOG.md，支持 --check 校验，并检测未列出、重复列出、缺失文件与失效交叉引用。evals/ 目录保存十三个 claude plugin eval 用例，分别在有插件和无插件条件下对比。
- 使用 Claude Code 或 Cursor 写 Compose Multiplatform 界面，想避免渐变、scrim、动画参数等视觉细节踩坑的个人开发者。
- 维护 KMP 多模块工程、需要 Room 迁移和仓库/缓存层出错概率更低的后端或数据层工程师。
- 为桌面 JVM 应用做三平台打包与代码签名、希望提前知道 CI 与构建配置陷阱的发布负责人。
- 在 CI 中加入 footgun-scan，对每次 PR 新增的 Kotlin 行做定向检查并阻止已知失败模式的团队。
- 不想依赖 Agent、只想读一份从真实生产项目提炼的 Kotlin/Compose 工程参考的工程师。
- 需要在本地或私有仓库中保存并改写技能文件的团队，用 npx skills 复制后按自身代码库裁剪。
如何安装或部署这个 Agent？
方式一，作为 Claude Code 插件安装（受管只读，随仓库更新）：
/plugin marketplace add maxrave-dev/kotlin-footguns
/plugin install kotlin-footguns@maxrave之后用下面的命令拉取更新：
/plugin marketplace update maxrave方式二，用 skills CLI 把可编辑技能文件复制进你自己的项目（可选 Claude Code、Cursor、Codex、Copilot、Windsurf、Gemini 等）：
npx skills@latest add maxrave-dev/kotlin-footguns后续更新：
npx skills update两种方式只选一种，同时安装会让每个技能出现两次。运行 scan.py 需要 Python 3；使用 npx 安装路径需要 Node.js。
如何使用这个 Agent？
在支持技能格式的 Agent 中用自然语言触发，例如让它检查未提交的 Kotlin 改动是否命中陷阱。也可以自己运行扫描脚本，当作 CI 步骤：
python3 .claude/skills/footgun-scan/scripts/scan.py --base origin/main --fail命中分两类：likely 表示除非该陷阱列出的例外成立，否则写法就是错的；look 表示陷阱建议检查的位置，需要人工或 Agent 阅读确认。修改或新增陷阱后重建索引：
python3 scripts/build_index.py只想校验而不写入时加 --check：
python3 scripts/build_index.py --check这个 Agent 有哪些优点和局限？
- 语料源自持续生产三年多的 SimpMusic（10.8k+ stars），陷阱来自真实故障而非官方文档转述。
- 按十个区域技能分层加载，常驻上下文约 2,900 字符，避免了 228 个独立技能挤占 Claude Code 的 1% 技能列表预算。
- 每个陷阱都带「Verifying it」小节，给出可在自己代码库运行的命令，可验证而非只读劝告。
- footgun-scan 把陷阱转成 32 条可执行模式，能直接接入 CI 并作为失败的检查步骤。
- 同时提供 Claude Code 插件与 npx skills 两条安装路径，且全部为纯 Markdown，无 Agent 也能当工程参考阅读。
- 公开了十三组带插件/不带插件的 eval 对比结果，并说明模型本就掌握或自信答错的情况。
- 领域严格限定在 Kotlin、Compose Multiplatform、Android 与桌面 JVM，对其他技术栈无价值。
- 扫描器只有 32 条模式，覆盖的是形状明确的片段，漏报与误报需靠 Agent 打开陷阱文件人工判定。
- 索引与 CATALOG.md 由脚本生成，手工编辑会被覆盖，新增陷阱必须遵守文件命名与 frontmatter 约定。
- README 的验证流程（多轮对抗式复核、逐条命令复跑）针对作者自身工作流，其他团队难以复现同等质量门槛。
- 插件更新依赖作者的 marketplace，另一条路径需要 Node.js 与 npx，两条路径并存容易重复安装。
这个 Agent 与同类方案有什么区别？
README 未点名任何同类技能集合或 Kotlin 静态分析工具，仅与「按官方文档编写的 Kotlin/Android Agent 技能」这一泛化做法对照，故不做具体产品比较。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Kotlin Footguns 技能库 当前 | 50 · 缺口较多 | Agent 插件 / 技能免费 | ★ 1.9k | 7 天前 | Python | Codex · Claude Code |
| Aurite Agent Verifier | 52 · 缺口较多 | Agent 插件 / 技能免费 | ★ 44 | 23 天前 | — | Codex · Claude Code |
| Argot 仓库风格审查器 | 93 · 表现优秀 | 命令行工具免费 | ★ 52 | 2 个月前 | Rust | Claude Code |
| Jev Review | 81 · 表现良好 | Agent 插件 / 技能免费 + 模型费 | ★ 248 | 1 个月前 | TypeScript | Codex · Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
仓库主体是 Markdown 技能与一个 Python 扫描脚本，README 说明扫描器只读取变更行并匹配 32 个模式，未声明网络访问、凭据读取或破坏性默认行为，因此权限面看起来较小；但仅凭 README 无法核实脚本实际行为，且安装方式涉及 npx skills 与 /plugin marketplace 两类第三方分发通道，其数据流与更新机制未在仓库内说明，故各项仅给 1。source_attribution 相对较好：README 明确作者、来源项目 SimpMusic、GPL-3.0 许可，并声明 custom-shuffle-order 改编自 Auxio 并保留出处，故给 2。
README 对技能数量、陷阱数量、索引生成脚本 build_index.py 的一致性检查（未列出、重复、缺失、交叉引用失效即失败）有较具体描述，内部叙述基本自洽，给 2；但依赖项（npx skills、claude plugin eval、skills.sh 徽章）的可用性与版本未在仓库内固定或说明，失败信息方面只提到扫描器区分 likely/look，未展示脚本的错误处理，故各给 1。
README 清楚界定受众（Kotlin/Compose Multiplatform/桌面 JVM 开发者及编码代理）、场景（十个领域技能加扫描器）、触发方式（按领域索引加载、按描述匹配陷阱），并说明为何从 228 个技能合并为十个以适配上下文预算，边界与触发精度描述较充分，给 2；但未提供针对不同代理环境的适配细节或降级方案，未给 3。
信息架构清晰（CATALOG.md、十个领域索引、统一陷阱文件结构、生成脚本），安装说明给出插件与 skills CLI 两条路径并提示不要同时安装，命名规则（frontmatter name 与文件名一致）明确，许可为完整 GPL-3.0 文本，均给 2；示例与 FAQ 仅有零散命令示例、无独立 FAQ，已知限制只提到上下文预算与扫描器 look 非结论，版本与变更日志仅在正文提及 v2.0 而无 CHANGELOG 文件，维护责任虽有作者自述但发布者身份未经注册表验证，故各给 1。
产出为可直接被代理加载的 Markdown 陷阱文件与可运行的扫描脚本，README 给出具体命令与 likely/look 语义，输出可用性给 2；相对官方文档的边际价值在于生产环境失败模式与验证命令，叙述有说服力但属自述，给 2；成本方面强调每轮仅十一条描述进入上下文、按需加载，成本收益论证合理，给 2。
README 声称每条陷阱附“Verifying it”命令、机制主张经反汇编与源码复核、命令逐字执行，并指向 evals/README.md 的对照表，具备可追溯的设计，但本次仅提供 README 与 LICENSE，无法核对具体陷阱文件、评估表或脚本，故 claim_traceability 给 1；交叉印证仅依赖作者自述与外部徽章，无独立来源，给 1；文中区分了“仅来自散文的主张会被标注”，体现事实与推断分离意识，但无法在证据中验证执行情况，给 1。
- 本次仅提供 README 与 LICENSE，未提供任何陷阱文件、CATALOG.md、evals/README.md 或 scan.py，README 中关于 228 条陷阱、评估结果与验证流程的主张均无法在静态审查中核实。
- 安装依赖 npx skills 与 /plugin marketplace 等第三方分发通道，其更新与数据流机制未在仓库内说明，部署前应自行审查。
- 扫描脚本的实际行为（是否仅读取变更行、是否访问网络）无法从所给证据确认，建议在隔离环境先行审阅后再用于 CI。
- 发布者身份未经 FollowAgents 注册表验证，维护责任与更新路径仅来自作者自述。
- GPL-3.0 为传染性许可，将技能文件并入自有项目或产品时需评估合规影响。